Using WS-ReliableMessaging

Sending a Sequence of Messages from the Web Client

To send a sequence of messages reliably from an InterSystems IRIS web client to a web service that supports WS-ReliableMessaging, do the following:

1. Specify the security header elements of the web client as needed.

   If you are using WS-SecureConversation, start the secure conversation.

2. Call the Create() class method of %SOAP.RM.CreateSequenceOpens in a new tab. This returns an instance of that class.

   This method has the following signature:

   classmethod Create(addressingNamespace As %String, 
                      oneWay As %Boolean = 0, 
                      retryInterval As %Float = 1.0, 
                      maxRetryCount As %Integer = 8, 
                      expires As %xsd.duration, 
                      SSLSecurity As %Boolean = 0) as %SOAP.RM.CreateSequence
   

   

   Where:

   • addressingNamespace is the namespace being used for WS-Addressing support. The default is "http://www.w3.org/2005/08/addressing"

   • oneWay is true if only request sequence is to be created.

   • retryInterval is interval in seconds to wait before retry.

   • maxRetryCount is the maximum number of retries when no activity has taken place.

   • expires is an XML format duration that specifies requested duration of the sequence to be sent.

   • SSLSecurity specifies whether the web client uses SSL to connect to the web service.

3. Call the %StartRMSession() method of the web client and pass the instance of %SOAP.RM.CreateSequenceOpens in a new tab as the argument.

   Note that you can use the instance of %SOAP.RM.CreateSequenceOpens in a new tab only one time. That is, you cannot use it to create another session later.

4. Invoke web methods as needed.

   Use the same web client instance each time.

5. Call the %CloseRMSession() method of the web client when you are done sending messages.

Signing the WS-ReliableMessaging Headers

You can sign the WS-ReliableMessaging headers in either of the following ways.

Signing the Headers with the SecurityContextToken

If you are also using WS-SecureConversation, the SecurityContextToken property of web client contains a symmetric key that you can use to sign the WS-ReliableMessaging header elements. To do so, call the AddSTR() method of the instance of %SOAP.RM.CreateSequenceOpens in a new tab, passing the SecurityContextToken property as the argument:

 do createsequence.AddSTR(client.SecurityContextToken)

Do this before calling %StartRMSession().

Modifying a Web Service to Support WS-ReliableMessaging

To modify an InterSystems IRIS web service to support WS-ReliableMessaging, modify the web methods so that they do the following:

• Verify the inbound request messages contain the WS-ReliableMessaging headers.

• Verify that the WS-ReliableMessaging headers are signed.

  Note that InterSystems IRIS automatically checks whether any signatures are valid. See Validating and Decrypting Inbound Messages.

• Optionally specify the parameters of the web service class to fine-tune the behavior of the web service, as described in the next section.

It is easier, however, to create a security policy and use the Reliable Message Delivery option in the Web Service/Client Configuration Wizard.

Controlling How the Web Service Handles Reliable Messaging

You can specify the following parameters of the web service class to fine-tune the behavior of the web service:

You can specify the same parameters in a web service class that uses a security policy that uses the Reliable Message Delivery option.

Also, you can implement the %OnCreateRMSession() callback method of the web service. This method is invoked at the start of WS-ReliableMessaging session before the %SOAP.RM.CreateSequenceResponse is returned. The response argument has been completely created and not yet returned at this point. This callback gives you an opportunity to add any required Security header elements to the SecurityOut property of the web service. If WS-Policy is used, then WS-Policy support does this automatically. For the method signature, see the class reference for %SOAP.WebServiceOpens in a new tab.