Transforming mapped fields

While creating or updating flows in BMC Integration Studio, you might need to apply transformations to the fields in the source application to enable the appropriate data delivery to the target application. This topic provides transformations examples, and describes how to apply them.


Accessing the Transformations pane

The Transformations pane lets you transform one or more source field values to a mapped target field value. Click the transformation icon () while mapping fields in the Flow Designer, or in the flow's profile page (while updating a flow). The transformation icon is only active if the field mapping is set to Source Fields, and one or more source fields are already added. After a source field is transformed, the icon is highlighted ().

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

The following illustration shows the flow profile point of access to the Transformations pane (see the Field Mapping section):

Applying the transformations

Follow the instructions below for one of the available transform types:

Source value to target value

Transforms a single source field's values to a mapped target field.

For example, in a Remedy ITSM to JIRA flow, you may want escalated Remedy issues to automatically have a high priority in the corresponding JIRA ticket, and non-escalated issues to have a low priority. To achieve this, you must set the Escalated?=Yes case to be mapped to Priority=High. Since the only other possible case is Escalated?= No, No is the default value and should be mapped to Priority=Low, as shown in the following illustration:


Steps to transform

  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 provide a different value for the source field.
  4. Add a target field value for the new source field value.
  5. Repeat steps 3-4 if required.
  6. Click Save and Close.

Note

If you have Source value to target value selected, but have included more than one source field, then only the first source field will be transformed. Refer to the following subsection for transforming multiple source fields.

Multiple source values to target value

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

For example, in a Remedy ITSM to JIRA flow, you may want escalated user service requests in Remedy to be assigned to a certain user Allen Albrook, whose JIRA username is "aalbrook". To achieve this, you must set Escalated?=Yes and Incident Type=User Service Request to be mapped to Assignee=aalbrook, as shown in the following illustration:


Steps to transform

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

    Note

    This option only appears if more than one source fields are mapped.

  2. Select or enter values for each of the source fields.
  3. Select or enter a value for the target field.
  4. Click Add >, and then click Save and Close.

String transformation

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

The following table provides the list of available functions, their descriptions, and examples:

Function Description Example
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 till 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) will return 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 till the end of the string will be returned.
If the source string is "Integration", applying substr(1,2) will return nt
words / words()

Returns the source string or part thereof 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 till 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,!) will return to read
lines / lines()

Returns the source string or part thereof 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 till 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) will return:

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 will replace all occurrences of searchValue.
If the source string is "myemail@email.com", then applying replace(@,[at]) will return 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", then applying toUppercase() will return 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", then applying toLowercase() will return 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", then applying capitalize() will return Some Text

Tip

Typically string transformations are only useful if applied towards a source field that holds string data, as opposed to other data types. For example, in a Remedy ITSM to JIRA flow, it does not make much sense to transform the Escalated? field since it is of boolean type. On the other hand, you can apply string transformations to the Summary field to trim or format the string value, or even replace certain parts of it (assuming the resulting string is more aligned with your JIRA practices).


Steps to transform

  1. In the Transformations pane, select the String transformation transformation type:



  2. Click the Function row, and then select the function you want to use. The selected function is turned green – for example,.
  3. Provide parameter values as needed. Refer to the preceding table for function details.
  4. 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 ocurrences of "legacyProject" found within those 250 characters with "newProject". If you want to reorder functions, remove and re-add them in the intended order.

Applying configuration-specific transformations

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

According to your business goals, 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 Remedy 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 your goal, you can use separate connector configurations for JIRA.

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


Note

If a connector that you use during a flow creation 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

  1. Click the transformation icon () for the intended field.
  2. Click Delete My Transformations
    The transformation icon becomes inactive.

Note

By clicking Remove all (for all transformation types) or removing function boxes (for string transformations), you are not deleting the transformations. This action clears the current transformations for the particular source field or fields, but the deletion takes place after you click Save and Close.


Warning

Deleting or modifying the transformations alters the flow's behavior across all environments, and therefore has a direct impact on all users who are using the flow. Removing a mapped source field also removes all its transformations and has the same impact. For either of the scenarios, BMC recommends that you notify the flow's users before deleting or modifying the transformations.

Where to go from here

Publishing or using flows

Was this page helpful? Yes No Submitting... Thank you

Comments