Understanding x-ibm properties

Configuring an importable OpenAPI specification

The x-ibm-skill-type property sets the type of the app and skills that are defined in the OpenAPI specification. On watsonx Orchestrate, all imported skills must be imported type.

That property is added automatically when a skill is imported, but you can add it manually in the info section.

The following example shows how to use the x-ibm-skill-type property.

{
  "info": {
    "x-ibm-skill-type": "imported"
  }
}

Configuring OpenAPI specification subtype

The x-ibm-skill-subtype property sets the subtype of the app and skills that are defined in the OpenAPI specification. The subtype of a skill defines whether the skill is public or private.

To configure the x-ibm-skill-subtype property, add that property in the info section and then set one of the following values:

The following example shows how to use the x-ibm-skill-subtype property.

{
  "info": {
    "x-ibm-skill-subtype": "public"
  }
}

{
  "info": {
    "x-ibm-skill-subtype": "private"
  }
}

Configuring app ID

Use the x-ibm-application-id property to set the unique ID of your app on watsonx Orchestrate.

If you don't configure this property, the unique ID is randomly generated when you import a skill on watsonx Orchestrate.

The following example shows how to use the x-ibm-application-id property.

{
  "info": {
    "x-ibm-application-id": "app-id"
  }
}

Configuring the app name

Use the x-ibm-application-name property to set a name to your app. It is the app name that the user sees in the user interface. The value must be human-readable and easily understandable.

If you don't configure this property, the name is automatically configured by using the configuration that is defined in the title property.

The following example shows how to use the x-ibm-application-id property.

{
  "info": {
    "x-ibm-application-name": "App name"
  }
}

Adding an icon to the app

You can use the x-ibm-application-icon property to add an icon for your app. The property is specified at the info or operation levels in your OpenAPI specification. The icon that is specified at the operation level takes precedence over the info level.

The property takes an HTML <svg> as its value, and is rendered at 48 x 48 pixels. To create your <svg>, use any image modification program.

The following example shows how to use the x-ibm-application-icon property.

At the info level.

{
  "info": {
      "x-ibm-application-icon": "<svg version=\"1.1\" id=\"Layer_1\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" x=\"0px\" y=\"0px\" viewBox=\"0 0 32 32\" style=\"enable-background:new 0 0 32 32;\" xml:space=\"preserve\"><path id=\"user--profile_1_\" d=\"M16,31.36C7.53,31.36,0.64,24.47,0.64,16S7.53,0.64,16,0.64S31.36,7.53,31.36,16S24.47,31.36,16,31.36z M6.349,27c2.579,2.266,5.957,3.64,9.651,3.64c3.693,0,7.072-1.374,9.65-3.64h-0.01c0-4.341-2.941-8.161-7.153-9.29c-0.144-0.038-0.248-0.16-0.265-0.307c-0.018-0.146,0.058-0.289,0.188-0.358c1.678-0.897,2.72-2.635,2.72-4.534c0-2.84-2.306-5.151-5.14-5.151s-5.141,2.311-5.141,5.151c0,1.899,1.042,3.637,2.72,4.534c0.13,0.069,0.205,0.212,0.188,0.358s-0.122,0.269-0.264,0.307C9.292,18.835,6.36,22.655,6.36,27H6.349z M19.435,17.25c3.913,1.377,6.646,4.973,6.905,9.104c2.655-2.651,4.3-6.314,4.3-10.354c0-8.073-6.567-14.64-14.64-14.64C7.927,1.36,1.36,7.927,1.36,16c0,4.04,1.645,7.703,4.3,10.354c0.258-4.135,2.982-7.729,6.883-9.104c-1.506-1.094-2.415-2.846-2.415-4.739c0-3.237,2.629-5.871,5.86-5.871c3.232,0,5.861,2.633,5.861,5.871C21.85,14.404,20.941,16.156,19.435,17.25z\"/><rect id=\"_Transparent_Rectangle\" style=\"fill:none;\" width=\"32\" height=\"32\"/></svg>"
  }
}

At the skill level.

