Payload Mapping File

Using CA Service Virtualization › Using the Workstation and Console with CA Service Virtualization › Creating Service Images › Using Data Protocols › Copybook › Payload Mapping File

Payload Mapping File

The payload mapping file is an XML document that describes how incoming payloads can be matched to corresponding copybooks. The payload mapping file is also known as payload copybook mapping and payload to copybook file definition map. This file also provides hints for how to structure the resulting XML to provide clarity to the user.

Sample

A sample mapping file can be found here. The sample file contains examples of various configurations and comments describing each of the attributes on each node. This sample file is useful as a reference while creating your copybook mapping files.

Structure

The following example shows the basic payload mapping file structure. For simplicity, this example contains no attributes of values.

<payloads>
  <payload>
    <key></key> 
    <section>
      <copybook></copybook>
      ...
    </section>
    ...     
  </payload>
  <payload>
    ...
  </payload>     
</payloads>

<payloads>

The root XML node for the document. The node cannot be repeated.

<payload>

This element, in its entirety, fully describes a payload that matches it. When a payload is determined to match a <payload> element in this document, the <payload> element is used to describe the incoming payload.

<key>

(Optional) This option makes the XML document more readable. Everything that you specify on this element you can also specify as attributes on the <payload> element.

<section>

A logical grouping of copybooks that defines a portion of the payload. If there are multiple <section>s, they are processed in order with no repetition.

<copybook>

A single copybook that may or may not describe a record in the payload. A <section> can contain multiple <copybook> elements.

<payload>

A <payload> element can contain the following attributes:

<payload name="TEST" type="request" matchType="all" key="reqKey" value="reqVal" keyStart="3" keyEnd="6" headerBytes="0" footerBytes="0" saveHeaderFooter="false" definesResponse="false">
    ...
</payload>

Attribute	Required/Optional	Description
name	Required	Defines a unique name to identify the type of request described here. Name must be unique among the set of payloads of the same type (that is, request or response).
type	Required	Specifies the payload type. Value: One of the following: request response.
matchType	Optional	The matchType attribute applies differently to payload definitions of type "response." For example, responses do not contain arguments or operation names. If a payload definition of type "response" sets this attribute to argument, attribute, or operation, it will never match anything (unless the matching request sets the definesResponse attribute to true, which overrides this attribute). If a payload definition of type "response" sets this attribute to all, the argument, attribute, and operation phases of matching are skipped. Value: One of the following: argument: Try to match on only the specified argument. attribute: Try to match only the specified attribute. metaData: Try to match only the specified metaData. operation: Try to match on only the operation name. payload: Try to match on the body of the request. all: Try to match in the following order: argument, attribute, metaData, operation, then payload. Default: payload
key	Required	The behavior of this attribute depends as follows on the matchType: If matchType is operation or payload, the value of this attribute is used for matching. If matchType is argument, attribute, metaData, or all, the value of this attribute is assumed to be the key of an argument, attribute, or metaData entry. If the matchType value is all, the key value is NOT used for matching against the operationName or the payload body. The value attribute is used instead.
value	Optional/Required	The behavior of this attribute (and whether it is required) changes depends as follows on the matchType: If the matchType is operation or payload, the value of this attribute is ignored and can be excluded. If the matchType is argument, attribute, or metaData, this attribute is assumed to be the value of an argument, attribute, or metaData entry and is required for matching. If the matchType is all, this attribute is required and behaves as described previously during the argument, attribute, and metaData matching phases. During the operation and payload matching phases, however, the value of this attribute is used for matching (as opposed to using the value of the key attribute as is the case if the matchType is operation or payload).
keyStart	Optional	Designates the position where the search for the key should start in the payload (1-based index). The search is inclusive of this value. If you set keyStart to 1, the search starts with the first byte. If you do not set keyStart, the entire payload is searched and keyEnd is ignored. If you set keyStart to a number less than 1, the value is treated as if the value was 1. If you set keyStart to a number greater than the length of the payload, the entire payload is searched and keyEnd is ignored. If you set keyStart equal to keyEnd or greater than keyEnd, the entire payload is searched. If keyEnd minus keyStart is less than the length of the key, the entire payload is searched.
keyEnd	Optional	Designates the position where the search for the key should end in the payload (1-based index). The search is exclusive of this value. If you set keyEnd to 3, it searches only bytes 1 and 2. If you do not set keyEnd, the search starts at keyStart and ends at the end of the payload. If this value exceeds the length of the payload, the search stops at the end of the payload. If this value is equal to or less than keyStart, the entire payload is searched. If keyEnd minus keyStart is less than the length of the key, the entire payload is searched.
headerBytes	Optional	Designates the number of bytes to strip from the beginning of the payload. This defaults to 0 if you do not provide a value. If the attribute is present, the value must be a valid integer.
footerBytes	Optional	Designates the number of bytes to strip from the end of the payload. This defaults to 0 if you do not provide a value. If the attribute is present, the value must be a valid integer.
saveHeaderFooter	Optional	Specifies whether the header and footer bytes that were stripped are persisted in the XML version of the request as hex-encoded strings under the rawHeader and rawFooter tags. Values: true: Persists the stripped header and footer bytes. false: Does not persist the stripped header and footer bytes. Default value: false.
definesResponse	Optional	If true then the response for this request will look for a payload element with an identical name but of type response. This attribute is ignored when the type is response. Default value: false.

