Function Name	SubString
Category	String
Icon
Description	Retrieve section of input String
Inputs	String Text String to retrieve SubString from Start String index to start the SubString from Length Length of desired SubString
Outputs	Result Text String representing SubString from input String
Properties	None -

Usage

The Data Mapper String SubString function retrieves a portion of a source String as a SubString. Often, when mapping data, you may face limitations in terms of storage or differing application logic within the target context which requires you to map only a portion of selected input Strings. The SubString function allows you to map sections of input Strings by defining start position and length. To apply the String SubString transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using office_source.xsd, an XML Schema Definition inferred from the following source:

<office>
 <file type="corporate">
  <ref>12345abcde</ref>
  <title>Smith and Mitchell</title>
 </file>
 <file type="individual">
  <ref>54321fghij</ref>
  <title>James Black</title>
 </file>
</office>

For our target schema we will be using office_target.xsd, inferred from the following XML:

<associates>
 <account reference="98765">
  <category>Organisation</category>
  <contact>Jane Johnson</contact>
 </account>
 <account reference="56789">
  <category>Corporate</category>
  <contact>Mary Simpson</contact>
 </account>
</associates>

The data models office files for an organisation. Here is the Data Mapper with Source and Target imported:

Let's assume that we only want to map the numerical part of the "ref" item in the source, which represents the first 5 characters in the String. Drag the String SubString function from the Component Palette into the mapping area:

The String SubString function takes three inputs and gives a String output. The String input should be connected to the source String you want to retrieve part of. The Start and Length inputs should be connected to numbers, for which we will use Constants. The output should be connected to the target item, which may be in the XML Writer or another mapping component if you need to apply further transformations.

Connect the SubString String input to the "ref" output in the XML Reader, and the SubString output to the "reference" item in the XML Writer.

Now we need to represent the Start and Length numbers, so drag 2 Constants from the Component Palette onto the Mapper. For each one, we need to right-click and choose Show Properties. For the first one, enter "start" as the Name, choose an integer Data Type from the drop-down list and enter 0 as the Value, so that we start the SubString at the beginning of the source String. Setting the name is not strictly necessary but it does help when working with the Mapper.

For the second Constant, set "length" as the Name, an integer Data Type and 5 as the Value.

Now you can see clearly which Constant is which without having to view the properties.

Now let's map the Constants. Connect the "start" Constant output to the Start input of the SubString function, and the "length" Constant output to the Length input.

Finally let's connect the remaining input and output connections:

We can now execute the transform by pressing Shift-F5 or the Execute button (). The transform is applied and the file we selected as output opens in the editor:

<associates>
 <account reference="12345">
  <category>corporate</category>
  <contact>Smith and Mitchell</contact>
 </account>
 <account reference="54321">
  <category>individual</category>
  <contact>James Black</contact>
 </account>
</associates>

The input item has been restricted to the first 5 characters as part of the mapping process. If the SubStrings you need are either at the start or end of an input String, you can alternatively use the Left and Right functions.