Indexed Mapping

The Indexed Mapping feature is used to map array fields and specify the element in the array to be mapped. Few examples are:

  • For String Lists and Object Lists, you can specify the index for the list element you want to link. For example, you can map the third element in a String List to a String.
  • For Document Lists, you can specify the index for the Document that you want to link. For example, you can map the second Document in a Document List to a Document field.
  • For a field in a Document List, you can specify the index of the Document that contains the value that you want to link. For example, if the Document List POItems contains the String ItemNumber, you can link the ItemNumber value from the second POItems Document to a String.

The mapping between array indexes can be performed using the Indexed Mapping dialog box. The Indexed Mapping dialog box automatically appears when you map array fields in the Pipeline panel.

Note: Index mapping for the Document and Document Reference data types are not supported.

The Indexed Mapping dialog box has the following options:

  • Map on array level - Allows you to map arrays without providing indexes. This is the default option.
  • Map specific elements in an array - Allows you to map specify the mapping between arrays at an index level. On selecting this option, the indexes are listed for you to specify the mapping. For example, you can link the second element in a String List to a String or link the third Document in a Document List to a Document field. You can map either all indexes or only few of them. If you do not map all indexes, the mapping between the indexed items is only displayed and the mapping for the main array is not shown in the Pipeline page.
Note:

  • If you have not mapped: > - any indexes and the Map specific elements in an array option is selected, then the parent fields are automatically mapped. > - any one of the target index with the source index, then that index element is mapped to the parent.

  • If you have mapped multiple source indexes to a single target, then the result is not definite because the order in which the mappings are run is not guaranteed.

  • If you want to add or delete a row index, you can use the Add and Delete buttons in the Indexed Mapping dialog box. To delete a single index entry, use the Delete button adjacent to the index entry row. You cannot modify any existing mappings that are indexed.

Guidelines for Mapping Array Fields

  • To map array elements, you need to know the index for the element’s position in the array. Array index numbering begins at 0 (the first element in the array has an index of 0, the second element has an index of 1, and so on).
  • If you map to an array and specify an index that does not exist, IBM® webMethods Integration increases the length of the array to include the specified array index. For example, suppose a String List has length 3. You can map to the String List and specify an index of 4; that is, you can map to the fifth position in the String List. At run time, IBM webMethods Integration increases the length of the String List from 3 to 5.
  • Each element in an array can be the source or target of a map; that is, each element in the array can be the start or end of a map. For example, if a source String List variable contains three elements, you can map each of the three elements to a target field.
  • If the source and target fields are arrays, you can specify an index for each field. For example, you can map the third element in a source String List to the fifth element in the target String List.
  • If you do not specify an array index for an element when mapping to or from arrays, the default behavior of the Pipeline panel is used. For information about the default behavior of the Pipeline, see Default Pipeline Rules for Mapping Array Fields.
  • At run time, the map (copy) fails if the source array index contains a null value or if you specify an invalid source or target index (such as a letter or non-numeric character). IBM webMethods Integration generates journal log messages (at debug level 6 or higher) when maps to or from array fields fail.
  • Mapping Document, Document List, Document Reference, or Document Reference List fields - When working with Document types in the pipeline, you can link a source field to the Document or to the children of the Document field:
    • A Document and its children cannot be targets at the same time. That is, if you have mapped a Document as the target, the Document’s child fields cannot be mapped as target. The same is applicable for Document List.
    • If you have mapped to a child field of a Document, then the child’s parent Document cannot be mapped as target at the same time. The same is applicable for Document List.
    • If you map two Document fields and specify an index that does not exist, IBM webMethods Integration overwrites the structure of the target Document with the structure of the source Document. For example, suppose there are two Document fields D1 and D2 and both have length 3. If you map D1 with D2 and specify an index of 4; that is, map to the fifth position in the D2, then at run time, IBM webMethods Integration increases the length of D2 from 3 to 5.
    • You cannot map a nested Document List to a target Document List when the Document Lists have different sizes. A nested Document List is one that is contained within a parent Document List. Document Lists are considered to have different sizes when they have a different number of entries within the lists. If you need to move values from the source Document List to the target, create a user code that uses a LOOP flow step to assign values from the source to the target one by one.
    • When a Document Reference or Document Reference List refers to an Integration Server (IS) document type that contains identically named fields that are of the same data type and both identically named fields are assigned a value or are linked to another field, the application might not maintain the order of the document contents in the pipeline when the service runs. For example, the application might group all the identical fields at the end of the document. To prevent the change in the order of document contents, set default values for the identically named fields, insert a MAP step in the service before the step in which you want to map or assign a value to the fields. In the MAP step, under Pipeline Out, select the Document Reference field and assign default values to the identically named fields.

Default Pipeline Rules for Mapping Array Fields

When you create maps between scalar and array fields, you can specify which element of the array field you want to map to or from. Scalar fields are those that hold a single value, such as String and Object. Array fields are those that hold multiple values, such as String List and Object List. For example, you can map a String to the second element of a String List.

If you do not specify which element in the array that you want to map to or from, the application uses the default rules in pipeline to determine the value of the target field. The following table lists the default pipeline rules considered for mapping to and from array fields:

Field 1 - Field 2 Behavior
A scalar field - An array field that is empty (the field does not have a defined length) The map defines the length of the array field; that is, it contains one element and has length of one. The first (and only) element in the array is assigned the value of the scalar field.
A scalar field - An array field with a defined length The length of the array is preserved and each element of the array is assigned the value of the scalar field.
An array field - A scalar field The scalar field is assigned the first element in the array.
An array field - An array field that does not have a defined length The map defines the length of the target array field; that is, it will be the same length as the source array field. The elements in the target array field are assigned the values of the corresponding elements in the source array field.
An array field - An array field that has a defined length The length of the source array field must equal the length of the target array field. If the lengths do not match, the map does not occur. If the lengths are equal, the elements in the target array field are assigned the values of the corresponding elements in the source array field.