{
  "paths": {
    "/skillPath": {
      "post": {
        "x-ibm-application-icon": "<svg version=\"1.1\" id=\"Layer_1\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" x=\"0px\" y=\"0px\" viewBox=\"0 0 32 32\" style=\"enable-background:new 0 0 32 32;\" xml:space=\"preserve\"><path id=\"user--profile_1_\" d=\"M16,31.36C7.53,31.36,0.64,24.47,0.64,16S7.53,0.64,16,0.64S31.36,7.53,31.36,16S24.47,31.36,16,31.36z M6.349,27c2.579,2.266,5.957,3.64,9.651,3.64c3.693,0,7.072-1.374,9.65-3.64h-0.01c0-4.341-2.941-8.161-7.153-9.29c-0.144-0.038-0.248-0.16-0.265-0.307c-0.018-0.146,0.058-0.289,0.188-0.358c1.678-0.897,2.72-2.635,2.72-4.534c0-2.84-2.306-5.151-5.14-5.151s-5.141,2.311-5.141,5.151c0,1.899,1.042,3.637,2.72,4.534c0.13,0.069,0.205,0.212,0.188,0.358s-0.122,0.269-0.264,0.307C9.292,18.835,6.36,22.655,6.36,27H6.349z M19.435,17.25c3.913,1.377,6.646,4.973,6.905,9.104c2.655-2.651,4.3-6.314,4.3-10.354c0-8.073-6.567-14.64-14.64-14.64C7.927,1.36,1.36,7.927,1.36,16c0,4.04,1.645,7.703,4.3,10.354c0.258-4.135,2.982-7.729,6.883-9.104c-1.506-1.094-2.415-2.846-2.415-4.739c0-3.237,2.629-5.871,5.86-5.871c3.232,0,5.861,2.633,5.861,5.871C21.85,14.404,20.941,16.156,19.435,17.25z\"/><rect id=\"_Transparent_Rectangle\" style=\"fill:none;\" width=\"32\" height=\"32\"/></svg>"
      }
    }
  }
}

Forcing custom endpoint configuration

On watsonx Orchestrate, it is possible to cofigure a custom endpoint for your app after you import the app. For more information about configuring custom endpoint, see Configuring an imported app endpoint.

By default, you don't need to configure a custom endpoint because it's optional. To configure a custom endpoint as required, add the x-ibm-disable-default-server-url in the info section and set it to true.

The following example shows how to configure x-ibm-disable-default-server-url property:

{
  "info": {
    "x-ibm-disable-default-server-url": "true"
  }
}

Configuring headers

Use the x-ibm-skill-headers property to pass skill values through the skill request header. In that property, you can configure:

The following example shows how to configure x-ibm-skill-headers property. In this example, is used the user_email header label for the caller-id and the user_name header label for the caller-name.

{
  "info": {
    "x-ibm-skill-headers": {
      "caller-id": "user_email",
      "caller-name": "user_name"
    }
  }
}

Hiding skills from the skill catalog

Use the x-ibm-visible property to hide or show skills on the skill catalog. You can configure this property in the info or in the skill method sections.

Set the x-ibm-visible property to false to hide the skill from the skill catalog. Otherwise, set true to show the skill on the skill catalog. By default, this property is configured as true.

The following example shows how to configure the x-ibm-visible as false in the info section:

{
  "info": {
    "x-ibm-visible": false
  }
}

The following example shows how to configure the x-ibm-visible as false in the skill method section:

{
  "paths": {
    "/skillPath": {
      "get": {
        "x-ibm-visible": false
      }
    }
  }
}

Configuring a skill as conversational

Set skills as conversational to use them as skill-based actions by AI assistants.

To configure a skill as conversational in the OpenAPI specification, use the x-ibm-conversational-skill property, this property requires a boolean true or false.

By default, if you don't configure that property, it is automatically configured as true when you import the skill on watsonx Orchestrate.

The following example shows how to configure a skill to be shown as a skill-based action in the AI assistant builder:

{
  "paths": {
    "/register_user": {
      "post": {
        "x-ibm-conversational-skill": true
      }
    }
  }
}

The skills are displayed on Build an action from a skill page after you configure the app connection in the AI assistant team skill set. For more information about how to create a skill-based action on an AI assistant, see Building your AI assistant with actions.

On AI assistant chat, the inputs and outputs schemas of the skill can be displayed in a conversational way. For it occurs:

• The input and output schemas must have only string or integers. For more information of how to configure string and integers, see Configuring input and output data types: String and Configuring input and output data types: Integer.
• The skill cannot exceed the maximum number of fields set for multi-turn conversations. For more information, see Configuring the number of input fields for multi-turn conversations.

Training skills with phrases

