Designer implementation of HttpInitiatedP2PCallBridge

Create the project#

Create a new project#

1. Launch the CUAE-developer tool.

2. Select the File -> New Project option and enter the Project Name and Location in the "New Application Deisnger Project" form.

Define a new application script and the triggering event#

While creating a new application, the CUAE developer tool will prompt you to name the first script of the application and a triggering event for that script. For HttpInitiatedP2PBridged application we'll name the first script as "script1" and we'll select the triggering event named "Metreos.Providers.Http.GotRequest"

Adding Installer#

In this application we need to use an installer. To add an installer to the project we need to R-click on the root project directory. Then select Add Installer->New Installer.

• This installer can be used to configure the application through the application server web-console.

Configuring the Installer#

The Installer added in the previous step needs to be configured. Configuring an installer means adding values to the installer. For this application, it is shown in the figure below.

• For this application, we need to add two configuration items namely DN1 and DN2. These configuration items are given default values here. These values can be reconfigured from the Application Server Console when this application is uploaded to the Application Server.

• Once you are done with adding the configuration items to the installer, double click on the Script1 under the root project directory. It will ask you whether do you want to save the changes made in the installer file. Click on "Yes".

Adding Global(Or Script) Variables#

Now we need to add some global/script variables which can be used throughout one script. Only global variables are capable of collecting the configuration item values which are set in the installer.

• Adding some more global(Or script) variables.

-> Initialize g_DN1 with Config.DN1, and g_DN2 with Config.DN2. There is no need to initialize the last two global/script variables with any value. We'll assign proper values to these variables at an appropriate time.

Handling the incoming Http request#

While creating applications on CUAE developer tool, we try to handle the triggering events for the applications. The events which trigger the application script are displayed as tabs on the top of the designer canvas. To handle a particular event you need to add some actions, which will be executed on the occurrence of that event.

The actions are listed in the Toolbox under different tabs.

For this application, the triggering event is "Metreos.Providers.Http.GotRequest" and for this event there is only one event handler named "OnGotRequest". Using this event handler we'll start creating our application.

The steps to create the complete application are listed below:-

1. When we receive an incoming Http request, as per the application requirement, we need to make a call. For making a call we need to use the "MakeCall" action. The MakeCall action is enlisted under the "CallControl" tab in the ToolBox. Click and hold on this action and drag-drop this action onto the designer canvas. When "MakeCall" action is dropped to the designer canvas, it will create two more event handlers namley "OnMakeCall_Complete" and "OnMakeCall_Failed". We'll handle these two events later.

2. Now the MakeCall action needs to be configured with required action parameters to initiate a call. For example in order to make a call using MakeCall action we need to provide the "To" number.

• When we select the MakeCall action on the designer canvas it will bring up the properties window in the lower right hand corner of the Designer. In the action parameters list there is one parameter named "To".

• To bind the "To" parameter with the global variable "g_DN1" expand the "To" parameter by clicking on + on the left side of "To" parameter. This will open the properties of the parameter. For the "User Type" set the property to variable. Once it is done, select "g_DN1" as the value to be provided to the "To" parameter.

• For the "Display Name" and "From" parameters, write "P2P Test" in the text box. Do not change the "User Type" property for these two action parameters. This will be displayed to the phone to which this call is being initiated.

• Whenever a call is initiated, a Call ID is assigned to it. So the "MakeCall" action will also generate a CallId for the call being initiated in this application. We'll store this CallID into the global/script variable "g_CallId"

3. In response to an incoming Http request we need to send a response back to the endpoint which initiated the Http request. The "OnGotRequest" event contains an event parameter named "RemoteHost". In order to use this event parameter we need to create a local variable in the event handler for "OnGotRequest".

• To create a local variable first you need to open the "Variables Tray". This done by going to View->Variables tray.

• Once the "Variables Tray" is opened right-click on the tray and select "Add New Item". It will add a new variable to the tray.

• After the variable is added, rename it to "remote_Host". Now this local variable needs to be initialized with the event variable named "RemoteHost". To do this, click on the variable "remote_Host". It will open the properties window for this variable. Against the "InitializeWith" field, select "RemoteHost" from the drop down list. This list contains all the event variables.

