Appendix D: Respond to Web-Initiated Events with SOAP¶

The Application Server supports Simple Object Access Protocol (SOAP) as one communication method for web applications and other external applications. SOAP provides a way for web clients to interact with an XTML application with the least amount of additional programming.

SOAP is an XML-based remote procedure call approach to invoking services on a server. The client requesting the services formats a remote procedure request as an XML message and then sends that message to the server.

HTTP is commonly used, but SOAP itself is nonspecific about the choice of transport. The Application Server currently supports SOAP messaging over User Datagram Protocol (UDP). In this architecture, the application server acts as a SOAP server and responds to incoming messages by triggering XTML event handlers. The event handler can then send a SOAP message back to the client that initiated the message.

In a common use example, a web server plug-in (such as a Java server page, IIS extension, or CGI program) formats and sends a SOAP message to an application server. This can be useful in a click-to-dial application. The HTML page can collect the calling and called numbers and provide them to a CGI program that then sends a SOAP message to the Application Server to initiate dialing.

Configure the Application Server¶

The ps_soap_agent process handles SOAP messaging. The Application Server must first be configured to load and start this process as part of the system. To do so, the following entries must be added to the ps_master_config.xml configuration file:

<ps-init>
        <process name="ps_soap_agent" control-queue=
        restart="0" critical="1" />
</ps-init>
...
<console-port-list>
        <ps-soap-agent console-port="7550" />
</console-port-list>

The <ps-init> section of the file starts the SOAP agent process. The <console-port-list> section of the file configures the UDP port that the SOAP agent monitors for incoming messages.

Send a Message to an XTML Application¶

To send a message to an application server, send it using UDP to the port specified in the <consoleport-list><ps-soap-agent console-port> section of the ps_master_config.xml configuration file.

Example SOAP Messages¶

These examples include SOAP messages targeted to waiting sessions and specific sessions.

SOAP Message Targeted to Any Waiting Session¶

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

<SOAP-ENV:Body>
        <m:company.Click2Talk.1 xmlns:m="http://schemas.Xpress.com">
                <CallingNumber>7817842821</CallingNumber>
                <CalledNumber>5086160900</CalledNumber>
        </m:company.Click2Talk.1>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Key Elements¶

The key elements of this SOAP message format are as follows:

SOAP-ENV:Envelope: This should always be filled out as shown in this example.
SOAP-ENV:Header: The header element has the following two optional child elements:
- sessionID: This element identifies the specific session to send the message to. If no session ID is specified, the message is sent to any session waiting for a message of this type.
- trxnID: This element is provided as a convenience so the sending client can match responses with requests.

SOAP Message Targeted to a Specific Session¶

<SOAP-ENV:Envelope xmlns:SOAPENV="
http://schemas.xmlsoap.org/soap/envelope/" SOAPENV:
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Header/>
<sessionID>1.1.click2talk@10.10.160.1</sessionID>
<trxnID>5060AB</trxnID>
<SOAP-ENV:Body>
        <m:company.DisconnectCall.1
        xmlns:m="http://schemas.Xpress.com"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Key Element¶

The key element of this SOAP message format is SOAP-ENV:Body, which identifies the method name to invoke and the parameters to pass to that method.

Receive a SOAP Message in an XTML Application¶

The SOAP message is forwarded to your application as an external event. This provides a unified model of handling all requests and events, whether they are network-initiated (incoming call), web-enabled (click-to-dial request), or originated from a legacy system.

Perform the following steps to handle received SOAP messages.

Create a custom event in the application to respond to the message (see Custom Results).

The name of the event must be the same as the method name in the SOAP message. The display name of the event can be anything you choose. The first three parameters of the event must always be the following:
- string parameter that receives the IP address of the sending host (client)
- int (integer) parameter that receives the sending UDP port of the sending host (client)
- string parameter that receives the transaction ID in the header (if one was provided)
Add an event parameter for each parameter provided with the method in the SOAP message.

The company.Click2Talk.1 method, in the example SOAP message targeted to any waiting session, should have a custom event defined as follows:

Note

The names of the event parameters do not need to match the names of the method parameters. They must match in order and sequence after adding the first three parameters.
Add an event handler for the newly created custom event.

Select the public event handler check box in the Add Event Handler window to receive SOAP messages targeted for any waiting session.

Send a SOAP Message to a Remote Application¶

You can send a message via SOAP back to an originating application. This may be useful to confirm the results of the operation.

Create a Send a Message PAC and then open the Send Properties window.
Select the External SOAP server destination option.
Enter the Destination IP, Destination port, and Transaction. These values will be received as the first three parameters of the incoming message.
Enter a Message name, or method name.
Click Add to create the list of parameters for that method.

For each parameter, specify an XML tag and a value. The tag becomes the element name in the outgoing SOAP message, and the value is the text value in the outgoing SOAP message.