Web Service Operations

You can perform the following actions on web service operations:

Adding and Editing Operations
Removing Operations

Adding and Editing Operations

The Operation Editor dialog is displayed when you select the Add Operation or Edit Operation buttons on the Operations tab of the Web Service Client communication point. The dialog is used for:

Calling an Operation
Generating the SOAP Request
Processing the SOAP Response
Handling SOAP Faults
Configuring MTOM

Calling an Operation

Property	Description
Name	Enter or select the (local) name of the operation to call. If a value is selected from the list, then the Namespace, Mode, SOAP Action and Request WS-Addressing Action fields are automatically updated to contain the appropriate values from the WSDL.
Namespace	The namespace URI that qualifies the operation name. This property field is automatically set if you select an operation in the Name field.
Mode	The operational mode: `Request-Response` (default). `Out-Only`. If the operation is Output Only, then the Response tab is unavailable as there is no response. (Technically, there should be no faults either, but as some systems send faults anyway, the Fault tab is available). Note that the communication point must be running in Out->In mode to handle request-response messages. It can run in Output Only mode if it only handles Output Only messages. This property field is automatically set if you select an operation in the Name field.
SOAP Action	The value sent for the SOAPAction HTTP header in the SOAP request. Some Web services, particularly those using SOAP 1.1, use this HTTP header to determine which operation is being called. This is generally (but not always) not required when using WS-Addressing as the value of the `wsa:Action` header determines the operation. So if left blank, the SOAPAction header will not be sent. This property field is automatically set if you select an operation in the Name field, and the operation defined a SOAP action.
Request WS-Addressing Action	The value of the `wsa:Action` header that should be sent when calling this operation. This field is unavailable if the option to send WS-Addressing headers is disabled. This property field is automatically set if you select an operation in the Name field.
Enable MTOM	Select the checkbox to enable MTOM (W3C Message Transmission Optimization Mechanism), a method of efficiently sending binary data to and from web services. Refer to Configuring MTOM for details.

Generating the SOAP Request

The Request tab is used to configure how the SOAP requests are generated:

Property	Description
Mode	Determines the mechanism used to generate the SOAP request. The available options are: `Construct SOAP body contents using a template and values from the Rhapsody message body and properties` (default). `Construct the SOAP message using JavaScript`. `Use the Rhapsody message body as the contents of the SOAP body`. `Use the Rhapsody message body as the entire SOAP envelope`.
Template	The XML template to use to build the contents of the SOAP body. The template must be valid XML and should declare namespaces appropriately. Where the WSDL includes valid type information, Rhapsody will generate default templates when an operation loaded from the WSDL is selected. This field is only available if the mode is `Construct SOAP body contents using a template and values from the Rhapsody message body and properties`.
Content Insertion	Allows values to be inserted into the template that are retrieved from message properties, the entire message body or fields within the message. Source Type - the options are: `Body`, `Field`, `Property`. If you select `Body`, the Property / Field Name column is unavailable. If the body is inserted, then the current body encoding (as recorded on the Rhapsody message) is used. Property / Field Name - used to configure either the message property name (when the source type is a property), or the field within a message (when the source type is a field). If the source type is a field, and you have specified a message definition, double-clicking a cell in this column opens the Field Selection dialog for you to select a field. If no message definition is specified and the Rhapsody message is XML, then this can be an XPath. Content Type - determines whether the value should be treated as text (default) or XML. If the content type is XML, then it must successfully parse and is inserted into the template as an XML node at the appropriate point. If the content type is text, then it is inserted as a value at the specified location, and will be XML-escaped. Target XPath - the XPath to use to find the insertion location in the template. This field is only available if the mode is `Construct SOAP body contents using a template and values from the Rhapsody message body and properties`.
JavaScript	The JavaScript editor replaces the above controls when the `Construct the SOAP message using JavaScript` option is selected. The editor exposes XML objects that can be manipulated using E4X syntax to provide the content of the message. The following standard JavaScript objects are available (refer to JavaScript Object Reference and Shared JavaScript Libraries for details): `input` - a read-only Rhapsody message representing the original output message the communication point is sending. `log` - the log4j logger for the communication point. The SOAP request also exposes the following additional JavaScript objects: `request` - represents the request message to be sent. This exposes getters and setters for both the envelope and body. When assigning to envelope, the whole envelope is replaced, but when assigning to body, the body contents are replaced. Similarly, when reading the properties, the whole envelope and body contents are returned respectively. The getters retrieve the SOAP envelope/body as a JavaScript XML object whilst the setters convert a JavaScript XML object into the SOAP envelope/body respectively. `soapNs` - an E4X Namespace object set to the SOAP envelope namespace in use.
Signing / Encryption	Allows the signing and encryption options to be overridden for this request message. The default option is to inherit settings from the web service, but it can be changed to use customized settings. Refer to Signing and Encryption Parameters for details. Only available when using asymmetric or symmetric security binding.