You can use the optional <key> element to replace the key-related attributes. The example <payload> element that is shown previously could, optionally, be written as follows for readability:

<payload name="TEST" type="request" headerBytes="0" footerBytes="0" saveHeaderFooter="false" definesResponse="false">

    <key matchType="all" value="reqVal" keyStart="3" keyEnd="6">reqKey</key>
    ...
</payload>

<section>

Example: The following example is a sample section element with all attributes on it and a description of the attributes.

...

<section name="Body">
    ...
</section>
...

Attribute	Required	Description
name	Required	Defines the name of a grouping XML element in the XML output version of the payload. One or more converted copybook elements will be present beneath it.

<copybook>

Example: The following example is a sample copybook element with all attributes on it and a description of the attributes.

...
<copybook key="cpk" order="1" max="1" name="TESTRECORD" length-field="SOME-ID">TESTIN.CPY.TXT</copybook>
...

Attribute	Required	Description
key	Required	Defines the unique string in the record that identifies the copybook. Technically, this attribute is optional. However, if a key is not provided, it means that that copybook is the only one that will ever get applied to the payload. It will be applied over and over until the payload runs out of bytes. If multiple copybook elements have no key, then the first one will always be used, unless the max attribute is specified.
order	Optional	Defines a hint as to the order in which the records are found in the payload. The numbers used are irrelevant, but "later" records in the payload should use a larger integer. Multiple copybooks can be tagged with the same order number, meaning that those records could be in any order. When a record has been found with a specific order number, subsequent searches only search for copybooks with that order number and greater. You can include copybooks in a group that will never match against the payload. They are just ignored. However, this affects performance because each copybook has to be checked. Default: 0
max	Optional	Defines the maximum times that a copybook can be applied to the payload. Blank values, 0, negative numbers, non-numbers, and non-existent values all mean "no limit".
name	Optional	Defines a value to override the record name (that is, the root level in the copybook). If you set this value, the generated node in the XML for this copybook uses this name instead of the record name from the copybook definition. If you do not set this value, the default is to look up the record name from the copybook definition and use that. If you set this value to the record name from the copybook definition, the only effect is on readability of this file.
length-field	Optional	Defines how to split the payload so that the next record search begins in the correct place. If this attribute is not present, the processor attempts to determine the length of the copybook from the definition. If, for some reason, it cannot figure out the length, the processor assumes that the rest of the payload applies to this copybook, and ends processing after applying this copybook. The processor ignores this field if it is not an unsigned Display numeric field.