Distributed Application Development¶

This chapter provides information about how to build solutions consisting of multiple XTML applications that communicate with each other to accomplish tasks.

The SCE supports the following patterns of inter-application communication.

Applications can be chained in a serial way, where one application provides some services on a call and then hands off to the next application.
Two different application sessions can exchange messages between themselves to allow each to provide part of the service for a user. The two different sessions can be in the same or different applications, and they can be executing on the same or different application servers.
An executing application session can trigger an event handler in another application session.

XTML PACs for Application Communication¶

This section defines the unique tabs included in the Properties window and the standard results available for each PAC listed under Communication on the Actions tab in the workspace pane.

These PACs allow different applications to collaborate and coordinate with each other.

Handoff to Another Application¶

The Handoff PAC is used to transfer control of a call to another application. When a call is handed off to another application, the same event handler called in the original application is called in the recipient session.

For example, application A receives an INVITE via the OnInvite handler and then calls the Handoff PAC specifying application B. An idle session of application B is selected, and the application server calls the OnInvite handler in application B.

After the handoff, the session of application A that handed off the call continues executing unless terminated by another PAC.

Properties¶

The Handoff PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Description
Receiving application	Application to hand off the call to.
Recipient session	Unique session identifier for the session of the receiving application. If needed, this can be used to subsequently exchange messages between the two sessions.

Exit Paths¶

In addition to the default result exit path, the Handoff PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.

HTTP Request¶

The HTTP Request PAC is used to send an HTTP request message (SOAP).

Properties¶

The HTTP Request PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Description
URL	Address that the request message being sent to.
Use Http GET	If selected, the HTTP GET message is allowed by SOAP.
Use Http POST	If selected, the HTTP POST message is allowed by SOAP.
Content	Variables to hold the request message content.
Content-Type	XML format of the request message.
Proxy server	Proxy server that the request message being sent to.
Add’l Headers	Variables to hold optional additional headers.
Timeout	Maximum time to wait for this request.
Response	Variables to hold the response.
Content	Variables to hold the response message content.
Content-Type	XML format of the response message.
Add’l Headers	Variables to hold optional additional headers.

Exit Paths¶

In addition to the default result exit path, the HTTP Request PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.
Non-success response	Points to the next PAC to be executed when the HTTP server responds with a failure.

Send a Message¶

The Send a Message PAC is used to send a message to one of the following:

a named session of the same or another application
any or all sessions that are waiting for a message of the specified name
an external process (using SOAP/XML messaging)

For more information, see Send SOAP Messages to Another Application.

Properties¶

The Send a Message PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Destination	Radio button	Select Any waiting session to send the message to any available session that has registered a public event handler for the message type. The Session selected field stores the session ID of the recipient session for future correspondence. Select All waiting sessions to send the message to all waiting sessions that have registered public event handlers for the named message type. Select Specific session to send the message to a particular session, identified by session ID. Select External SOAP Server to send the message to a SOAP server.For more information, see Appendix D: Respond to Web-Initiated Events with SOAP.
Destination IP	String	IP address of the external SOAP server to which the message is sent.
Transaction	String	Transaction ID to keep track of messages sent to the external SOAP server.
Destination Port	Integer	Port the external SOAP server is monitoring for messages.
Message Name	String	Name of the message being sent.

Add Parameters

Parameters are required only if the message is being sent to an external SOAP server.

Click Add.
In the Tag field, type the parameter tag string that is included as part of the message.
In the Value field, type the parameter value string that is included as part of the message.

Note

Click Insert to add a parameter below the parameter currently selected. Click Delete to remove a parameter from the PAC.

Note

Parameters must be listed from top to bottom in the order they appear in the message.

Exit Paths¶

In addition to the default result exit path, the Send a Message PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.

Wait for Event¶

The Wait for Event PAC tells the application to pause until a specified event occurs or a specified time interval expires.

Properties¶

The Wait for Event PAC includes the General tab.

General¶

*General Fields*¶
Field Name	Type	Description
Event	Drop-down List	Event to wait for. Events can be added to this list as needed.
Event Parameters	Varies	Enter a variable to receive each parameter for the selected event.
Event received	String	If waiting for multiple events, enter a variable that will store the type of event that is actually received. For example, if the PAC is waiting for either a SIP Bye event or a Session End event, and the SIP Bye event occurs first, this variable stores a value indicating this.
Timeout	Short, Int, Float	Number of seconds the PAC will wait for a response.

Add Events

Click Add.

The Select the Events to Wait For window appears with the full list of the events available in the Events tab on the workspace pane.

Select the event to wait for and click OK.
Select additional events as needed.

Note

If you select more than one event, the Wait for Event PAC will wait until any one of the specified events occurs.

Exit Paths¶

In addition to the default result exit path, the Wait for Event PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Send SOAP Messages to Another Application¶

The SCE provides a powerful message-passing framework using the Send a Message PAC that allows you to send messages either to another session or to a third-party process via industry-standard Simple Object Access Protocol (SOAP) messages.

A message can be sent to any waiting session that registers a public event handler with an event name equal to the name of the message being sent. Using this method, one application can trigger an event in another application that is willing to handle that event. Similarly, a message can be broadcast to all waiting sessions that have registered a public event handler with an event name equal to the name of the message being sent.

A message can be sent to a specific session on any application server. The session must be identified by a session ID entered when the PAC is configured.

A message can be sent to an external SOAP server if the appropriate entries are made when the PAC is configured.

The SCE provides two methods for an application to receive a message. Most commonly, the application defines a custom event where the event name is equal to the message name that is expected. The application’s event handler for that custom event is triggered by the application server when that message arrives. The second method for receiving a message is to use the Wait for Event PAC to specify the custom event that was defined for the expected message. The application then blocks at that point in the execution until the message arrives or the defined timeout value is exceeded.