Processing the SOAP Response

The Response tab is used to configure the response message handling. This tab is unavailable if the operation is Output Only.

Property	Description
Mode	Determines the mechanism used to process the SOAP response. The available options are: `Execute custom JavaScript when SOAP response is received`. `Extract contents from SOAP message into Rhapsody message body and properties`. `Use entire SOAP envelope as Rhapsody message body`. `Use SOAP body contents as Rhapsody message body` (default).
XML Namespace Mapping	Used to define namespace URI to XML prefixes that are used in the XPaths. This is required because Rhapsody cannot control what XML prefixes are used in the response messages (as they are generated by the external Web service) and they may not be consistent from message to message. By default, an entry is added to this table for the operation namespace (as this is the namespace most likely to be used). If not set, another entry is also added for the SOAP envelope namespace using a prefix of `soapenv`. This property is only available when Mode is set to `Extract contents from SOAP message into Rhapsody message body and properties`.
Content Extraction	The values to be retrieved from the SOAP response. It is only available when Mode is set to `Extract contents from SOAP message into Rhapsody message body and properties`. It allows values to be retrieved from the response using XPaths, and to be used as the Rhapsody message body, inserted into the message body or set as message properties. Source XPath - used to set the XPath to retrieve the value from. These XPaths are relative to the SOAP envelope root (but the '//' prefix can be used to find the elements no matter where they are). If the XPath evaluates to a primitive node, then that value is set directly in the target (that is, the XML element tags are not included). If it evaluates to a non-primitive node, then the entire node is serialized and inserted at the specified location. If the XPath matches nothing, then an error is thrown if the target was the message body (sending the request to the Error Queue), but is ignored otherwise. If the XPath matches multiple values, then an error is thrown if the target was the message body or a non-repeating field, but all values are used if the target is a repeating field or message property. Target Type - options include the message body, a message property or a field in the message. It is not possible to set both the message body and fields in the message. Target Property / Field - contains the name of the message property or field path that the value should be inserted into. It is disabled if the target is the message body. If the target is a field and a message definition has been associated with the communication point, then double-clicking this cell opens the field selection dialog. If no message definition is specified and the Rhapsody message is XML, then this can be an XPath.
JavaScript	A JavaScript editor is provided when the mode is `Execute custom JavaScript when SOAP response is received`. The following standard JavaScript objects are exposed (refer to the JavaScript Object Reference for details): `log` - the log4j logger for the communication point. `output` - a writable Rhapsody message representing the message that will be returned from the communication point. By default, its contents will match the input message, but this can be changed in the script. The SOAP response also exposes the following additional JavaScript objects: `response` - the response message received from the service. This provides the read-only properties envelope and body, which can be inspected using E4X in the same way as the request properties. The properties are returned as a JavaScript XML object representing the envelope/body. `soapNs` - an E4X Namespace object set to the SOAP envelope namespace in use.
Signing / Encryption	Allows the signing and encryption options to be overridden for this request message. The default option is to inherit settings from the web service, but it can be changed to use customized settings. Refer to Signing and Encryption Parameters for details. Only available when using asymmetric or symmetric security binding.

