Liquid Studio Documentation
Data Mapping / Data Mapper Functions / By Category / String / SubString
In This Topic
    SubString
    In This Topic

    Function Name
    SubString
    Category
    String
    Icon
    SubString
    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:

    Source XML
    Copy Code
    <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:

    Target XML
    Copy Code
    <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:

    Data Mapper String Upper Function

    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:

    String SubString Component

    String SubString Transform Added

    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.

    String SubString Transform Mapped

    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.

    Start Constant Properties

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

    Length Constant Properties

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

    String SubString Constants Added

    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.

    String SubString Constants Connected

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

    Input and Output Connections Mapped

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

    Output XML
    Copy Code
    <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.

    This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

    See Also