4.5 Operation Data

The driver shim applies special handling to Subscriber commands based on the <operation-data> element. On the Subscriber channel, the <operation-data> element can be added to a command for two purposes.

  1. Specify XML data that you want included with the command result. In this way you can match commands with the responses they generate, which is useful for creating associations.

  2. Override default Subscriber options on a per-command basis.

As discussed in Section 1.0, Overview, the <operation-data> element is added to the command from one of the Subscriber channel policies. The driver shim removes the operation data from the command before it is sent to the application, and restores the <operation-data> element (and all child elements) to the resulting response. If needed, rules and style sheets can then access the operation-data element on the result.

4.5.1 Using Operation Data to Specify XML to be Returned on the Result

The sample configurations for the SOAP driver use the <operation-data> element to keep track of identifying information for a command, so the result can be recognized and associations can be properly assigned. Check these samples for details of how the <operation-data> element is used.

When the <operation-data> element is restored on the response, it appended as a child element of the root node. You can override this by providing one or more parent-node- n attributes to the <operation-data> element where n is a number beginning with 1 that is incremented for each parent specifier provided. The driver shim looks for parent-node- n attributes. When found, the attribute is checked to see if the named node exists. If the node is found, it uses as the parent for the <operation-data> element on the response.

4.5.2 Using Operation Data to Override Default Subscriber Options

There are two ways to override default Subscriber options for a command.

  1. Create multiple sets of Subscriber options (called connections) in your configuration, and use the <operation-data> element to specify which connection set to use for the current command.

  2. Specify a specific option to override for the current command, such as url, method, or soap-action.

Creating and Using Multiple Subscriber Option Sets (connections)

To use the <operation-data> element to override the default Subscriber connection parameters:

  1. Edit the Subscriber settings section of the driver configuration.

  2. Using the XML edit feature of iManager, find each Subscriber setting that ends with a dash and the number 1, such as subURL-1, duplicate it, and increment the number.

    For example: subURL-2

  3. Edit the values of the new settings to be the values you want to use for the second connection.

    You can configure any number of connections this way as long as the numbers you use are incremental without gaps.

  4. Add an attribute to the <operation-data> element called connection and give it the value of the connection number you want to user.

    For example:

    <operation-data connection="2">
...(other operation-data elements)
</operation-data>

Overriding Single Subscriber Options

Instead of using the concept of connections to override multiple Subscriber options, you can override only the url, the HTTP method, or the soap-action values, by directly using attributes on an <operation-data> element. The following table lists the attributes that can be used and the Subscriber option they are meant to override.

Table 4-1 Attributes Used to Override the Subscriber Options

<operation-data> Attribute

Subscriber Option Being Overridden

Description

url

subURL-1

This is the URL or (or URI) of the Web Service or HTTP application. Overriding the URL might be useful if, the application has one Web Service for adding a user and a different Web Service for deleting a user.

method

subHttpMethod-1

This is POST by default but can be set to other methods as defined in RFC 2616 Section 9 as needed.

soap-action

HTTP Request-Header field with key “SOAPAction”

With the DSML and SPML samples this value is always #batchRequest. However, there are some Web services that require this value to change, depending on the command.

Examples:

<operation-data url="http://137.66.10.13:18180/soap">
...(other operation-data elements if required)
</operation-data>

<operation-data method="GET">
...(other operation-data elements if required)
</operation-data>

<operation-data soap-action="addUser">
...(other operation-data elements if required)
</operation-data>