4. Now we'll add "SendResponse" action to the canvas. This action is under "HTTP" tab in the toolbox. Drag-drop this action to the canvas of "OnGotRequest" event handler.

Passing the program control from "MakeCall" to "SendResponse"#

Now we have a "SendResponse" action and we need to determine how the program flow moves from "MakeCall" to "SendResponse". This is done by connecting these two actions by a directed line.

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

Now we need to change the label of the connecting line. To do this, click on the line-label and select "Success" from the drop-down list. This ensures that the program control will move from MakeCall to SendResponse only if the MakeCall action is successful.

• The action parameters of the SendResponse action need to be initialized. In the text field against "Body" write "The call was placed successfully.".For "Content Type" - "text/plain". The "RemoteHost" parameter can be initialized with the local variable , named "remote_Host",we created in step 3. The "ResponseCode" = 200 and "ResponsePhrase" could be "Ok"

5. Now the function of "OnGotRequest" event hadler is done. We'll close this event hadler by drag-dropping the action named "EndFunction" from the "Application Components" tab in the toolbox.

• Connect it with "SendResponse" using a "Default" wire.

6. Now we'll cover the case when the call could not be initiated. Application server might fail in initiating a call for various reasons e.g. If the telephony server is not properly configured. To cover all these cases we add another "SendResponse" below the "MakeCall" and add it using a "Failure" wire.

• For the action parameters of this "SendResponse" action we'll use body :- "Make Call Failed", ContentType:- "text/Plain", remoteHost could be populated with the local variable "remote_Host", ResponseCode:- "200" , ResponsePhrase:- "Ok".

• After this we'll add another action "EndScript" here. Because if the first call itself could not be initiated then we'll end our main script. It is done in the figure below.

7. Now we're done with handling the incoming Http request. Now we'll handle the "OnMakeCall_Complete" event. According to our specification, when the application is triggered it should place a call to a phone and when the phone is answered, a prompt is to be played. So we'll use "Play" action which is under the "Media Control" in the "Toolbox".

• In order to configure the "Play" action we'll add one local variable to the "Variables Tray", named "connection_Id" and we'll initialize it with the event variable "ConnectionId"(Shown below.) . This variable is used as the action parameter for "Play" action. The prompt to be played is also written in the Prompt1 field. In this case it is "This is a test prompt. Press 1 to continue. Or press 2 to hangup.". The resulting parameter "ConnectionId" is stored into the same local variable for future usage.

>>Initializing the local variable with the ConnectionId :- As soon as the "MakeCall" is completed the "OnMakeCall_Complete" event handler is populated with the event variables like CallId, ConnectionId etc. We'll use ConnectionId from these variables. For this , R-click on the local variable and select Properties. Then initialize it with the "ConnectionId" from the drop-down list.

8. We'll add "GatherDigits" action to the canvas besides "Play" action. On the basis of the key pressed by the user, the GatherDigits action will move the program control. The GatherDigits action has some termination conditions. If any of these conditions is fulfilled, the program control will move to "OnGatherDigits_Complete". Here we'll use one such condition named "TermCondDigitList". If any number present in this list(1 or 2) is pressed, then the "OnGatherDigits_Complete" event handler will start executing.

• The action parameters which need to be configured are , ConnectionId:- connection_Id(local variable), TermCondDigitList:- 12.

9. Add an "EndFunction" using a "Default" wire.

10. Now we'll handle the event when make call is failed using the event handler named "OnMakeCall_Failed". If the first MakeCall action fails then we need to end the entire script.

11. There is another event handler named "OnPlay_Complete". We'll just end the function here. The difference between "EndFunction" and "EndScript" is that the earlier action ends the immediate function whilst the later one ends the initial script (Script1 in this case).

12. Now we'll move onto the next event handler named "OnPlay_Failed". The play action can fail due to various reasons, one of which could be unavailability of media resources. So, when the play action fails, the "OnPlay_Failed" event is triggered. We need to end the script here.

13. Next event handler is "OnGatherDigits_Complete". It will be triggered when the "GatherDigits" action is successful. We'll add a "Switch" which will decide whether to initiate another call or not on the basis of the key the user presses on the phone. The key pressed by the user can be collected using a local variable "digit" which needs to be initialized with the event parameter "Digits". The action parameter SwitchOn of Switch should be set to the variable digit.

