Indexed mapping

Use the Indexed mapping feature to specify elements within array or list structures by their index positions, enabling fine-grained control over data flow.

The following points explain how the indexed mapping feature is used to map array fields.

  • 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 DL1 contains the String field Str1, you can link the Str1 value to the string field Str2 in the second document DL2.

The mapping between array indexes is handled through the Indexed Mapping dialog box, which automatically appears when array fields are mapped in the Pipeline window.

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. Enables mapping of arrays without specifying indexes. It is the default option.
  • Map specific elements in an array. Specifies 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 a 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 to any one of the target indexes with the source index, then that index element is mapped to the parent.
  • If multiple source indexes are mapped to a single target, then the result varies because the execution order of the mappings is not fixed.
  • 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, click Delete. 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.).
  • If you map to an array and specify an index that does not exist, webMethods Integration increases the length of the array to include the specified array index. For example, suppose that 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, 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, map the third element in a source String List to the fifth 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 window is used.
  • 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). 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 selected 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, webMethods Integration overwrites the structure of the target Document with the structure of the source Document. For example, suppose that 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, 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 mapping or assigning values 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 that are 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 a 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 to 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, the length is same 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.