Rational Developer for System z

Where to use mapping routines

A mapping routine can be referenced from: (a) an Assign node; or (b) from the input terminal or an output terminal of most types of Invoke nodes.

Performing a mapping routine

A mapping routine is performed when the artifact that references the mapping routine is processed in the runtime environment.

The runtime environment performs a mapping routine by executing each mapping in the mapping routine in order, starting with the first mapping (see Mapping routines).

Artifacts from which mapping routines can be referenced

Table 1 shows the artifacts (Assign node, input terminal, or output terminal) from which a mapping routine can be referenced. For details see the paragraphs following this table.
Table 1. Artifacts that can reference mapping routines
Type of node: Artifact for which mapping capability is available:
Assign node
Assign node
The node itself.
Invoke nonterminal node
Invoke nonterminal node
The input terminal.
The output terminal.
One or more additional output terminals used to handle a fault or error return. Any number of additional output terminals is available.
Invoke outbound Web service node
Invoke nonterminal node
The input terminal.
The output terminal.
An additional output terminal used to handle a fault or error return (if specified). A maximum of one additional output terminals is available.
Invoke screen operation node
Invoke screen operation node
The input terminal.
Each output terminal. An output terminal is used to create a branch to another Invoke screen operation node to process a possible next screen.
An additional output terminal used to create the branch that is taken if none of the possible next screens matches the currently displayed screen.
Invoke flow node
Invoke flow node
Attention: The input and output terminals of an Invoke flow node do not have mapping routines associated with them. You must use a node on either side of the Invoke flow node.

Assign node: The purpose of an Assign node is to serve as a container for any mappings that you want to be performed at some point in a flow. When you add an Assign node to a flow in the flow editor, the flow editor automatically creates an empty mapping routine and associates it with the Assign node (see References to mapping routines). You can then add mappings to the mapping routine. When the Assign node is processed in the runtime environment, the mappings in the mapping routine are performed.

Invoke nonterminal node, Invoke outbound Web service node: For an Invoke nonterminal node or an Invoke outbound Web service node, a mapping routine associated with an input terminal typically contains mappings that prepare the data that is going to be passed to the invoked application or outbound Web service (see References to mapping routines). A mapping routine associated with an output terminal typically contains mappings that retrieve and process the data returned by the invoked application or outbound Web service.

Invoke flow node: Notice in the last row of the preceding table that an invoke flow node (used to invoke another flow) does not have a mapping routine associated with it, neither with the node itself nor with the input terminal or an output terminal of the node. To set input parameters for an Invoke flow node, or to read output parameters or fault parameters from an Invoke flow node, you must use an Assign node or the input terminal or an output terminal of some other type of Invoke node on either side of the Invoke flow node.

Invoke screen operation node: In general you should not manually create or modify a mapping routine for an Invoke screen operation node. Normally Invoke screen operation nodes and their associated mapping routines are created automatically during flow recording. These mapping routines contain mappings that allow the Insert node to generate the keyboard input for application screens, to perform Insert actions, and to save the results of Extract actions (see Mapping routines in nonterminal flows).

How mapping routines are created

For an Assign node, the service flow project tools create the mapping routine and the reference to it the first time that you try to access a mapping routine for the node (see Creating a mapping routine for an Assign node or an Invoke node).

Similarly, for the input terminal or an output terminal of an Invoke node, the service flow project tools create the mapping routine and the reference to it the first time that you try to access the mapping routine associated with the terminal (see Creating a mapping routine for an Assign node or an Invoke node).

Also, for all types of artifacts that can reference a mapping routine (that is, Assign nodes and the terminals of most types of Invoke nodes) you can replace an existing reference to an mapping routine with a reference to any other mapping routine in the same service flow project. This allows mapping routines to be reusable: the same mapping routine can be referenced by multiple terminals or Assign nodes (see Selecting a mapping routine for an Invoke or Assign node).

Flexibility in choosing a mapping routine

