Designer implementation of AnswerAndPlay

Build the Project#

Create the Project#

1. Open the Designer and Create a new project:

2. Create a project named "AnswerAndPlay":

3. When creating a new project, the Designer will prompt you to name first script and to select a triggering event for that script. For this example we will just go ahead and keep the default script name 'script1', but we are going to select a specific triggering event. For this application select the 'Metreos.CallControl.IncomingCall'event:

Handle 'OnIncomingCall'#

Developing applications in the CUAD is an exercise in implementing handlers for various generated events. When you add new triggers or actions to your CUAD application, the Designer automatically inspects those triggers and actions and determines which events need to be handled.

These events will appear as 'tabs' above the Designer's canvas. To implement handlers for these events, you click on a tab and drag into the canvas new actions to be executed.

The first, and for now only event, we have in this application is the 'OnIncomingCall' event. This is the event that is associated with the 'Metreos.CallControl.IncomingCall' trigger that we specified at application creation.

We must now handle the 'OnIncomingCall' event:

1. Click on the 'OnIncomingCall' tab to highlight a canvas for this event:

2. When we receive a new incoming call, the first thing we want to do is to answer it. To implement answering a call, we need to drag an 'AnswerCall' action from the 'Toolbox' onto the canvas for 'OnIncomingCall'.

Find the "Call Control" section in the 'Toolbox'. You may need to expand the window.

Click and hold AnswerCall and drag AnswerCall onto the canvas. The Designer will automatically connect the Start node to the new AnswerCall action.

About Variables#

The actions on the Designer canvas need to have options set to have any effect. For the AnswerCall action, we need to tell the action which call to answer (since many calls could be incoming at one time).

To tell the AnswerCall action which call to answer, we need to pass to the AnswerCall action the "CallId" of the incoming call.

Argument passing in Designer is done through variables. There are three types of variables:

• Script variables
• Event variables
• Local variables

The OnIncomingCall event carries with it the value of the incoming call CallId. To capture this value and pass it to the AnswerCall action. We need to create a local variable in the event handler for the CallId. Once we have the CallId in a local variable we need to set the CallId parameter of the AnswerCall action to read the 'callId' from this variable.

Passing OnIncomingCall-CallId to the action AnswerCall#

Saving OnIncomingCall-CallId as local variable callId#

1. The first thing we need to do is to reveal the Variable Tray in the Designer Canvas. To reveal the Variable Tray, click on View -> Variable Tray in the Designer menu.

2. Now that the Variable Tray is revealed, we can add a new variable. To add a new variable, move the cursor to the variable tray and right-click and select add new item. Set the name of the new variable to callId.

3. To initialize the value of the new local variable callId to the event variable CallId, move the mouse to the properties frame. For the new callId variable click on the drop-down select button next to InitializeWith and select the event variable CallId.

The variable callId is now initialized. Now it can be used by the AnswerCall action.

Passing local variable callId to AnswerCall#

1. To pass a local variable to the AnswerCall action, first click on AnswerCall. When you have selected it the icon will have a green box around it.

2. Selecting AnswerCall will bring up the properties of AnswerCall in the properties frame in the lower right-hand corner of the Designer. The very first parameter under the Action Parameters set in AnswerCall is the parameter CallId. To bind the CallId parameter to the callId local variable expand the CallId parameter by clicking on the + to the left of CallId. This will open the properties for the parameter. For the User Type set the property to variable. For the VAR name select callId.

Adding a Play action#

We are now ready to add a Play action to the OnIncomingCall event handler.

1. Find the Media Control group in the tool box:

2. Drag the Play action onto the canvas. Notice that when the Play action is dropped onto the canvas, two new events are added to the project: OnPlay_Complete and OnPlay_Failed. We will need to implement handlers for these events shortly.

Passing control from AnswerCall to Play#

Now that we have a Play action, we need to indicate how program flow moves from the AnswerCall action to the Play action. In Designer, this is done by connecting the actions together with a directed line.

To connect the AnswerCall action to the Play action, move your cursor to the AnswerCall icon. When your cursor approachs the center of the icon a 'dot' will appear in the center of the icon and your cursor will turn into a 'hand' insert hand icon here. Once your cursor has become a 'hand', click and drag the cursor from the AnswerCall action to the Play action.

There will now be a line from the AnswerCall action to the Play action labeled default. This means that once the AnswerCall action completes, the default conditional-step is to invoke the Play action.

Hmm, that is probably not quite what we want. The real world is messy and prone to failure. We cannot assume that every time the script answers an incoming call that the call will connect and someone will be on the other side. What we should probably do is to only pass control to the Play action if the AnswerCall action completes and returns a Success state.

To do that we need to change the meaning of the line between AnswerCall and Play to only pass control on Success rather than by default.

To change the line, click on the default label. A drop-down will appear. Select the Success label.

Now we have to handle the non-Success condition. If the AnswerCall does not succeed, all the script should do is terminate. To tell the script to terminate, we add an EndScript action to the event handler.

