5.5 Managing 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:

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.

5.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 they are 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.

5.5.2 Using Operation Data to Override Default Subscriber Options

There are three ways to override default Subscriber options for a command:

Creating and Using Multiple Subscriber Option Sets (connections)

You can override the default Subscriber option by creating multiple sets of the Subscriber options (called connections) in your configuration, and using the <operation-data> element to specify which connection set to use for the current command.

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 5-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.

soap-action

HTTP Request-Header field with the “SOAPAction” key

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>

Overriding the Authorization Header

You can set the Authorization header dynamically (from within policy) in<operation data>.

Example:

<operation-data><request-headers remove-existing="true"><request-header name="Authorization">Basic cn=admin,o=n:n</request-header> <request-header name="SOAPAction">#batchRequest</request-header></request-headers></operation-data>

The remove-existing flag defines whether the set of request-headers defined in the subscriber-options should be used in addition to the new headers defined in operation-data. If the Authorization header already exists, it is overridden. Otherwise, it is added as new.