The service flow project tools gives you great flexibility in choosing a mapping routine to use for a particular mapping operation. Two factors contribute to this flexibility:
  • There are many types of artifacts from which you can reference a mapping routine: from Assign nodes (which you can insert almost anywhere in a flow) and from the input terminals or output terminals of most Invoke nodes (all of these are described in the subsection Artifacts from which mapping routines can be referenced above).
  • All the message elements in all the messages in a service flow project are globally available and exist for the entire duration of the primary flow (or its equivalent in the runtime code).

For example, suppose that you have a flow named MyFlow01, that it contains an Invoke nonterminal operation node named getUserData, and that you want to create a mapping to initialize an element in the input message associated with the node getUserData. In this situation, you can create the mapping in a mapping routine associated with any of the following artifacts:
  • The input terminal of the Invoke nonterminal node getUserdata; or
  • An Assign node that you insert just before the getUserData node; or
  • An Invoke nonterminal node, Invoke screen operation node, or Invoke outbound Web service node immediately preceding the getUserData node;
  • and so on.
In sum, in the example above, you can create the mapping in a mapping routine associated with any artifact that precedes getUserData in the flow (and that lies along an actual sequence of execution within the flow, so that the mapping routine is guaranteed to be performed).

Similarly, in the example above, if you want to read the values returned in the output message associated with the Invoke nonterminal node getUserdata, you can create the mapping in a mapping routine associated with any artifact that follows getUserData in the flow (so long as the artifact lies along a sequence of execution in the flow that is guaranteed to be performed).

Guidelines for choosing a mapping routine

The following are guidelines for choosing which mapping routine to use for a particular mapping:
  • Use good programming practices that promote qualities such as orderliness, reliability, ease of understanding, ease of maintenance, etc.
  • Use Assign nodes freely:
    • The sole purpose of an Assign node is to provide an opportunity for mapping.
    • You can add an Assign node almost anywhere in a flow, with essentially no performance penalty.
  • Unless you know what you are doing, do not modify or add to the mapping routines associated with Invoke screen operation nodes, which (usually) are automatically created when you record a flow (see Mapping routines in nonterminal flows).

The following table addresses specific situations:
Table 2. Adding a mapping
Situation: Recommended way of adding a mapping:
You want to transfer data to the input parameters of an Invoke flow node.
  • The best practice is to add an Assign node in front of the Invoke flow node and then do the data transfer in the Assign node.
  • If the Invoke flow node is preceded by another Invoke node, then you can do the data transfer in the mapping routine referenced by the output terminal of the preceding Invoke node.
You want to transfer data to the output message of the current flow. Add an Assign node in front of the flow's Reply message, and do the data transfer in the Assign.

Mapping aids

The following table shows available aids and conveniences for working with mappings:
Table 3. Mapping aids
Artifact: Aid:
  • Assign node
  • Input terminal or output terminal of an Invoke nonterminal node, Invoke outbound Web service node, or Invoke screen operation node
In the flow editor, the Assign node or terminal is highlighted if a mapping routine has been created for the artifact.
Input terminal of:
  • Invoke nonterminal node
  • Invoke outbound Web service node
When the associated mapping routine is created, the service flow project tools automatically stores into the Target side a reference to the input message of the Invoke node.
Output terminal of:
  • Invoke nonterminal node
  • Invoke outbound Web service node
When the associated mapping routine is created, the service flow project tools automatically stores into the Source side a reference to the output message of the Invoke node.
Two connected and adjacent Invoke nodes (or an Invoke node connected and adjacent to a Receive, Reply, or Throw node) where the connected terminals of the Invoke nodes reference mappings. The Initialize Mapping menu entry creates a new Assign node, connects it between the two Invoke nodes (or between the Invoke node and the Receive, Reply, or Throw node) creates a mapping routine for the Assign node, and initializes the Target and Source sides of the mapping routine (see Initialize Mapping -- a convenient way to map data between two nodes).
Mapping routine In the mapping editor, the Select a Message window includes messages that describe system structures: SNA_FIELDS, SNA_TEXT_AREA, SYS_FEPI_OVERRIDES, SYS_LU_LOGON, WS_SOAPs_AREA.

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)