To add an EndScript action find the Application Components section of the Toolbox:

Then drag the EndScript action to the canvas underneath the AnswerCall action and then connect the AnswerCall and EndScript actions.

Configuring the Play action#

Now lets configure the Play action to play the desired prompt.

The Play action requires at least two pieces of information to execute successfully: 1. the connection to play media onto, and 2. the media to play.

Like the CallId parameter to AnswerCall, the ConnectionId parameter for Play needs to be passed to the Play action through a local variable. But there is no local variable the corresponds to the connectionId yet... so lets create one.

Saving connectionId as a local variable#

When AnswerCall completes successfully a new connection identified by a unique ConnectionId is defined. This ConnectionId is available as a Result Parameter of the AnswerCall action. To use this parameter in other actions, we need to save the ConnectionId result parameter into a local variable. We need to modify the AnswerCall action to do this.

1. The first thing we need to do is to create a new local variable to hold the connectionId. Right-click on the Variable Tray and select Add New Item. Name the variable connectionId but do not initialize it.

2. Next click on the AnswerCall icon in the canvas. Move your cursor to the properties box in the lower right-hand side of the Designer and scroll down to the Result Data section of the box until you reach the ConnectionId parameter. Click once in the field to the right of the ConnectionId parameter to reveal the drop-down icon and then click on the drop-down icon to reveal the variable selection list. Select the connectionId variable.

Passing connectionId to Play#

Now that connectionId is defined as a variable, we can set the ConnectionId action parameter for the Play action. Click on the Play icon in the canvas and then associate the ConnectionId parameter with the connectionId local variable.

1. You will need to first change the default type of the parameter from literal to variable. To do this expand the properties of the ConnectionId parameter. On the User Type property, click on literal and in the dialog select variable as the new User Type.

2. Now bind the ConnectionId action parameter to the connectionId local variable.

Setting the Prompt in Play#

Now let's specify what to actually play when the call is answered by the application. The Play action has the ability to play both static media files (.WAV) as well as generate dynamic media using the CUME's embedded Text-to-speech engine.

We will discuss adding static media later, for now let's have the application speak the words: "Hello World" to the caller.

To do this select the Action Parameter named Prompt1. It should be immediately below the ConnectionId action parameter in the Play Properties box.

Click into the text-field to the right of the parameter name and type the string Hello World.

The Play action is now configured.

Handling exit conditions of the Play action#

When we wired up the Play action to AnswerCall we created two paths for the application flow. The first path was from AnswerCall to Play when AnswerCall succeeded and the second path was to an EndScript action if AnswerCall was not sucessfull.

Similarly we need to now handle the exit conditions of the Play action. However, unlike AnswerCall, the Play action is an asynchronous action. When Play is called what is really happening is a play request is being issued by the CUAS to the CUME. If the request is accepted, then some time after being accepted, actual media streaming will be initiated by the CUME to the specified ConnectionId. We know that Play is an asynchronous action because when we dropped Play onto the canvas, two new event handler functions were initialized: OnPlay_Complete and OnPlay_Failed. These event handler functions are also visible as annotations on the Play icon in the canvas.

So to properly handle the exit conditions and events that Play generates we need to understand that there are really several possible outcomes to the Play action:

• Play action completes successfully indicating that the play request was received and accepted by the CUME
• Play action fails indicating that the play request was rejected by the CUME or failed to be delivered
• OnPlay_Complete event is raised indicating that the CUME has completed the requested media streaming to the ConnectionId
• OnPlay_Failed event is raised indicating that the media streaming to the ConnectionId failed to complete or initiate.

For the first two conditions, we need to add actions to the OnIncomingCall event handler function and sequence them after the Play action, similar to what we did for the non-success condition of AnswerCall. For the last two conditions, we need to implement the OnPlay_Complete and OnPlay_Failed event handler functions.

Lets finish what needs to be done in OnIncomingCall first and then we can move on to the other event handler functions.

Play action success#

If the Play action succeeds, it means that the play request to the CUME was delivered successfully. When that happens the OnIncomingCall event handler function is done. To implement this correctly we need to add an EndFunction action on Success of Play. Select Application Components in the Toolbox and drag an EndScript action onto the canvas and place it to the right of the Play action and link them together with a Success wire.

Play action failure#

If the Play action does not succeed, it mean the play request to the CUME was rejected or otherwise failed to be delivered. When this happens we need to hangup on our caller and terminate the application. To hangup we need to add a HangUp action on non-success of play and then after Hangup and EndScript action to terminate the application.

1. From the Call Control section of the Toolbox drag a Hangup action to the canvas.

2. Connect the default condition from Play to Hangup

3. Drag an EndScript action from the Application Components section of Toolbox onto the canvas.

4. Connect the default condition from Hangup to the new EndScript action.

Configure Hangup#

Like Play and AnswerCall the Hangup action needs to be configured. Hangup needs to know the CallId that should be terminated.