Exchange SOAP Messages with Third-Party Software¶

SOAP is used when sending and receiving messages with external processes. Within the Application Server architecture, SOAP messaging is the mechanism by which third-party software, such as web services, can exert control over XTML multimedia applications or be notified by XTML applications of VoIP network events. Typical uses of SOAP interfaces include building click-to-talk applications, interfacing with third-party systems such as credit card validation and SMS messaging, and invoking remote procedure calls on disparate systems.

To use the SOAP messaging facility, the application server ps_master_config.xml file must be configured to start the ps_soap_agent and ps_httpd processes. To send SOAP requests to a remote server, the IP address and HTTP port of the remote server must be configured. For example:

<ps-soap-agents>
        <agent host=10.10.123.2" port="8080" protocol="http"/>
        <agent host=84.151.21.56" port="80" protocol="http"/>
</ps-soap-agents>

For more information, see the Application Server User’s Guide.

Send a SOAP Message from an Application¶

An XTML application sends SOAP messages using the Send a Message PAC. The information for the remote server must be configured in the <ps-soap-agents> tag of the ps_master_config.xml file.

When configuring the Send a Message PAC, select External SOAP Server as the destination of the message and specify the Destination IP and Destination Port of the remote SOAP server. If required, the Transaction field must be populated with a string value that is used as a transaction ID for the XTML application and remote server to match requests with responses. The SOAP message will have a message name and zero or more parameters. Each parameter has an XML tag and a value.

The message is encoded into a SOAP message with a SOAP envelope header and body. The SOAP envelope header includes the transaction ID and the source XTML session ID.

Note

SOAP messages sent by third-party software to an XTML session will have a destination session ID rather than a source session ID.

The SOAP envelope body includes the message name and the parameter values. Each parameter is in an element named according to the specified tag name provided in the Send a Message PAC.

For example, an XTML application sends a notification to a SOAP server that a conference participant has just left the conference. The message is named ConfLeaveNotify and there are parameters that include the conference ID (conferenceId), the caller’s pass code (callerPassCode), and the reason for leaving (reasonMsg). The encoded SOAP message would look like the following:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" >

        <SOAP-ENV:Header>
                <dst-sessionID>2.3.conference.110@10.10.105.3</dstsessionID>
                <TrxnID>100</TrxnID>
        </SOAP-ENV:Header>

        <SOAP-ENV:Body>
                <m:ConfLeaveEvent xmlns:m="ConfLeaveEvent/" >
                        <conferenceId>18958</conferenceId>
                        <callerPassCode>45</callerPassCode>
                        <reasonMsg>PARTY HANGUP</reasonMsg>
                </m:ConfLeaveEvent>
        </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The third-party SOAP server must be prepared to receive and parse this message and perform whatever service logic is appropriate to the notification. The Send a Message PAC returns immediately after sending the message and does not block waiting for a response. All messaging is asynchronous.

Send a SOAP Message to an Application¶

It is possible for a third-party software to send SOAP messages to an XTML application. The HTTP connection from the remote server must connect to the HTTP port that the ps_httpd process is configured to monitor. The HTTP request must include the SOAPAction header as follows:

SOAPAction: <soap-uri>

In the header, <soap-uri> is currently not interpreted. The request must be sent as an HTTP POST.

Note

By default, this is TCP port 8080, but this is a configurable parameter in the ps_master_config.xml file.

Send a SOAP Message to a Specific Session¶

To send a SOAP message to a specific XTML session, the SOAP envelope header must include a <dst-sessionID> tag with a value that is the session identifier for the session for which the message is targeted. The message is routed to that specified session, where it triggers a custom event with the same name as the message (which is the immediate child element of the <SOAP_ENV:Body> tag). The signature of the XTML custom event must be defined with the following parameters that must then be followed by the parameters in the incoming SOAP message:

IP address of the sender of the message (string value in dot decimal format)
TCP port of the sender (integer value)
transaction ID in the message (string value)

Following this, the parameters in the message must be defined in the custom event signature so they arrive in the message. Each of the parameters will be encoded and presented to the application as an XTML string value.

Note

It is critical that the custom event signature follow the rules outlined in this section. If the number or type of the parameters do match the custom event signature, the message will be discarded.

Send a SOAP Message to any Waiting Session¶

To send a SOAP message to any waiting XTML session, the SOAP message should be defined exactly the same as when sending to a specific session except that no <dst-sessionID> tag should be present in the SOAP envelope header. In this case, the application server routes the SOAP request to the internal event routing mechanism. The routing mechanism selects an available session that has registered a public event handler for a custom event with a name equal to the message name.

When the application session receives the message - either because the associated event handler was triggered or because the session was in a Wait for Event PAC - the application should use a Send a Message PAC to send a response back to the requesting source using the IP address, port, and transaction ID specified in the event parameters. The response SOAP message will be formatted similarly to the incoming SOAP request except that the <dst-sessionID> tag (if present) will be replaced with a <src-sessionID>. The response can include a different message name and set of parameters from the request. The response message is transmitted back to the requestor as a HTTP 200 OK response to the original request, with the encoded SOAP message carried in the body of the HTTP response.

To implement a one-way notification transaction that does not require the application to respond to the requestor, the SOAP request should include the following tag in the <SOAP-ENV:Header> section:

<send-soap-response>false</send-soap-response>

This tag causes the application server to transmit an immediate HTTP 200 OK in response to the request before the request is sent to the application session, and the session therefore does not need to send a response.