Mapping values to input fields

Using the available mappings

When you build your skill flow, output values from all the preceding skills are displayed in the input field of each skill. You can select the output value that you want to use as the input for the current skill.

You can browse through the available mappings in the input field and select the one that best suits your needs. In the following video, an output value from a Dropbox skill is assigned in an input field of an Microsoft Outlook skill.

Generating mapping suggestions

You can generate mapping suggestions to assign values to the skill input fields. You can manually map values from any of the previous skills based on the generated suggestions. Manual mappings take priority over the automatically generated suggestions.

To generate mapping suggestions, you must click Generate mapping suggestions in the Input tab. You get the notification when the suggestions are populated in the respective fields successfully.

Clear mapping suggestions

You can reset the mappings, both the generated suggestions and the mappings that are set manually.

To clear the mapping suggestions, click Clear all mappings.

Also, you can click the close icon next to the mapped input value to discard the individual mapping suggestion.

Setting default values

For the input parameters, you can also specify and set default values. Hover your cursor over the input parameter and click the Specify default value icon. Then, set the default value that you want in the input field.

Combining variables from data mapping and default values

You can use both the default value and the variable from a data mapping as an input value. Follow the procedure to combine the variable from a data mapping and default values in an input field:

1. From the Input tab, click Specify default value icon in a field.
2. Enter the default value that you want.
3. Click Insert variables.
4. Select the data mapping to combine to your default value.

Mapping values from multiple sources

You can map values from multiple sources to an input field.

Following are the steps to map multiple output values to an input field:

1. From the Input tab, click the Specify default value icon in a field.
2. Click the Insert variables icon.
3. Select the value from the available mappings.
4. Click the Insert variables icon to map more values to the field.

In the following image, two output values First name and Last name are mapped to the Text field of a Slack skill. In this way, the values you provide in the First name and Last name fields of the skill are fetched and shown together in the Text field of the Slack skill.

Mapping arrays of primitive data types

In watsonx Orchestrate, array mappings are allowed between the output and input fields of the same data type. For example, an array of strings can be mapped only to an array of string types or a single sting type field. You can perform the following array mappings:

• Map a single value (like a string) to a field that expects multiple values (an array). Your users can see the value as a list in their input form.
• Map an array of values to an input field (like a string). In this mapping, your users get a drop-down list to pick from.
• Map an array of values to another array field. Here, users can choose multiple values from the drop-down list in the input form.

For example, consider three skills: Skill-1, Skill-2, and Skill-3,

Skill-1 with an output field jobRequestIDs. The field jobRequestIDs is an array of string values, for example, ['123', '456', '642']. Output: jobRequestIDs - ['123', '456', '642']

Skill-2 with an input field inputJobRequestIDs that takes an array of string values, for example,['222', '111', '333']. Input: inputJobRequestIDs - type: array[]

Skill-3 with an input field inputOneJobRequestID that takes a string value, for example, ABC. Input: inputOneJobRequestID - type: string

Then, the allowed mappings for this example are:

1. Skill-1.jobRequestIDs [array] to Skill-2.inputJobRequestIDs [array]
2. Skill-1.jobRequestIDs [array] to Skill-3.inputOneJobRequestID [string]

Mapping of nested array of objects

Map nested arrays to another array of objects with same or different structure.

To map nested arrays, use the Available mappings resource. From the list that appears in this resource, select the skill that returns the nested array, and then select the value that you want to map.

You can also map parent elements of one nested array. In this case, the parent element is duplicated for each entity present in the nested array.

To exemplify it, consider a skill flow with two skills:

• The Get users skill that returns a nested array that contains the user roles and the users for each role.
• The Register users skill that registers a list of users and their roles though one array object.

Example of the Get users skill output schema:

{
  "paths": {
    "/getUsers": {
      "get": {
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "group_id": {
                            "type": "integer"
                          },
                          "group_name": {
                            "type": "string"
                          },
                          "users": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "email": {
                                  "type": "string"
                                },
                                "age": {
                                  "type": "integer"
                                },
                                "settings": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "background": {
                                        "type": "string"
                                      },
                                      "language": {
                                        "type": "string"
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Example of the Register users skill input schema:

{
  "paths": {
    "/register": {
      "post": {
        "requestBody": {
          "description": "User",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "Users": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "group_id": {
                          "type": "integer"
                        },
                        "user_name": {
                          "type": "string"
                        },
                        "user_email": {
                          "type": "string"
                        },
                        "preferred_language": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

To use the nested array values of the Get users skill on the Register user skill, map the Register user skill inputs through the available mappings. For example:

• Users.group_id > results.items.properties.group_id
• Users.user_name > results.items.properties.users.items.properties.name
• Users.user_email > results.items.properties.users.items.properties.email
• Users.preferred_language > results.items.properties.users.items.properties.settings.items.properties.language

Then, when users use the skill flow, the Get user skill returns the users in each user group. After the users select one or more groups, the Register user skill register all users in the selected groups. Since the group_id is the parent element of the users, it is duplicated for each user entity.

For more information about how to use arrays on watsonx Orchestrate, see Array.

Mapping values to a dynamic list of options

You can map values to dynamic drop-down fields. In dynamic drop-down fields, the values are retrieved from a specific skill. If the value mapped to the drop-down field matches the dynamically retrieved value from the previous skill, then the option is automatically selected in the drop-down field when the user runs the skill flow. Even though the drop-down field shows a preselected value, you can choose another value from the drop-down list.

If the value mapped to the drop-down field doesn't match any value from the previous skill, the drop-down field doesn't show a preselected value, but you can still be able to select a value from the drop-down list.

In the following example, the drop-down field of the second skill is mapped to show the name of a country when the user selects the code of this country in the first skill.

Transforming data

When mapping, you can change the output of a skill to match what another skill needs. For example, if a skill gives a date and time, you can use the transformation to take only the date (without the time) for the other skill's input. You can apply multiple transformations to a single field, where the value that is obtained from the first transformation serves as the basis for the next transformation. The data transformation works only for fields with text (string) data.

Use the following operators to define transformations:

Get substring by regular expression

By defining a regular expression pattern, you can extract a substring to match the input field. For example, if you use the regular expression [0-9]+ on the string User ID is 111, you get 111. If there are multiple matches for the regular expression, then only the first match is taken. For example, for the string User ID is 111 or 1234, when you apply the regular expression [0-9]+, the value that is extracted is 111.

watsonx Orchestrate uses re module of Python runtime to process regular expression. For more information, see Regular expression operations.

Get substring by index

You can specify where to start and stop to get the needed input.

For example, for the string Hello world:

• Setting the End position as 5, returns "Hello".
• Setting the Start position as 1 and End position as 5, returns "ello"
• Setting the Start position as 5 and End position as 5, returns "".
• Setting the Start position as 5 and End position as 6, returns " ".
• Setting the Skip index as 2, returns "Hlowrd",
• Setting the Start position as 6, End position as 11 and Skip index as 2, returns "wrd".

About the Skip index, the characters are grouped according to the skip value, returning only the first character in the grouping. See the following possibilities:

If you define Skip index as 2 for Hello world string, the return is the first character of each group of two characters, which is "Hlowrd".

If you define Skip index as 3 for Hello world string, the return is the first character of each group of three characters, which is "Hlwl".

If you define Skip index as 4 for Hello world string, the return is the first character of each group of four characters, which is "Hor".

Replace a string

You can replace a part of the text with another string to get the wanted input.

For example, for the value "hello_world":

• Specify Search for as "_" and Replace with as " " to get "hello world"
• Specify Search for as "world" and Replace with as "Watson" to get "hello Watson"

Trim string

To trim and select only the required part of a string, you can use the Trim string operator. Specify the Position and Character to trim to get the required input.

For example, to remove the underscore from the beginning of the string “_hello world“, you can specify the Position as "beginning" and Character to trim as "_". So, you get the value “hello world”. Likewise, you can select the Position as "trailing" to remove a character from the end of the string, and you can select "both" to remove characters from both sides of the string.

Trim string is mostly used to remove the spaces in the beginning or at the end or both the beginning and end of a string. By default, the Character to trim is space (" "), so you can specify the Position to remove the spaces.

Filtering skill inputs

Some skills prompt you to enter a filter input. When you create skill flows, you can autopopulate the filter options by mapping the output of previous skills. The following steps show you how to accomplish this goal:

1. Click the skill in your skill flow.
2. In the Input tab, scroll down to the filterable input fields. You have three initial fields to fill with the data that you want to filter:
   1. In the #1 Filterable input field, select the value that you want to filter.
   2. In the Operator field, select the operator. For example, select the is operator if the filterable input is the value that you inserted in the Value field.
   3. In the Value field, choose the value that needs to match with filterable input from the available mapping list.
      • You can map an output from previous skills or add your own default value.

See the following sequence of examples with a Box skill to get all folder items. In the first example, the filter is defined by folder ID. So, the configuration is:

• #1 Filterable input: Folder ID
• Operator: is
• Values: id

When you finish filling these fields, immediately you can add another filter to your skill flow. The steps to add another filter are the same that you followed previously. Between filters, you must select a logical operator, like the AND operator. In this other example, the other filter is by folder name. So, the configuration is:

• #2 Filterable input: Folder ID
• Operator: is
• Values: name

You can add as many filters you need as you finish to fill the previous one. If you don't want to add new filters, keep the new option blank.

Parent topic:

→ Combining skills into skill flows