• The local variable "digit" needs to be initialized with the Event Parameter "Digits". To do this, R-click on the variable "digit", in the variables tray, and selet properties. In the properties window initialize this variable with "Digits" be seleting it from the drop-down list.

14. We'll add a "MakeCall" action again to initiate the second call, if the user presses 1. We'll rename the functions "OnMakeCall_Complete" and "OnMakeCallFailed" to "OnMakeCallComplete1" and "OnMakeCall_Failed1". This can be done by R-clicking the function name, shown below the action ,"OnMakeCall_Complete" to "OnMakeCall_Complete1". Similarly it can be done for "OnMakeCalled_Failed1".

• Now we'll connect the "Switch" action with "MakeCall" using a wire which has a user defined name. If the user presses "1" key then the control should go to the "MakeCall" action. Otherwise it should hangup the first call. Name of the connecting wire is changed by right clicking on the associated name of the connecting wire. This field is editable. Change it to 1.

• If the user presses "2" key then the first call, whose CallId is stored in "g_CallId" should hang up. This is done by using an action named "HangUp" and the action parameter "CallId" for this action should be set to global variable "g_CallId".

• To run the "MakeCall" action we need to supply some action parameters like DisplayName:- "P2P" and To:-"g_DN2"(global variable). After this we'll add the "EndFunction" and "EndScript". This is done in the figure below.

• Store the result data parameter "CallId", for this "MakeCall" action, in the global variable "g_CallId2".

15. If the GatherDigits action fails then we need to HangUp the first call(with CallId "g_CallId"). This is done in the figure below.

• After the hangup, the application should stop running so we'll use the "EndScript" action.

16. For handling the "MakeCall_Complete1":- In accordance with the requirement, we need to bridge the two calls which we generated in this application. We'll pass the two CallIds namely "g_CallId" and "g_CallId2" to the "Unbridge" action, which is enlisted under "CallControl" tab in the "Toolbox".

• The "Unbridge" action will cause these two calls to form a peer-to-peer http://cuaesdk.sourceforge.net/api/ApiGlossary.html#ApiGlossary.P2P relationship, in the process renegotiating their audio streams to receive and transmit to each other, bypassing the media engine.

• Once the calls are connected via peer-to-peer, we'll end our script.

17. Now we'll handle the "OnMakeCall_Failed1". Here we'll do an "EndScript"

18. Now we'll add three more handlers, namely "OnStartTx", "OnStopTx" and "OnStartRx", to the main script. All these event-handlers are enlisted in the "CallControl" tab under the "Toolbox". All the information about these three non-triggering events are provided at the corresponding links.

• StartTx :- http://cuaesdk.sourceforge.net/api/Metreos.CallControl.StartTx.html
• StopTx :- http://cuaesdk.sourceforge.net/api/Metreos.CallControl.StopTx.html
• StartRx :- http://cuaesdk.sourceforge.net/api/Metreos.CallControl.StartRx.html

• Drag-drop all these three event handlers one by one into the main script "Script1".

19. For these three event handlers, we need to put an "EndFunction" action in each of these. This is shown below.

• Put an "EndFunction" action in "OnStopTx" and "OnStartRx" actions as well.

Building the Application#

Build the created application using the "Build Project" option under the "Build" tab of the designer.

• The output of the build will be displayed in the "Output" window.

Deploying the Application#

Once the build is successful, we need to deploy the application to the Application-Server, in order to run it. To do this we need to configure the deployment options. Select the "Options" link which is under the "Tools" tab. It will open a new window. Select "Connectivity" option from the list on the right hand side of the window. Then configure the fields under "Application Server Network Address" . Fill in the IP address of the Application Server, where the application is to be deployed.

• Provide the login credentials for the Administrator under "Administrator".

• Now for deploying the application, select "Deploy" link which is under "Build" tab. Once the package is deployed, an entry will be made in the output window.

Trigger the Application#

1. To set a trigger for the application, go to Applications -> Find/List Triggers. Enter "To" and the route pattern for the application. Select "Add Parameter".