fn:substring

In the Graphical Data Mapping editor, you can use the fn:substring transform to set the value of an output element to a substring of the original input value. You must define the start position, and optionally, the number of characters that you need to extract.

Overview

The fn:substring XPath 2.0 function takes two arguments, an input string and a 1-based number, to return a part of the original string, beginning from the position indicated. You can also specify a third optional parameter as a number, to indicate the end position to compose the resulting string.

The following function call fn:substring("12345", 2, 3) returns "234".

The following function call fn:substring("12345", 2) returns "2345".

The fn:substring-before() and fn:substring-after() functions are variations of the fn:substring() function.
  • Use the fn:substring-before(arg1, arg2) function when you need the part of arg1 that occurs before arg2 occurs in it. For example, substring-before('1234567/CustomerID','/') returns 1234567.
  • Use the fn:substring-after(arg1, arg2) function when you need the part of arg1 that occurs after arg2 occurs in it. For example, substring-after('1234567/CustomerID','/') returns CustomerID.

For more information about XPath, see XPath tutorial or W3C XML Path Language (XPath) 2.0.

Inputs to the transform

The fn:substring transform takes as input one simple type element. This element is used to define the first argument of the fn:substring function.

Note: If the simple type is not of type xs:string, the transform will fail at run time with BIP3945E. Cast the element to a string if you want to use a non-string input element. For more information, see Cast type (xs:type).

Arguments of the XPath function

You define the arguments to the fn:substring function in the General tab of the fn:substring transform properties view.
  • The first argument is a string element. You can define a literal expression, a constant, an input element, or a custom XPath expression.
  • The second argument is named startLocation and specifies the a start position.
  • The third argument is named length, is optional, and specifies the number of characters that you need to select.

In the following figure, the fn:substring transform has one input. The input is used to define the first argument of the fn:substring function.

This figure shows the fn:substring transform.

Define when the transform is applied at run time

You can use any of the input elements to the fn:substring transform to define a conditional expression that defines the condition under which the transform is applied. If the condition evaluates to true, the transform is applied.

For more information, see Configuring the properties of a transform.