Responses are classified as valid by the communication point if they are non-fault SOAP responses, and returned using an HTTP status code of 200, 400, or 500.

Handling SOAP Faults

The Fault tab provides several options to deal with SOAP faults received in response to a SOAP request.

Property	Description
Mode	Determines how SOAP faults are treated by the communication point. The available options are: `Treat SOAP Faults As Connection Errors` - causes the connection retries to be executed and the same message resent. `Treat SOAP Faults As Message Errors` (default) - causes the request message to be sent to the Error Queue and the next message to be sent. `Return Fault to Route` - returns the entire SOAP envelope containing the SOAP fault to the route as the input message from the communication point. The communication point will continue to run and send the next message in the queue. `Execute Custom JavaScript When SOAP Fault Is Received` - executes custom JavaScript to examine the SOAP fault and determine the course of action to take.
JavaScript	A JavaScript editor is provided if `Execute Custom JavaScript When SOAP Fault Is Received` is selected. The following standard JavaScript objects are exposed (refer to the JavaScript Object Reference for details): `input` - a read-only Rhapsody message representing the original output message the communication point is sending. This is the same type of message object used in the input array of the JavaScript filter and the input object of the JavaScript connectors. This is not the SOAP request itself. It is the message used to generate the SOAP request. `log` - the log4j logger for the communication point. `output` - a writable Rhapsody message representing the message that will be returned from the communication point. By default, its contents will match the input message, but this can be changed in the script. The SOAP fault also exposes the following additional JavaScript objects: `fault` - the SOAP fault received from the system. This provides properties to get the fault as an E4X object, retrieve the fault code and sub-codes, and methods to treat the fault as a connection or message error. The properties are as follows: `faultCode` - retrieves a JavaScript QName object containing the fault code or null if the fault code is not known. `faultSubCodes` - retrieves the fault sub-codes as a JavaScript array of QName objects or an empty array if no subcodes were returned by the fault. The methods are as follows: `treatAsConnectionError` - throws ConnectionFailedException which treats this fault as a connection error. The first argument passed to the call is used as the message in the exception. If omitted, a default error message is produced. `treatAsMessageError` - throws MessageSendFailedException which treats this fault as a message error. The first argument passed to the call is used as the message in the exception. If omitted, a default error message is produced. The following script excerpt illustrates how to process a fault response // Check the fault code if (fault.faultCode.localName == "Receiver") { // Fault in the web service - treat as a connection error so we retry fault.treatAsConnectionError(); } if (fault.faultSubCodes.length != 0 && fault.SubCodes[0].localName == "FailedAuthentication") { // Authentication failed - treat as message error fault.treatAsMessageError("Invalid security"); } // Otherwise we insert the body of the fault into message (which is assumed to be XML) default xml namespace = "http://www.orionhealth.com/2010/01/rhapsody"; var msg = new XML(output.text); msg..result.appendChild(fault.envelope..soapNs::Fault); output.text = msg; `soapNs` - an E4X Namespace object set to the SOAP envelope namespace in use.

Property

Description

Mode

Determines how SOAP faults are treated by the communication point. The available options are:

Treat SOAP Faults As Connection Errors - causes the connection retries to be executed and the same message resent.
Treat SOAP Faults As Message Errors (default) - causes the request message to be sent to the Error Queue and the next message to be sent.
Return Fault to Route - returns the entire SOAP envelope containing the SOAP fault to the route as the input message from the communication point. The communication point will continue to run and send the next message in the queue.
Execute Custom JavaScript When SOAP Fault Is Received - executes custom JavaScript to examine the SOAP fault and determine the course of action to take.

JavaScript

A JavaScript editor is provided if Execute Custom JavaScript When SOAP Fault Is Received is selected. The following standard JavaScript objects are exposed (refer to the JavaScript Object Reference for details):

input - a read-only Rhapsody message representing the original output message the communication point is sending. This is the same type of message object used in the input array of the JavaScript filter and the input object of the JavaScript connectors.

This is not the SOAP request itself. It is the message used to generate the SOAP request.
log - the log4j logger for the communication point.
output - a writable Rhapsody message representing the message that will be returned from the communication point. By default, its contents will match the input message, but this can be changed in the script.