Since we already have a local variable with this information, callId, all we have to do is to select the Hangup icon in the canvas and bind the CallId Action Parameter to the callId local variable.

As with the ConnectionId parameter in the Play action, you will need to first set the User Type of the parameter to variable before you can bind the callId variable.

A note on Designer Coding Style#

Instead of adding a second EndScript to the OnIncomingCall event handler function, it is also possible to directly link the Hangup action to the same EndScript action that the non-success condition of AnswerCall flows to:

This is perfectly legal, but in the opinion of the CUAE engineering team is not recommended as a coding style. The recommend orientation of Designer functions is to advance program flow from left to right and to handle exception conditions from top to bottom. This is purely our convention and by no means implies any sort of religous truth, merely our convention. Other teams are quite happy with different conventions.

Handle 'OnPlay_Complete'#

When the CUME completes it media streaming, it will raise an OnPlay_Complete event. The application needs to handle this event by hanging-up the call and terminating the script.

To handle this event, start by clicking the OnPlay_Complete tab on the canvas.

This event handler function will be much simpler than the OnIncomingCall handler. The only thing this function needs to do is to Hangup and EndScript.

So lets add a Hangup action and a EndScript action to this function and wire them up.

Now all we need to do is pass the correct CallId to the Hangup action and this event handler function is complete.

Because OnPlay_Complete is a new event handler function, it does not have access to the local variables we defined in the OnIncomingCall event handler function. Furthermore the OnPlay_Complete event does not have any knowledge of the CallId. The event only knows about the ConnectionId because the event is a consequence of the Play action and not the AnswerCall action or the Metreos.CallControll.IncomingCall trigger.

So before we can complete the OnPlay_Complete event handler function, we need to define a global variable in our main script script1 and then set that global variable in the AnswerCall action. Once we do this then we can reference the global variable in our Hangup action in the OnPlay_Complete event handler function.

Define the global variable g_callId#

1. To define a global variable select the script1 tab in the canvas.

2. Right-click on the variables folder and select Add New Item

3. Set the name of the variable to g_callId

Note:

On variable naming it is the CUAE engineering team convention to prefix global variable names with a 'g_'.

Initialize the global variable g_callId#

Now that the variable g_callId is defined, it needs to be initalized.

1. Select the OnIncomingCall event handler function and click on the AnswerCall action.

2. Now bind the AnswerCall Result Data property CallId to the global variable g_callId.

Configure OnPlay_Complete's Hangup#

Now that the global variable has been defined and initialized, we can complete the configuration of the OnPlay_Complete's Hangup action and complete the event handler function implementation.

1. Go back to the OnPlay_Complete handler function and select Hangup.

2. Change the User Type attribute of the CallId property of Hangup to variable and then bind the g_callId variable to CallId.

OnPlay_Complete is now complete.

Handle 'OnPlay_Fail'#

The OnPlay_Fail event is handled exactly link the OnPlay_Complete event. So for this implementation, lets just copy-n-paste the actions from OnPlay_Complete into OnPlay_Fail.

1. Select the OnPlay_Complete event handler function.

2. Click on the canvas and drag a selection box around the Hangup and EndScript actions. Use Ctrl+C or the Edit->Copy menu to copy the selection into the buffer.

3. Select the OnPlay_Fail event handler and use either Ctrl+V or Edit->Paste to paste the buffer into the canvas.

4. Wire the Start node to the Hangup action.

OnPlay_Fail is now complete.

Other Events 'OnRemoteHangup'#

During the execution of the test application the script has the ability to process known provider event triggers. In the case of this application, the event trigger that we need to process is RemoteHangup.

• To add the event to the script:

1. Select the script1 tab
2. Drag the "RemoteHangup" event from the "Toolbox - Call Control" item list and under the "Events and Functions" folder on the canvas"
3. Finalize the "OnRemoteHangup" function for the RemoteHangup event by adding an "EndScript" action to the function and connecting the start with a branch condition connector to the "EndScript" action.

Build & Deploy the Application#

Prior to building and deploying the application, configure the "Connectivity" options between the CUAD and the CUAS.

• Select "Tools -> Options -> Connectivity" from the top menu
• Enter the IP address and username / password for the CUAE server, then save the change.

To both build and deploy the application, select "Build -> Deploy" from the top menu (to Build without deploying, select "Build -> Build Project").

Note

The status of the build and deployment is displayed in the "Ouput" pane at the bottom of the CUAD. In the case that this is not you first deployment to the CUAE server you will be present with a pop-up prompt to select "Upgrade" or "Reinstall".

To view the status of the application in the CUAE Admin console. Log into the CUAE management console and select applications from the menu list.

Adding A Trigger#

• Select "Applications -> Find/List Triggers" to generate a list of applications and their associated triggers.
• Select the application "AnswerAndPlay" in the list.
• Enter "to" and the number that will be used to trigger the application. Select "Add Parameter".

Running the Application#

You should now be able to run the program by calling the specified trigger above.