Transforming mapped fields

While designing new flows or updating existing flows in BMC Helix Integration Studio, you can apply transformations to the fields in the source application to enable modified data delivery to the target application. You can also unify data types across applications that are involved in a flow.

BMC Helix Integration Studio provides the capabilities to apply the following types of transformation:

Note

You can apply different types of transformations in one flow if these transformations do not get in conflict with each other.

In addition to transforming the fields of the same data type, BMC Helix Integration Studio supports transforming the fields that have different data types. If required, the following transformations are applied automatically:

  • String to integer
  • Integer to string
  • Date to string
  • Date to integer
  • Integer to date


Points of access to the Transformations pane

In BMC Helix Integration Studio, to transform mapped fields, you can access the Transformations pane in one of the following ways:

  • While designing a new flow, in Flow Designer, on the stage of mapping source fields to target fields.

    The following illustration shows the Flow Designer point of access to the Transformations pane:



  • While updating an existing flow, in the flow profile, in the FIELD MAPPING section.

    The following illustration shows the flow profile point of access to the Transformations pane.

In both cases, you should click the  (transformations) icon. The transformations icon is active only if the field mapping is set to Source Fields, and one or more source fields are already added. If you apply a transformation, the icon gets highlighted in green: .

To apply the source value to target value transformation

The following table explains the Source value to target value transformation type and how you can apply it in a flow.

DescriptionExampleSteps to apply the transformation
Transforms a single source field's value to a mapped target field's value.

In a Helix ITSM-to-JIRA flow, you want the escalated ITSM issues to automatically have a high priority in the corresponding JIRA tickets, and non-escalated issues to have a low priority.

To achieve this goal, you must set the Escalated?=Yes case to be mapped to Priority=High. Because the only other possible case is Escalated?= No, No is the default value and should be mapped to Priority=Low.

The following image illustrates the preceding example:


  1. In the Transformations pane, select the Source value to target value transformation type.
  2. Enter a target field value for the default value.
  3. Click Add new, and then provide a different value for the source field.
  4. Add a target field value for the new source field value.
  5. (Optional) Repeat steps 3-4.
  6. Click Save and Close.


Note: If you select the Source value to target value transformation type, but include more than one source field, only the first source field is transformed.

To transform multiple source fields, use the Multiple source values to target value transformation type.

To apply the multiple source values to target value transformation

The following table explains the Multiple source values to target value transformation type and how you can apply it in a flow.

DescriptionExampleSteps to apply the transformation

Transforms multiple source fields' values to a single mapped target field.


Note: This option is available only if two or more source fields are mapped in a flow.

In a Helix ITSM-to-JIRA flow, you want an escalated user service request in BMC Helix ITSM to be assigned to a specific user; for example, to Allen Albrook, whose JIRA user name is aalbrook.

To achieve this goal, you must set Escalated?=Yes and Incident Type=User Service Request to be mapped to Assignee=aalbrook,

The following image illustrates the preceding example:


  1. In the Transformations pane, select the Multiple source values to target value transformation type.

  2. Select or enter values for each of the source fields.
  3. Select or enter a value for the target field.
  4. Click Add >.

  5. Click Save and Close.

To apply string transformation

The following table explains the String transformation type and how you can apply it in a flow.

DescriptionExampleSteps to apply the transformation

Applies a string function to transform a source field's value.


Note: Typically, string transformation is useful only if applied to a source field that holds string data, as opposed to other data types.

For example, in a Helix ITSM-to-JIRA flow, it's not recommended to transform the Escalated? field because it is a boolean field.

In such a flow, you can apply string transformation to the Summary field to trim or format the string value, or replace certain parts of it, assuming that the resulting string is more aligned with your JIRA practices.

See the string transformation functions.
  1. In the Transformations pane, select String transformation.
  2. Click the Function row, and then select the function that you want to use.
    The selected function is highlighted in green—for example,.
  3. Provide the required parameter values.
  4. (Optional) To add additional functions, repeat steps 3–4.

  5. Click Save and Close.


Note: Functions are applied to the source string in the order you enter them.

For example, if you have substring(0,250) followed by replace(legacyProject,newProject), then the first function returns the first 250 characters of the source string, and the second function returns any occurrences of legacyProject found within those 250 characters with newProject.

If you want to reorder the functions, you should remove and re-add them in the required order.


The following table explains the string transformation functions that are available in BMC Helix Integration Studio:

FunctionDescriptionExample
substring / substring()

Returns a part of the source string identified by start and end parameters.

  • The minimum start value is 0 and corresponds to the first character in the string.
  • The end parameter is optional. If no value is provided, the part starting from start to the end of the string will be returned.

Note: The function processes the character in the start position, but not the one in the end position.

If the source string is "integer", applying substring(0,2) returns "in".
substr / substr()Similar to substring(), except that you have start and length parameters.
  • The minimum start value is 0 and corresponds to the first character in the string.
  • The length parameter is optional; if no value is provided, the part starting from start to the end of the string will be returned.
If the source string is "Integration", applying substr(1,2) returns "nt".
words / words()

Returns the source string or a part of the source string as a collection of words. It has the following parameters: start, end, separator, and join.

  • The minimum start value is 0 and corresponds to the first character of the first word in the string.
  • The end parameter is optional; if no value is provided, all words starting from the start position to the end of the source string will be transformed.
  • The separator parameter is optional and is used to split the source string into separate words. A separator value can be any character, or any string enclosed between // (such as /my-separator/) . If no value is provided, the entire source string (from start to end) will be processed as one word.
  • The join parameter is optional and is used to concatenate words. The default value is ' ' (a single whitespace character).

