Message Attributes

In a Map Engine, data is passed from Activity to Activity in the form of messages. These messages are parsed to build Business Document instances that are used as DML Blocks inputs. DML Blocks, in turn, generate Business Document instances that are incorporated in messages which are sent outside the Sequential Activity.

The Map Engine messages are similar to ordinary mail: they include both the actual data (the letter text) and information to help message delivery (the envelope). This envelope information is called message attributes.

Message attributes are broken down into two categories:

System attributes

System attributes are usually bound to Receive and Send Activities. The integrations you create in Mapping Services generally depend on a Connector type. The Connector enables Mapping Services to handle specific file types, protocols or security services.

For each communication Connector type that you link to an integration, a template file (known as an s4h file) specifies the set of attribute definitions that can be used with that Connector. The template file specifies the attributes for which you can retrieve and modify values with DML Message functions.

Note You cannot modify the content of the standard attribute template files for Mapping Services communication Connectors.

A template file is structured as a sequence of attribute definitions:

DECLARE PUBLIC RECORD Attribute_name {

    DECLARE PUBLIC FIELD $field1_name type1;

    DECLARE PUBLIC FIELD $field2_name type2;

    DECLARE PUBLIC FIELD $field3_name[] RECORD {

        DECLARE PUBLIC FIELD $field31_name type31;

        DECLARE PUBLIC FIELD $field32_name type32;

        }

    }

Where:

  • type[n] is STRING, DATE, INTEGER or REAL
  • attribute_name is the attribute name
  • field_name[n] is the field name

The RECORD field defines sub-fields.

To insert lines of comments, introduce the line with a double slash (//).

To insert a comment in the middle of a line, enter the comment between the/* and the */.

Where to find available attributes for each Connector

You can find the .s4h files that list the attributes for each connector in $CORE_ROOT\config\attribute.

User-defined attributes

To create integrations in which you apply customized processes to the messages, you create Message Flow Components (MFCs) using either Java or the Axway proprietary Message Builder language. In the Message Flow Components that you create using Message Builder, you can create custom sets of attribute/value pairs that you can then retrieve and modify during processing, using the DML Message Functions.

The Message Flow Components that you build in Mapping Services using the Message Builder language are known as Message Builder Components (MBCs). When you create an MBC, you define the attribute/value pairs necessary for the execution of the component in a file with the extension *.s4h.

If you want to make the attribute/value pairs available to the DML message functions, you must place the *.s4h file in: $CORE_ROOT\config\attribute.

The following is an example of a set of MBC attribute definitions contained in an *.s4h file.

When you have created an MBC and placed the attribute definition file in the DML access directory previously mentioned, you can then use DML Message Functions to handle the attributes as you would with standard message attributes.

For example, you can use the following functions:

  • getStringAttribute("MyStructure", "Type"): Returns the value of the Type attribute defined in the MyStructure.s4h file.
  • setStringAttribute("MyStructure", "Type", "00123213"): Sets the value of the Type attribute defined in the MyStructure.s4h file to the value 00123213.

Working with attributes globally

Once defined, you can get and set message attributes values using calls to built-in functions.

A family of built-in functions exists to read attributes. Since you may require a specific class for the result, four functions exist in this family: one for each class (getBooleanAttribute, getIntegerAttribute, getRealAttribute, and getStringAttribute). You pass the names of the attribute and its field as arguments to one of these functions. You must use these function in connection with the type defined for the attribute field in the .s4h file. For example, the type STRING requires the use of getStringAttribute.

To set an attribute value, you use calls to setAttribute with the appropriate arguments (attribute name, field name, and value).

The key point to remember in reading and setting attributes is that they are attached to the Activity messages, and not to the Business Document instances that are moved across the Flow. As a consequence, all output messages share the same attributes. In a complex Flow, the actual value of the attribute is the result of the last call to setAttribute.

Attributes are usually not transferred automatically across Flows. You explicitly call the appropriate get and set functions to copy their value from input messages to output messages.

Related Links