Coding Input Mappers

In between the BeginMapper and EndMapper nodes, the mapper developer must implement the mapping from the source format to ISF. The input message, from the BeginMapper node, will either be a parsed version of the input bit stream or a BLOB depending on the type of mapping technology being used. The output, to the EndMapper node, must contain a valid ISF message. The mapper developer does not need to perform any database persistence or raise any events; the EndMapper component will take care of this.

The mapper developer only needs to perform the following two tasks, in order, before passing control back to the EndMapper node:
  1. The mapper must map the message from the input format to ISF, generating the ISF representation below the OutputRoot node on the output tree.
    Note: It is recommended to use XMLNSC for all ISF message tree manipulation.
  2. The mapper must supply the values for the columns of the transaction records which it wants populated. Any values not supplied may be given a default value.
The mapper developer has a number of technology options for implementing a mapping:
  • Using ESQL code in a compute node.
  • Calling out to a Java™ procedure from a compute node.
  • Using a Java compute node.
  • Using an XML Transformation node (XSL-T).
  • Using a mapping node.
  • Using a IBM® Transformation Extender (WTX) plug-in node.
The choice of mapping technology is influenced by many factors including but not limited to:
  • Message size
  • External format
  • Skills availability
  • Technology preferences
  • Performance requirements
Notes:
  1. Using a mapper that returns unparsed output (BLOB) can negatively affect performance. For these mappers, use EndMapper (v2) BLOB input for maximum efficiency.
  2. Using ESQL is a risk free choice for both performance and scalability if the external format is XML or IBM App Connect Enterprise message sets are available for non XML formats. A Java compute node is also reasonable choice if Java is the programming language of choice.
  3. WTX may be a good choice for non XML formats if type trees for the external format are readily available.
  4. Using an XML transformation node with non-XML data is not recommended as extra parse/write steps will be required to convert the data to and from XML.
  5. Using XSLT from a Java compute node could be attractive on z/OS® for XML formats since the MIPS cost can usually be offloaded to zAAP.

During mapper invocation, the IBM App Connect Enterprise environment contains the information shown in the following table.

Table 1. Input mapper context data
Location Contents
InputBody Input message in IBM App Connect Enterprise Domain defined in Environment.PMP.Variables.Channel.MSG_DOMAIN
Environment.PMP.Variables. Channel The details of the channel on which the message arrived.
The following channel properties are available beneath this location:
  • ID
  • PARTY_ID
  • FORMAT_ID
  • MAPPER_ID
  • VALIDATOR_ID
  • NAME
  • PARTICIPANT
  • DESCRIPTION
  • INBOUND
  • OPEN
  • Q_MGR
  • Q_NAME
  • SEQUENCE
  • EFF_DATE
  • END_DATE
  • CCSID
  • ENCODING
  • VALIDATE_MSG
  • VALIDATE_ISF
  • MSG_SET
  • MSG_TYPE
  • MSG_FORMAT
  • MSG_DOMAIN
  • MAPPER_NAME
  • VALIDATOR_NAME
  • LOG_DATA
  • TIMEZONE
  • MASTER_FLAG
  • PARAM
    • BURST_LIMIT
    • BURST_WAIT
    • BURST_MAX_LATENCY
    • PT_TYPE
    • Name/Value[]
      Note: Data in the PARAM column is parsed and populated under the PARAM entry as elements with the Param name / param value format.
    Note: BURST_LIMIT, BURST_WAIT and PT_TYPE are always present. BURST_MAX_LATENCY is optional.
Environment.PMP.Variables.Rules. {MapperName}.BusinessConcept The type of object contained in the input message. Examples are: PAYMENT_ORIGINATION and ACKNOWLEDGEMENT.
Environment.PMP.Variables. References.TransmissionID The unique identifier for the physical transmission the input mapper is processing.