Creating a Map - Blue Integrator

Help

Creating a Map Example

The Map Editor lets you to define the mapping between two Schemas, typically two different Schemas.

NOTE It is possible to write a map where both input and output Schemas are the same. You might want to do this when you want to populate an empty field in a message, for example). You can also create a map to or from a RAW schema, where the document contents are treated as binary or raw text. Maps based on the RAW schema can be useful to provide preprocessor and/or schema independent functionality, for example character set conversions or the addition or removal of a header.

As input, a map takes a Message and a set of parameters which are populated from the Message Context and from any explicit arguments specified in a Map Workflow Activity. As output a map returns the output Message and a set of parameters which are copied into the output Message Context.

To create a Map, click on the Maps in the Blue Integrator Explorer window, then click New at the bottom of the right pane. This will display the Map Editor:

The Map Editor is laid out in four sections for (from left to right) the input schema document tree, the mapping detail pages, the output schema document tree, and the functoid palette and Properties. By default, a new map defaults to RAW schemas, but any input and output schemas are set by clicking the hyperlink at the top of the relevant section. The input and output schema document trees show the structure of the document. (In the case of a RAW schema, only the root can be accessed and the entire document is treated as a single binary object.) Input and output parameters are defined using the context menus. A default value can be supplied for input parameters, and it is this value that is used when testing the Map.

A Simple Mapping

To create a map, select the schemas to be used for input and output (assuming the RAW schema is not used). This will display the relevant elements and attributes in the appropriate sections of the Map Editor:

Links can be drawn between elements and attributes by dragging and dropping between input and output trees. The input document is traversed, and every link that is triggered creates an associated node in the output document. If the link is associated with a value (an attribute, element, or parameter), this value is copied to the output of the link. For example, to create a link between an input attribute and an output attribute, click and hold the cursor on the dot next to the input attribute in the Mapping section, and drag a line to the output attribute. When you release the mouse button, a red line indicates the link is created:

If a link is selected by clicking on it, its properties can be edited in the Properties sheet. For example, you can change the link so it copies the name rather than the value of the input (useful if you are moving to a more generic schema).

You can delete a link by selecting Edit / Delete from the right-click pop-up menu or hitting the Delete key when the link is selected.

You can create multiple pages for a mapping for clarity or organizational purposes, and each link remains on the page on which it is drawn. Multiple pages are useful to prevent complicated maps getting confusing. Additionally each page can have a scope element (Page Scope) defined by dragging an input schema document node to the Page Scope link. When this is done the links on the page will only execute when this scope element is in execution scope (i.e. the input document node being traversed is the selected node or a child node).

Functoids

A functoid is a function that can be linked into a map. Blue Integrator comes with a library of predefined functoids, and you can define new functoids as needed.

The Functoid palette is displayed in the top-right portion of the Map Editor, where all functoids are categorized into groups. For example the ‘Concatenate’ functoid from the ‘String Functoids’ group will concatenate strings together. When a functoid is selected, the properties are displayed in the Properties Form.

To use a functoid, drag it from the Functoid palette onto a page of the Map. Then drag the input parameters it requires to the left (input) section, and the output values from the right-hand side to where it needs to go (a node in the output document tree, or another functoid). You can specify an explicit scope for the functoid by dragging a link its top. When you do this, the scope is evaluated in addition to the Page Scope to determine whether to execute the functoid.

For further information, please consult the Functoids topic.

Binary Mapping

When mapping with a document type of RAW, the Body element is of type System.IO.Stream, and any VSTA or Custom Functoids should accept or produce data in this format or byte[] as appropriate. Where a string value is expected by a functoid or output node, Blue Integrator will try and convert the entire document body to a single string.

Tracing

Maps now support tracing – the map results form has a Trace tab you can use to specify the generation of an execution trace file.

Example

See Creating a Map Example for a step-by-step guide to creating a map.