The SOAP fault also exposes the following additional JavaScript objects:

fault - the SOAP fault received from the system. This provides properties to get the fault as an E4X object, retrieve the fault code and sub-codes, and methods to treat the fault as a connection or message error. The properties are as follows:

- faultCode - retrieves a JavaScript QName object containing the fault code or null if the fault code is not known.
- faultSubCodes - retrieves the fault sub-codes as a JavaScript array of QName objects or an empty array if no subcodes were returned by the fault.

The methods are as follows:

- treatAsConnectionError - throws ConnectionFailedException which treats this fault as a connection error. The first argument passed to the call is used as the message in the exception. If omitted, a default error message is produced.
- treatAsMessageError - throws MessageSendFailedException which treats this fault as a message error. The first argument passed to the call is used as the message in the exception. If omitted, a default error message is produced.

The following script excerpt illustrates how to process a fault response

// Check the fault code
if (fault.faultCode.localName == "Receiver") { 
  // Fault in the web service - treat as a connection error so we retry 
  fault.treatAsConnectionError(); 
}

if (fault.faultSubCodes.length != 0 && fault.SubCodes[0].localName == "FailedAuthentication") { 
  // Authentication failed - treat as message error 
  fault.treatAsMessageError("Invalid security"); 
}

// Otherwise we insert the body of the fault into message (which is assumed to be XML)
default xml namespace = "http://www.orionhealth.com/2010/01/rhapsody";
var msg = new XML(output.text);
msg..result.appendChild(fault.envelope..soapNs::Fault);
output.text = msg;

- soapNs - an E4X Namespace object set to the SOAP envelope namespace in use.

When a SOAP response message is received representing a SOAP fault, the following message properties are populated on the Rhapsody Message:

rhapsody:SoapFault is set to true.
rhapsody:SoapFaultCode is set to the local name of the SOAP fault code if present.
rhapsody:SoapFaultSubCode is set to the local name of the SOAP fault sub-code if present.

Not all errors that occur when calling a web service necessarily have a SOAP fault available. If a SOAP fault is available in the response and an HTTP status code of 200, 400, or 500 is received, then the configured fault processing action is used.

If an HTTP 4xx or 5xx error occurs but no SOAP fault is available in the response, then:

- The error is treated as a message error if the status code is a 401 (unauthorized) or 403 (forbidden) and if any of the following parameters are configured dynamically using message properties: Endpoint URL, Username, or Password; the error is treated as a connection error if none of those settings are configured dynamically using message properties.
- The error is treated as a message error if the status code is neither 401 nor 403, or unavailable and if the Endpoint URL is configured dynamically using message properties. The error is treated as a connection error if the Endpoint URL is not configured dynamically.

Configuring MTOM

To configure the Web Service Client communication point to use MTOM to send elements as separate parts in a multi-part message, ensure:

The rhapsody:XopFields property list contains the XPath for each element that should be sent as a separate part. If the property list is not specified, only a single-part message is sent.
The rhapsody:XopFieldsNamespaces property list is populated if the prefix used in the XPaths in rhapsody:XopFields is different than those used in the message.

For example, the following code excerpt specifies the XPaths in the XOP fields:

var next = output.append(input[0]);
next.addPropertyValue("rhapsody:XopFields", "//ns1:ProvideAndRegisterDocumentSetRequest/ns1:Document");
next.addPropertyValue("rhapsody:XopFields", "//ns1:ProvideAndRegisterDocumentSetRequest/lcm:SubmitObjectsRequest/rim:RegistryObjectList/rim:ExtrinsicObject/rim:Slot[1]/rim:ValueList/rim:Value");
next.addPropertyValue("rhapsody:XopFieldsNamespaces", "ns1=urn:ihe:iti:xds-b:2007");

If any specified element is empty or evaluates to a complex element, the Web Service Client communication throws an error.

Removing Operations

The Remove Operation button enables you to delete the selected operation after prompting you to confirm the action.