Note: The function processes the character in the start position, but not the one in the end position.

If the source string is "hard!to!read!", applying words(5,11,!) returns "to read".
lines / lines()

Returns the source string or a part of the source string as a collection of lines. The implicit \n character is used to split lines.

  • The minimum start value is 0 and corresponds to the first character of the first line in the string.
  • The end parameter is optional; if no value is provided, all lines starting from the start position to the end of the source string will be transformed.

Note: The function includes the character in the start position, but not the one in the end position.


If the source string is:

"This is line 1.
This is line 2.
This is line 3."

Then applying lines(17) returns:

"This is line 2.
This is line 3."

replace / replace()

Returns the source string after replacing a matching value.

  • searchValue identifies the value that the source string will be parsed for.
  • newValue replaces all occurrences of searchValue.
If the source string is "myemail@email.com", then applying replace(@,[at]) returns "myemail[at]email.com".
toUpperCase / toUpperCase()Converts and returns the source string in all uppercase letters. This function has no parameters. If the source string is "some text", applying toUppercase() returns "SOME TEXT".
toLowerCase / toLowerCase()Converts and returns the source string in all lowercase letters. This function has no parameters.If the source string is "SOME TEXT", applying toLowercase() returns "some text".
capitalize / capitalize()Converts and returns the source string with the first letter in all words capitalized. This function has no parameters.If the source string is "some text", applying capitalize() returns "Some Text".
stripHtml()

Removes the HTML tags used for text formatting to send plain text to a target system. Use this function if the HTML markup is not supported in a target application of your flow.

This function has no parameters.

If the source string is:

"This is a text from a JIRA comment:

  • some text 1
  • some text 2"

Then applying stripHtml() returns:

"This is a text from a JIRA comment: some text 1 some text 2".

isEqual(value) /

isNotEqual(value)

Sets the boolean fields in a target application to True or False. You must configure the parameters in one of the following ways:

  • Select isEqual and specify a value
  • Select isNotEqual and specify a value

Note: This function is available only for the boolean fields and is hidden for the other fields.

  • If you apply isEqual, and a value from a target application is equal to the specified value, the boolean field in a target application is set to True.

  • If you apply isEqual, and a value from a target application is not equal to the specified value, the boolean field in a target application is set to False.

  • If you apply isNotEqual, and a value from a target application is not equal to the specified value, the boolean field in a target application is set to True.

  • If you apply isNotEqual, and a value from a target application is equal to the specified value, the boolean field in a target application is set to False.

currentTime()

Sets the current time as a timestamp for the fields of the following data type:

  • Datetime
  • Date
  • Time
  • Integer

For the datetime, date, and time fields, the value is the appropriate string representation of the current time. For integer fields, the value is the number of seconds since January 1, 1970 (epoch date).

If the source time is "16:00:05", and the current time is "17:01:01", applying currentTime() returns "17:01:01".

formatDate(<format string>, [timezone])

Formats values to a specified string format for the fields of the following data type:

  • Datetime
  • Date
  • Time

Optionally, you can specify a timezone to convert a value according to the timezone before formatting the value into the string.

If the source date is "11/12/2019", applying formatDate(yyyy-mm-dd) returns "2019-12-11".
getValueAt(<index>)

Extracts a value from a string array at a specified index under the following conditions:

  • The index value for getting a value is 1-based.
  • If there is no value at the specified index (the index value is greater than the length), the returned value is set to undefined.
  • Negative and 0 indexes are not allowed.
If the source string array is "some text is written here", applying getValueAt(2) returns "text".

insertValueAt(<index>, <string>)

Inserts a value at the start, at the end, or at a specified index into a string array under the following conditions:

  • Inserting a value at index 0 adds the value at the start of an array.
  • Inserting a value at index -1 appends the value to the end of an array.
  • Inserting a value at other positive indexes inserts a value in the array at that point. If the index value is greater than the length, the value is appended at the end of the string array.
  • Negative indexes (other than -1) are not allowed.
If the source string array is "some text is written here", applying insertValueAt(-1,with high importance) returns "some text is written here with high importance".

To set up configuration-specific transformations

By default, transformations in BMC Helix Integration Studio flows are connector-specific. This means that transformations are automatically applied to all flows that use a particular connector.

You can set up configuration-specific transformations. In this case, transformations are applied to each connector configuration separately. For example, you might want to create two separate flows that are using a JIRA connector. In a JIRA-to-Helix ITSM flow, you might not need any transformations. But in a JIRA-to-Salesforce flow, you might need to apply transformations to several mapped fields. To achieve this goal, you can use separate connector configurations for JIRA.

To tie transformations to a connector configuration, you must select an existing custom schema instead of a default schema while creating a flow, as shown in the following illustration:

If a connector that you use while designing a flow does not have a custom schema, the original connector-specific transformation functionality is retained. For information about how to create a custom schema for a connector, see Generating custom schema for connectors.

To remove the transformations

Warning

If you remove or modify the transformations in a flow, this action affects the behavior of the flow across environments and has a direct impact on all users who use the flow. By removing mapped source fields, you also remove all transformations of these fields. We recommend that you notify the flow's users before removing or modifying the transformations.

  1. Access the Transformations pane.
  2. Next to the required source field, click the transformations icon.
  3. Next to a transformation that you want to remove, click the  icon.
    The transformation is removed. 
Was this page helpful? Yes No Submitting... Thank you

Comments