XML Web Services connection

With the XML Web Services connection, you can retrieve data from XML through the HTTP protocol. As different HTTP servers expect different types of messages, the XML Web Services connection is set up in a flexible way. You can control the overall layout of the HTTP request to a large extent with templates. This applies both to HTTP header and to the content of the message. This allows for the construction of any type of HTTP request message, including messages without XML data.

When an entry is executed in the Master Template, the XML Web Services connection either extracts data from an earlier collected XML structure sends an HTTP request through an URL. The HostName, Port, and URI from which this URL is composed can be configured in the connection configuration in KCM Core Administrator.

You can specify a template for the content of the HTTP message and a template for its headers. If a content template is specified, the content type of the HTTP message needs to be specified as well (see Example content template).

Also, you can specify an error tag in the connection configuration to include error information.

By default, XML files use UTF-8 encoding.

Usage

To use this connection type, follow these steps:

Open the required DID document and locate a DID module that contains XML Web Services connection entries.
Set the CONNECTION attribute to XMLWEB.
Set the CALLING_CONVENTION attribute to one of the following values:
- HTTPREQUEST. These entries collect data through an actual HTTP request.
- SUBELEMENT. These entries collect data through XML structures obtained from the Master Template.
The DATA_RETRIEVAL attribute is dependent on the value set in the CALLING_CONVENTION attribute:
- If CALLING_CONVENTION is set to HTTPREQUEST, the DATA_RETRIEVAL holds the function that is being called. The returned records are specified at the DEFINE_FIELDS section of the entry. You can refer to the DATA_RETRIEVAL key from within the content template with the expression @(ENTRY:RETRIEVAL).
- If CALLING_CONVENTION is set to SUBELEMENT, the DATA_RETRIEVAL key specifies the XML tag that identifies the entry in the XML file. The returned records are specified at the DEFINE_FIELDS section of the entry. XML tags are case-sensitive.
KEY_RETRIEVAL is only possible for entries that collect their data through MQSeries. It holds the function that is being called. The returned records are specified in a key at the DEFINE_PARAMETERS section of the entry that describes the parameters of the function.

You can refer to the KEY_RETRIEVAL key from within the content template with the expression @(ENTRY:RETRIEVAL).
Set the MODEL_DOC_STATEMENT to WITH for a single entry to retrieve only one record or FORALL for an entry where zero, one, or more records need to be retrieved.
Set the DEFINE section to keys to refer to in the content template. These keys describe the parameters for the key and data retrieval. This gives you the ability to pass any value from the DID to the template.

The result of the HTTP request is returned in an XML structure. The RESULT_PATH specifies where the KEY_RETRIEVAL and DATA_RETRIEVAL are located in this XML structure. Each item in the path specifies the tag of an XML element. The first one holds the root element and the last one specifies the tag of the returned records.

RESULT_PATH
"biztalk_1//body//@(ENTRY:RETRIEVAL).Response//EMPLOYEE//item"

You can include references to the function name with the @(ENTRY:RETRIEVAL) statements. Slashes must be escaped. You can use backslashes instead as shown in this example.

RESULT_PATH
"biztalk_1\body\@(ENTRY:RETRIEVAL).Response\Employee\item"

Also, you can include @(PAR:…) and general @(ENTRY:…) statements when the actual function name is passed as a parameter (and part of the result path).

The result path is not parsed for namespace prefixes. Any prefixes must be included in the path.

Retrieving attributes

An attribute of an XML element becomes a field of an entry with the same name as the element tag.

Example

<Root>
      <Var1 Attribute="x"> 
            Content of var1.
      </Var1>
 </Root>

This XML is specified in the entry in the following way:

DEFINE_ENTRY
    NAME                     Root                           (* Root *)
    MODEL_DOCUMENT_STATEMENT WITH
      DEFINE_FIELDS
        Var1                C_CHAR LENGTH ( 255  )  DATABASE_FIELD "Var1"
      END_DEFINE_FIELDS
      DEFINE_SUBENTRIES
        Var1                   (* Var1 *)
      END_DEFINE_SUBENTRIES
  END_DEFINE_ENTRY
  DEFINE_ENTRY
    NAME                     Var1                           (* Var1 *)
    MODEL_DOCUMENT_STATEMENT WITH
      DEFINE_FIELDS
        Attribute           C_CHAR LENGTH ( 255  )  DATABASE_FIELD "@Attribute"
      END_DEFINE_FIELDS
  END_DEFINE_ENTRY

Set the DATABASE_FIELD for such attribute to @<name of the attribute> to retrieve the content of the attribute.

You can retrieve the content of a current node with a single period.

The following data types are supported for Fields in the XML Web Services connection: C_CHAR, W_CHAR, and DOUBLE.