The Problem
In a UCCX script, there exists a nice Prompt operator called the Prompt Substitution Operator. Its intended purpose, as I read it to be, is to attempt to queue a Prompt for playback, and if that fails, then attempt to queue a second Prompt for playback instead.
The example given in the documentation is as follows:
For example the main prompt could represent a TTS prompt which in cases where the system has not be en installed or licensed with TTS support, one would want to fallback to a pre-recorded prompt. In this case, queuing a TTS prompt would fail and the substitute would be used instead.
Source:
The problem is that the substitution only happens for very specific circumstances, one of which is Prompt Not Found. However, what about prompts that meet other criteria, such as: Prompt length too short? As is the case when silencing a prompt from a Prompt Management script.
Which, if you didn't know, at the time of this writing, there is no only one way (REST API) to delete a Prompt from a script, causing a Prompt Not Found exception. The API was introduced in UCCX 10.0. Therefore, unless you're on UCCX 10.0, the only option we have to us is to overwrite the Prompt, which in my case, I do with the smallest possible valid WAV file UCCX will play. I have written about that special file before, if you wanted to learn more. You may choose to do it another way, such as pressing the mute button on the recording phone, and then terminating the recording step with # (pound/hash/octothorpe) to create a short and silent file.
And there may be other criteria you are interested in, but I am mainly interested in: Prompt Not Found and Prompt Length Too Short.
The Solution
The solution is to use something called a Prompt Template. A Prompt Template is basically a text file full of Java code (Enhanced, Premium and IP-IVR only) that evaluates to either a Prompt directly, or to some other type that can be converted into a Prompt. E.g., A Document.
Here is my Prompt Template, which I use, to replace the Prompt Substituion Operator, enhancing my scripts to also handle Prompt Content Length Too Short exceptions.
Prompt Template File: play.tpl (Attached as play.zip)
/* ==========================================================================
This Prompt Template will validate if a requested Prompt to be played is
both found in the repository and does not have a content length equal to
the silence is golden Prompt.
The silence is golden Prompt is the smallest possible g711ulaw wav file
supported by UCCX with a payload size of 0, for a total file size of 56B.
The template takes two arguments:
1. A requested Prompt to be played back
2. A default Prompt to play if the requested Prompt is not valid
========================================================================== */
(Prompt requested_prompt, Prompt default_prompt) {
// Initialize the local variable which will hold the content length of
// the silence is golden wav file
long silence_is_golden_length = 56L;
// Initialize the local variable which will hold the contents of the
// requested Prompt.
Document cache = DOC[];
// Initialize the local vairable which will hold the content lenthd of
// the requested Prompt.
long cache_length = 0L;
// Initialize the local variable which will hold the resulting Prompt
// from the outcome of this function.
Prompt given_prompt = P[];
// Attempt to work with the requested Prompt as if it were valid.
// If an Exception is thrown, catch it, then use the default Prompt.
try {
// Casting the requested Prompt to a Document is a way to check if
// the Prompt exists within the Prompt repository
cache = (Document) requested_prompt;
// At this point, the Prompt exists
// Get its content length value.
cache_length = cache.getContentLength();
// Compare its content length value to that of silence is golden.
if (cache_length > silence_is_golden_length) {
// Its content length is greater than that of silence is golden.
// We'll use the requested Prompt.
given_prompt = requested_prompt;
} else {
// Its content length is less than or equal to that of silence
// is golden. We'll us the default Prompt.
given_prompt = default_prompt;
}
} catch (Exception e) {
// Something went wrong reading the requested Prompt.
// Use the default Prompt.
given_prompt = default_prompt;
}
// Return the outcome of this function to the script.
return given_prompt;
}
The Sub Problem
The reason I have attached it as a ZIP archive is an interesting one. If you were to try an upload the TPL file directly into UCCX's Prompt Management Web Interface, you will be met with an error message like the following:
Why are you scolded for trying to upload a perfectly valid file to the repository? Well, here's the JavaScript embedded in the page that decides to shame you in front of your cube mates:
if( opener.document.form1.promptFolders.value != 'Root Folder' && (pFileExt!= '.wav' && pFileExt!='.zip' )) {
alert('File name does not have a valid extension. Only .wav files can be uploaded');
document.FORM1.file1.focus();
return false;
}
Now we can see that the only valid extensions are .wav and .zip, despite there being three other valid extensions as described in documentation.
The extension of the prompt file can be omitted in which case the search looks at all supported extensions (<.wav>, <.ssml>, <.tts>, <.tpl>) in order until one is found.
Source:
The Sub Solution
I have actually addressed this issue with a working solution on UCCX version 7x. I don't recall where, why, when, who, or how I was prompted to solve this problem, but the solution I had at the time was to modify the client side JavaScript as can be seen in a YouTube video I made of the process.
There is actually a much simpler solution though, one that I overlooked two years ago as I created that video. As Occam's razor would have it, this solution is one I would recommend to you.
Are you ready? It's so simple. You may have already guessed it.
You ZIP the TPL file, and then upload the ZIP file. Simple right? I know, I slapped myself on the forehead when I realized it.
EDIT: I just discovered another way. You use the Upload Prompt step within a script to upload the TPL to the repository. I'd still recommend the ZIP file option, as there is still a challenge with getting your TPL file contents into the script in the first place. One option is to save it in the Document repository first, then upload it with the Upload Prompt step to the Prompt repository. The Document repository does not prohibit the TPL file extension.
Back to the Solution
Ok, now that we have that out of the way, here is how you use the Prompt Template in your script. Actually, before I show you that, let's take a look at how the Prompt Substitution Operator looks.
If you hadn't seen this syntax before, it basically means: "try to play first_choice.wav and if you can't then play second_choice.wav"
It's actually quite nice. Think about a retail chain of 150 stores where there's a default set of prompts for all stores, but if a store chooses to be more specific or stray from the norm, then they can simply upload their store prompt as first_choice.wav. For those stores who wish to use the default, they simply do nothing and allow the Prompt Sub'ing to work its magic.
But again, with a Prompt Management solution built on solid UCCX scripting, we cannot delete prompts, only overwrite them. Here is how you use the Prompt Template I provided to account for the Prompt Content Too Short scenario.
Let's break it down...
Play Prompt
You should already know that this is the Step name. Nothing special here.
--Triggering Contact--
You may even know this is the default reference to the Contact created for the caller. It could be something different, but it's not messed with very often outside of Call Back scripts and Trigger Application steps.
P[String, Prompt, Prompt]
This is where it gets tricky. The P[] on the outside is the User Prompt literal syntax. Inside of it are three arguments:
- The first one is the Prompt Template Name.
- The second is your first choice Prompt
- The third is your second choice Prompt
"play"
Your Prompt Template Name. I named my Prompt Template "play.tpl" If you rename yours or create others, be sure to change this value to reflect the real name of the file. File extensions are optional as noted above.
P[first_choice.wav]
This is just a User Prompt literal. It could be a System Prompt (SP[welcome.wav]) a TTS Prompt (TTS[Hello CSC]) or anything else Playable. This works the same as the Prompt Substitution Operator.
P[second_choice.wav]
This is exactly the same as the first choice prompt, and works the same here as it does in the Prompt Substitution Operator.
The Conclusion
Prompt Templates are a powerful tool for abstracting the Prompt selection process from the script. It keeps your script code short and clean, while providing powerful, reusable code for your whole system.
The Challenge
I challenge the community to create an even better Prompt Substitution Operator replacement out of Prompt Templates. What about wrong encoding of the WAV file given the System Parameter setting? I.e., UCCX is set to G729 and the Prompt is G711.
I challenge Cisco to the following:
- Enhance the Prompt Substitution Operator to include handling of more Exceptions
- Enhance the web interface to allow uploading of all five Prompt file extensions: .zip, .wav, .tpl, ssml, and .tts
- Enhance the Documentation around Prompt Templates. It took me about 4 hours and a lot of trial and error to figure this out.
Please accept my apology jaysyoung. I missread the DP[0], being in the same sentence as BIN[], as being BIN[0].
Technically, DP[0] should work, since the Engine plays it without error, but in reality it creates an empty wav file once saved and a prompt exception is thrown.
However, if you do a DP[1], it does create a valid wav file, unfortunately it's 852B. So far my 56B file is the smallest valid wav file possible. Of course, I'm not going to argue that a 1 millisecond silent file is way too large to put into production. That would be silly. I'm just in it for the science!
I appreciate our chat. Reply anytime.