You can use the natural language model to determine whether the user's phrase that is written in the UI chat box matches a specific skill. When you use the property x-ibm-nl-intent-examples, you can supply example phrases to train the natural language model. If the property is not supplied, phrases are generated from the description and summary that are supplied for the skill. However, these phrases are basic and tend to produce a narrow model.

You can specify the property x-ibm-nl-intent-examples to enable the explicit use of natural language sentences. For good results, provide around 20 to 30 phrases for your skill. You can supply less, but fewer than 10 phrases limits the usability of your skill. See the following example to learn how to use x-ibm-nl-intent-examples property:

{
  "paths": {
    "/skillPath": {
      "post": {
        "x-ibm-nl-intent-examples": [
          "repeat a message",
          "can you echo this message?",
          "repeat what I say",
          "can you repeat what I tell you?",
          "repeat this message for me",
          "repeat after me",
          "say it back to me",
          "play that again",
          "repeat this message again",
          "repeat this message"
        ]
      }
    }
  }
}

Wrapping schemas to use skills on automations

If you want to use imported skills on automations, you must wrap the skills schemas to be recognized by the automation. To do it, use the x-ibm-parameter-wrapper and x-ibm-response-wrapper properties.

Use the x-ibm-parameter-wrapper to wrap inputs and outputs schemas for synchronous skills. In the input and output schema, add the x-ibm-parameter-wrapper property and set it to true.

The following example shows how to configure the x-ibm-parameter-wrapper property:

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "user": {
                    "type": "string"
                  }
                },
                "x-ibm-parameter-wrapper": true
              }
            }
          }
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "response": {
                      "type": "string"
                    }
                  },
                  "x-ibm-parameter-wrapper": true
                }
              }
            }
          }
        }
      }
    }
  }
}

Use the x-ibm-response-wrapper to wrap outputs and callback request schemas for asynchronous skills. In the outputs and callback requests schemas, add the x-ibm-response-wrapper property and set it to true.

The following example shows how to configure the x-ibm-response-wrapper property:

{
  "paths": {
    "/skillPath": {
      "post": {
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "jobId": {
                      "type": "string"
                    }
                  },
                  "x-ibm-response-wrapper": true
                }
              }
            }
          }
        },
        "callbacks": {
          "postResponse": {
            "{$request.header.callbackUrl}": {
              "post": {
                "requestBody": {
                  "content": {
                    "application/json": {
                      "schema": {
                        "properties": {
                          "output": {
                            "properties": {
                              "userName": {
                                "type": "string"
                              }
                            },
                            "x-ibm-response-wrapper": true
                          }
                        }
                      }
                    }
                  }
                },
                "responses": {
                  "500": {
                    "content": {
                      "application/json": {
                        "schema": {
                          "properties": {
                            "code": {
                              "type": "string"
                            }
                          },
                          "x-ibm-response-wrapper": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Mapping inputs from phrases

You can train the natural language model to map input values in the user message, and then automatically fill input fields by using the mapped value. To do it, use the x-ibm-nl-entities property to map the input values, and the x-ibm-nl-intent-examples property to train the natural language model to recognize mapped values.

To map the input value based on the user message, add the x-ibm-nl-entities property to your OpenAPI specification. And then in the entities property list, map the values that you want for each input field by using the following properties:

To train the natural language model to recognize mapped values, add the examples of the mapped values in x-ibm-nl-entities property phrases by using the structure: [example of the mapped value](field name). See more about x-ibm-nl-entities in Training skills with phrases

The following example shows how to configure the mapping of the input values from the user message.

"paths": {
  "/skillPath": {
    "post": {
      "x-ibm-nl-intent-examples": [
        "I want yo see my input as [wo](yourInput)",
        "Show my [watsonx](yourInput) input",
        "My input is [Orchestrate](yourInput) show it",
        "Please show my input as [automation](yourInput)",
        "So, [rpa](yourInput) is may please show it"
      ],
      "x-ibm-nl-entities": {
        "entities": [
          {
            "entity": "yourInput",
            "values": [
              {
                "type": "synonyms",
                "value": "watsonx Orchestrate",
                "synonyms": [
                  "watsonx",
                  "Orchestrate",
                  "orchestrate",
                  "watsonx Orchestrate",
                  "Watsonx",
                  "wo"
                ]
              },
              {
                "type": "synonyms",
                "value": "Robotic Process Automation",
                "synonyms": [
                  "rpa",
                  "IBM RPA",
                  "IBM Robotic Process Automation",
                  "automation",
                  "robotic process automation",
                  "RPA"
                ]
              },
              {
                "type": "patterns",
                "value": "date",
                "patterns": [
                  "\\d{2}\\/\\d{2}\\/\\d{4}"
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

Configuring output messages

You can configure your output message as consistent text into the openAPI specification file, through the x-ibm-nl-output-template property.

By default, the output is "Here are the results of the {your skill name} skill." followed by the skill results. The x-ibm-nl-output-template property replaces this default output for one that you configure in the property.

The following example shows how to configure custom output messages.

{
  "paths": {
    "/skillPath": {
      "post": {
        "x-ibm-nl-output-template": "The user has been registered successfully"
      }
    }
  }
}

Configuring output hyperlinks

Add hyperlinks to skill outputs to redirect users to any web page. To add a hyperlink on the output message, insert the web page URL in the x-ibm-nl-output-template property as plain text or within the <a> href HTML tag as in the example snippet.

The following example shows how to configure a hyperlink in output messages:

Link displayed as a clickable text

{
  "paths": {
    "/register_user": {
      "post": {
        "x-ibm-nl-output-template": "User registered successfully. For more information see https://www.example.com or <a href='https://www.example.com' target='_blank'>Example Website</a>."          
      }
    }
  }
}

Using JMESPath to concatenate phrases with API outputs

Use JMESPath to concatenate the output values of an API into a single message for skill outputs.

To use JMESPath, in the x-ibm-nl-output-template property configure the JMESPath expression by following the structure "{$.JMESPathExpression}", where "JMESPathExpression" is the JMESPath expression for your output.

To create the JMESPath expression, start the reference from the response schema. The following example shows a sample response schema:

{
  "paths": {
    "/skillPath": {
      "post": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "userEmail": {
                      "type": "string"
                    },
                    "userName": {
                      "type": "string"
                    },
                    "userPassword": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The following example shows how to configure JMESPath in output phrases:

{
  "paths": {
    "/skillPath": {
      "post": {
        "x-ibm-nl-output-template": "{$.userName} has been registered successfully. To access the system use the email \"{$.userEmail}\" with the password \"{$.userPassword}\""
      }
    }
  }
}

Filling string fields automatically for Assistant skills

For Assistant, you can automatically fill a string field based on the user utterance or the skill history. You configure this resource by using the x-ibm-skill-inputs property.

To configure the x-ibm-skill-inputs property, add the property in the string input schema that you want to fill automatically and then set one of the following values:

The following example shows how to configure the x-ibm-skill-inputs property:

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "name": {
                    "type": "string",
                    "x-ibm-skill-inputs": "skill-utterance"
                  },
                  "email": {
                    "type": "string",
                    "x-ibm-skill-inputs": "skill-history"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Disabling inputs

Use the x-ibm-disable property to disable input fields in the form and make it uneditable. By default, all fields are enabled:

The following example shows how to disable inputs.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "userName": {
                    "x-ibm-disable": true
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Adding instructions to your skill and skill fields

You can use the x-ibm-disable property to add instructions to your skills or skill fields.

Follow the procedure to add instructions to your skill or skill field:

1. Create a field.
2. Set x-ibm-disable to true.
3. Use the x-ibm-label to set an empty string "".
4. In default set the instructions.
5. Use the x-ibm-order to set the position of your instructions.

The following example shows how to configure instructions at the skill level.

{
  "paths": {
    "/register_user": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "skillInstruction": {
                    "type": "string",
                    "x-ibm-disable": true,
                    "x-ibm-label": "",
                    "x-ibm-order": 1,
                    "default": "<h1>Instruction</h1><br><br>This skill is created by using IBM RPA. Therefore, make sure that you have access to the following RPA tenant:<br><ul><li>API server: https://us1api.rpa.ibm.com/</li><li>Tenant name: IBM RPA</li><li>Code: 0000</li></ul>"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The following example shows how to configure instructions at the skill field level.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "userID": {
                    "type": "number",
                    "x-ibm-order": 1
                  },
                  "skillInstructionForUserID": {
                    "type": "string",
                    "x-ibm-disable": true,
                    "x-ibm-label": "",
                    "x-ibm-order": 2,
                    "default": "The user unique ID in your system."
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

When you add instructions to your skill or skill fields, you can use the <br>, <h1>, and <ul> HTML tags to format your instructions.

Configuring input and output names

You can use the x-ibm-label property to supply a human-readable name for input and output fields on watsonx Orchestrate.

The following example shows how to configure input field names.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "userName": {
                    "type": "string",
                    "x-ibm-label": "Name"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The following example shows how to configure output field names.

{
  "paths": {
    "/skillPath": {
      "post": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "userEmail": {
                      "type": "string",
                      "x-ibm-label": "Email"
                    },
                    "userUsername": {
                      "type": "string",
                      "x-ibm-label": "Username"
                    },
                    "userName": {
                      "type": "string",
                      "x-ibm-label": "Name"
                    },
                    "userPassword": {
                      "type": "string",
                      "x-ibm-label": "Password"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Configuring the error message response

With the x-ibm-display-message-ref property, you can customize the error message that is shown to the user when the skill run fails. In that property, you must configure the x-ibm-message-abs-path and x-ibm-message-template properties.

The following example shows how to configure the x-ibm-display-message-ref, x-ibm-message-abs-path, and x-ibm-message-template properties to display an error message on watsonx Orchestrate.

{
  "paths": {
    "/skillPath": {
      "post": {
        "responses": {
          "400": {
            "description": "Validation Error",
            "x-ibm-display-message-ref": {
              "x-ibm-message-abs-path": "error_response",
              "x-ibm-message-template": "A validation error caused due to {error-msg}. Revisit the inputs and retry"
            }
          }
        }
      }
    }
  }
}

Configuring inputs and outputs as multiline

You can use the x-ibm-multiline property to switch the text box that is used in input and output fields form from a single line to a multiline box.

The following example shows how to use the x-ibm-multiline property to configure input fields as a multiline box on watsonx Orchestrate.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "text": {
                    "type": "string",
                    "x-ibm-multiline": true
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The following example shows how to use the x-ibm-multiline property to configure output fields as a multiline box on watsonx Orchestrate.

{
  "paths": {
    "/skillPath": {
      "post": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "text": {
                    "type": "string",
                    "x-ibm-multiline": true
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Ordering inputs and outputs

You can use the x-ibm-order property to order the input and output fields on watsonx Orchestrate.

The following example shows how to configure the x-ibm-order property to order the input fields on watsonx Orchestrate.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "userID": {
                    "x-ibm-order": 1
                  },
                  "userUsername": {
                    "x-ibm-order": 3
                  },
                  "userName": {
                    "x-ibm-order": 2
                  },
                  "userPassword": {
                    "x-ibm-order": 4
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The following example shows how to configure the x-ibm-order property to order the output fields on watsonx Orchestrate.

{
  "paths": {
    "/skillPath": {
      "post": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "userEmail": {
                      "x-ibm-order": 3
                    },
                    "userUsername": {
                      "x-ibm-order": 2
                    },
                    "userName": {
                      "x-ibm-order": 1
                    },
                    "userPassword": {
                      "x-ibm-order": 4
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Hiding inputs and outputs

You can use the x-ibm-show property to show or hide optional inputs and outputs of the generated form on watsonx Orchestrate. By default, all fields are shown.

The following example shows how to configure the x-ibm-show property to show and hide input fields on watsonx Orchestrate.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "userID": {
                    "x-ibm-show": true
                  },
                  "userUsername": {
                    "x-ibm-show": false
                  },
                  "userName": {
                    "x-ibm-show": true
                  },
                  "userPassword": {
                    "x-ibm-show": true
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The following example shows how to configure the x-ibm-show property to show and hide output fields on watsonx Orchestrate.

{
  "paths": {
    "/skillPath": {
      "post": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "userEmail": {
                      "x-ibm-show": true
                    },
                    "userUsername": {
                      "x-ibm-show": true
                    },
                    "userName": {
                      "x-ibm-show": true
                    },
                    "userPassword": {
                      "x-ibm-show": false
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Promoting fields to the main section

You can split the input fields in two sections, main and show more sections. The main section shows the input fields by default, and the show more section hides the input fields being necessary to click in the show more button to show it.

You can use it for skills that have many input fields. Therefore, you highlight the most important inputs for your skill.

To configure the main section, you use the x-ibm-important property as true to promote fields you want to the main section in the skill forms. For example, you can put a field in the main section of the form that might improve the search, even if that option is not required.

Fields without the x-ibm-important property or defined as false are grouped on show more section.

The following example shows how to configure the x-ibm-important property to show a field on watsonx Orchestrate chat.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "status": {
                  "x-ibm-important": true
                }
              }
            }
          }
        }
      }
    }
  }
}

The following example shows the x-ibm-important property with the data type as an array.

"post":{
   "summary":"Process a string and an array of strings",
   "operationId":"processStrings",
   "requestBody":{
      "required":true,
      "content":{
         "application/json":{
            "schema":{
               "type":"object",
               "properties":{
                  "inputString":{
                     "type":"string",
                     "description":"The string to process",
                     "x-ibm-important":"true"
                  },
                  "stringArray":{
                     "type":"array",
                     "x-ibm-important":"true",
                     "items":{
                        "type":"string"
                     },
                     "description":"The array of strings to process"
                  }
               }
            }
         }
      }
   }
}

Sequencing skills

Sequencing skills is the method of ordering the use of skills to achieve other goals. Therefore, you can sequence these skills to achieve new results.

On OAS, you sequence skills by using the x-ibm-next-actions property. This property contains a list that can sequence the skill. For each item of that list you must configure:

The following example shows how to sequence skills by using x-ibm-next-actions.

{
  "paths": {
    "/skillPath": {
      "post": {
        "x-ibm-next-actions": [
          {
            "skill_id": "app_id__1.0.0__skill_id",
            "utterance": "Register User"
          }
        ]
      }
    }
  }
}

When you sequence skills, the value of the first skill output is automatically set in the second skill input if the input and output matches.

The following example shows an example of the input and output of skills that matches:

Skill that generates the output

{
  "paths": {
    "/skillOutputPath": {
      "post": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "userName": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-ibm-next-actions": [
          {
            "skill_id": "app__1.0.0__skillpath",
            "utterance": "Register User"
          }
        ]
      }
    }
  }
}

Skill that uses the output of the previous skill as input

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "userName": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

{
  "paths": {
    "/skillPath": {
      "post": {
        "x-ibm-next-actions": [
          {
            "skill_id": "Amazon-S3-bucket__2.0.0__create_bucket",
            "utterance": "Create a bucket",
            "configurations": {
              "mappings": [
                {
                  "mapping": {
                    "sourceSkill": "Get-Recipes__1.0.0__get-recipes",
                    "targetSkill": "Amazon-S3-bucket__2.0.0__create_bucket",
                    "fieldMapping": [
                      {
                        "sourceSkill": "recipes.items.properties.type",
                        "targetSkill": "LocationConstraint",
                        "option": "singleLine",
                        "displayName": "recipes.items.properties.type"
                      },
                      {
                        "displayName": "recipes.items.properties.difficulty",
                        "sourceSkill": "recipes.items.properties.difficulty",
                        "targetSkill": "Name",
                        "option": "singleLine"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Configuring dynamic values for list of options

With the x-ibm-ui-extension property, you can enhance input fields to turn them into dynamic input fields. Use this property to add a list of options in your skill inputs where the values are dynamically set from the output of another skill that you have in your skill set.

To use the x-ibm-ui-extension property, add that property in the skill input schema and then configure:

The following example shows how to use the x-ibm-ui-extension to create a list of options with dynamic values from other skill.

{
  "paths": {
    "/skillPath": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "input": {
                    "x-ibm-ui-extension": {
                      "component": "dropdown",
                      "actions": [
                        {
                          "skill_id": "<skill_id>",
                          "type": "data",
                          "mappings": {
                            "labels": "<link_to_object_property_name>",
                            "values": "<link_to_object_property_name>"
                          },
                          "params": {}
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Mapping items for list of options

The mappings section of the x-ibm-ui-extension property specifies the values and labels properties, which define how the data that is gathered from a specific skill can populate a list of options:

Property	Required	Description
values	Yes	The value that the field receives when the user selects it from the drop-down.
labels	No	The values that are displayed in the drop-down list for the users. You can use this resource in cases that the values are not simple to understand for the user, for example: If your values links to an object that returns language codes, you can use labels to link to an object that returns the language names. Therefore, the language names are displayed in the drop-down while the values that are received to the input is the language code.

To map the values and labels properties, create a link to the output object that populates the list of values. That link is based on the hierarchy of object properties in the response schema.

You can create a link for simple objects, complex objects, or arrays at the root level. The structure of these links might vary based on how an object is built. The following are examples of these structures:

Link to a simple object:

<object_property_name>

Link to a simple object with multiple properties:

<object_property_name>.properties.<object_property_name>

Link to a complex object that nest an array:

<object_property_name>.items

Link to a complex object that nest an array of objects

<object_property_name>.items.properties.<object_property_name>

Link to an array at the root level

items.properties.<object_property_name>

Note: For complex objects and arrays, you need to specify the mappings section. Otherwise, the mappings section isn't needed.

{
  "params": {
    "input": "value"
  }
}

{
  "params": {
    "input": {
      "name": "inputMapped",
      "value": "__reference__"
    }
  }
}

{
  "paths": {
    "/skill1": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "startWith": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

{
  "paths": {
    "/skill2": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "usersFilter": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string",
                    "x-ibm-ui-extension": {
                      "component": "dropdown",
                      "actions": [
                        {
                          "skill_id": "app_id__1.0.0__skill1",
                          "type": "data",
                          "mappings": {
                            "labels": "user.items.properties.name",
                            "values": "user.items.properties.id"
                          },
                          "params": {
                            "startWith": "J"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

{
  "paths": {
    "/skill2": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "usersFilter": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string",
                    "x-ibm-ui-extension": {
                      "component": "dropdown",
                      "actions": [
                        {
                          "skill_id": "app_id__1.0.0__skill1",
                          "type": "data",
                          "mappings": {
                            "labels": "user.items.properties.name",
                            "values": "user.items.properties.id"
                          },
                          "params": {
                            "startWith": {
                              "name": "usersFilter",
                              "value": "__reference__"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Showing input fields dynamically

With the x-ibm-ui-extension property, you can enhance input fields to turn them into dynamic input fields. Use this property to show inputs dynamically based on previous input values.

To configure dynamic input fields, add the x-ibm-ui-extension property in the input schema that should be shown dynamically. Then, configure the following properties:

The following example shows how to configure one dynamic input field based on other skill input. In this example, the email input field is shown when the using input receives the Email value.

{
  "paths": {
    "/skill": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "using": {
                    "type": "string",
                    "enum": [
                      "Email"
                    ]
                  },
                  "email": {
                    "type": "string",
                    "x-ibm-ui-extension": {
                      "title": "Email",
                      "component": "string",
                      "expressions": [
                        {
                          "type": "display",
                          "connector": "AND",
                          "rules": [
                            {
                              "referencePropertyName": "using",
                              "operator": "equals",
                              "valuesToCompare": [
                                "Email"
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

{
  "x-ibm-ui-extension": {
    "expressions": [
      {
        "type": "display",
        "connector": "AND",
        "rules": [
          {
            "referencePropertyName": "using",
            "operator": "equals",
            "valuesToCompare": [
              "Email"
            ]
          }
        ]
      }
    ]
  }
}

Configuring output list pagination

You can configure pagination to your output lists. Configure the pagination by using the x-ibm-pagination property. Exist two ways to create a pagination.

{
  "paths": {
    "/getItems": {
      "get": {
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "x-ibm-visible": false,
            "x-ibm-show": false,
            "explode": true,
            "schema": {
              "type": "string",
              "default": "30",
              "x-ibm-pagination": {
                "pagination": true,
                "isLimit": true
              }
            },
            "x-ibm-label": "limit",
            "x-ibm-order": 1
          },
          {
            "name": "skip",
            "in": "query",
            "explode": true,
            "x-ibm-show": false,
            "x-ibm-visible": false,
            "schema": {
              "default": "10",
              "type": "string",
              "x-ibm-pagination": {
                "pagination": true,
                "isSkip": true
              }
            },
            "x-ibm-label": "skip",
            "x-ibm-order": 2
          }
        ]
      }
    }
  }
}

{
  "paths": {
    "/getItems": {
      "get": {
        "parameters": [
          {
            "name": "nextPageToken",
            "in": "query",
            "x-ibm-visible": false,
            "x-ibm-show": false,
            "explode": true,
            "schema": {
              "type": "string",
              "x-ibm-pagination": {
                "pagination": true,
                "isNextPageToken": true
              }
            },
            "x-ibm-label": "nextPageToken",
            "x-ibm-order": 2
          }
        ]
      }
    }
  }
}