Understanding x-ibm properties
See how to use the x-ibm properties to enhance your app and skills configurations.
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:
| Value | Description |
|---|---|
public |
Define that the app and skills in the OpenAPI specification are public. It is the default value for all imported skills if the x-ibm-skill-subtype property is not configured. |
private |
Define that the app and skills in the OpenAPI specification are private. For private skills, you need to configure the secure tunnel. For more information about secure tunnels, see Configuring secure tunnel. |
The following example shows how to use the x-ibm-skill-subtype property.
{
"info": {
"x-ibm-skill-subtype": "public"
}
}
Configuring a secure tunnel
A Secure Tunnel provides endpoint-to-endpoint connections across a network without opening firewall rules in an enterprise network. It allows access between different networks through TCP over HTTPS technology. The traffic through these connections is encrypted with HTTPS.
The secure tunnel configuration is made with the help of the IBM Support. For more information about how to contact the IBM Support and open a case, see Support.
Open a support case to modify your tenant configurations for a tunnel connection and application mapping. Include the following information in the case:
- Hostname: The hostname or IP address for the API in your private network:
https://my-env-dev.nonprod.example.com. - Platform: The platform that your host is running, for example:
virtual machine (VM). - watsonx Orchestrate crn details: To know the crn ID, click your profile and then About. Send the screenshot of the About page.
After your case is processed, you receive an installer with instructions to install on your environment to complete the secure tunnel configuration.
Then, you are ready to use private skills that use this secure tunnel. To configure a private skill, set the x-ibm-skill-subtype property to private in your OAS file.
The following example shows how to configure a private skill:
{
"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"
}
}
Getting information about skill usage
Use the x-ibm-skill-headers property to configure the headers that pass extra information about the skill usage. The headers that are configured in this property are sent to the skill's API whenever the user uses the skill. Therefore,
in your skill's API you can use these headers values according to your business needs, for example to authenticate watsonx Orchestrate users in your API based on caller-name and caller-id that are received from the headers.
Considerations for using the property
You must do additional configurations if you want to get information about skill usage from conversations that happen on the AI agent chat embeded in external web pages.
Configure user_payload as a private claim when you enable the web chat security for the AI agent chat to get data from the caller-id, caller-name, and user_payload properties. For the skill-utterance and session-history properties, the encryption is not required.
For more information, see Encrypting sensitive data in web chat.
Configuring the headers
Configure the x-ibm-skill-headers property by adding it in the info section. For each header available, define the name that you want to give to the header. The following table describes the properties and their details:
| Property | Required | Accepted values | Description |
|---|---|---|---|
caller-id |
no | string |
Set a value to be the header name for the header that passes the caller-id information. |
caller-name |
no | string |
Set a value to be the header name for the header that passes the caller-name information. |
skill-utterance |
no | string |
Set a value to be the header name for the header that passes the skill-utterance information.Note: This header receives values only if the skill is used through AI assistants deployed in a channel or the AI agent chat of watsonx Orchestrate .
|
user-payload |
no | string |
Set a value to be the header name for the header that passes the user-payload information.Note: This header receives values only if the skill is used through AI assistants with security enabled deployed in a channel or the AI agent chat of watsonx Orchestrate.
|
session-history |
no | string |
Set a value to be the header name for the header that passes the session-history information.Note: This header receives values only if the skill is used through AI assistants deployed in a channel or the AI agent chat of watsonx Orchestrate .
|
The following example shows how to configure x-ibm-skill-headers property. For this example, the headers names are: X-CUSTOM-CALLER-ID, X-CUSTOM-CALLER-NAME X-CUSTOM-USER-PAYLOAD, X-CUSTOM-SKILL-UTTERANCE,
and X-CUSTOM-SESSION-HISTORY.
{
"info": {
"x-ibm-skill-headers": {
"caller-id": "X-CUSTOM-CALLER-ID",
"caller-name": "X-CUSTOM-CALLER-NAME",
"user-payload": "X-CUSTOM-USER-PAYLOAD",
"skill-utterance": "X-CUSTOM-SKILL-UTTERANCE",
"session-history": "X-CUSTOM-SESSION-HISTORY"
}
}
}
When this property is defined, the configured headers are sent to the external API referenced by the skill as header parameters. They cannot be sent as explicit parameters or body. How you get these headers and use them in the API depends on your business needs.
The following example is a Python script that shows how to retrieve the headers from a sample API and return the data from them to the user.
from fastapi import FastAPI, APIRouter, Request
app = FastAPI()
router = APIRouter()
@router.get("/headersGet")
async def getHeaders(request:Request) -> dict:
headers = {}
if request.headers.get("X-CUSTOM-CALLER-ID"):
headers["X-CUSTOM-CALLER-ID"] = request.headers.get("X-CUSTOM-CALLER-ID")
if request.headers.get("X-CUSTOM-CALLER-NAME"):
headers["X-CUSTOM-CALLER-NAME"] = request.headers.get("X-CUSTOM-CALLER-NAME")
if request.headers.get("X-CUSTOM-USER-PAYLOAD"):
headers["X-CUSTOM-USER-PAYLOAD"] = request.headers.get("X-CUSTOM-USER-PAYLOAD")
if request.headers.get("X-CUSTOM-SKILL-UTTERANCE"):
headers["X-CUSTOM-SKILL-UTTERANCE"] = request.headers.get("X-CUSTOM-SKILL-UTTERANCE")
if request.headers.get("X-CUSTOM-SESSION-HISTORY"):
headers["X-CUSTOM-SESSION-HISTORY"] = request.headers.get("X-CUSTOM-SESSION-HISTORY")
data = {"headers": headers}
return data
app.include_router(router)
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
}
}
}
}
x-ibm is not applicable for skills that are used through the AI agent chat.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.
| Boolean | Definition |
|---|---|
true |
Default. Enable the skill usage by AI assistants. |
false |
Disable the skill usage by AI assistants. |
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 projects
If you want to use imported skills on projects, you must wrap the skills schemas to be recognized by the project. 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
}
}
}
}
}
}
}
}
}
}
}
}
}
x-ibm is not applicable for skills that are used through the AI agent chat.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:
| Property | Description |
|---|---|
| entity | The field that receives the mapped input value from the user message. Use the input name to configure it. |
| values | A list of the input values and its mappings. Use the type, value, and synonyms properties to configure each input value.
|
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}"
]
}
]
}
]
}
}
}
}
x-ibm is not applicable for skills that are used through the AI agent chat.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.
x-ibm-nl-output-template property, only the message that was configured in this property is shown.
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:
| Value | Description |
|---|---|
| skill-utterance | To automatically fill the field by using the skill utterance. |
| skill-history | To automatically fill the field by using the skill history. |
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:
- Create a field.
- Set
x-ibm-disabletotrue. - Use the
x-ibm-labelto set an empty string"". - In
defaultset the instructions. - Use the
x-ibm-orderto 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.
For multi-turn conversation, it is also the messages that are displayed to request and show the skills inputs and outputs.
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.
| Property | Required | Description |
|---|---|---|
x-ibm-message-template |
yes | The text that is displayed when the skill run fails. It replaces the default text: "The <your skill name> skill can't be used right now. Retry your request later.".You can concatenate this text with a message that your skills return when it fails. To do it, add the {error-msg} placeholder in your text and then configure the x-ibm-message-abs-path property. |
x-ibm-message-abs-path |
no | The path for the property that returns the error message when your skill fails. The message that is retuned in this property replaces the {error-msg} placeholder that is configured in the x-ibm-message-template property. |
The following example shows how to configure the x-ibm-display-message-ref property with the x-ibm-message-abs-path property to display an error message.
{
"paths": {
"/skillPath": {
"post": {
"responses": {
"403": {
"description": "Error",
"x-ibm-display-message-ref": {
"x-ibm-message-template": "An error occurred."
}
}
}
}
}
}
}
The following example shows how to configure the x-ibm-display-message-ref property with the x-ibm-message-abs-path and x-ibm-message-template properties to display an error message.
{
"paths": {
"/skillPath": {
"post": {
"responses": {
"403": {
"description": "Error",
"x-ibm-display-message-ref": {
"x-ibm-message-abs-path": "message",
"x-ibm-message-template": "An error occurred. {error-msg}"
}
}
}
}
}
}
}
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.
To configure the single line and multiline fields, add the x-ibm-multiline property in the input or output schema and then set one of the following values in boolean or text format:
| value | Description |
|---|---|
| true | Set the field as multiline. |
| false | Keeps the field as a single line. It is the default value if the x-ibm-multiline property is not configured. |
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"
},
"word": {
"type": "string",
"x-ibm-multiline": false
}
}
}
}
}
}
}
}
}
}
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 and show more sections, add the x-ibm-important property in the input schema and then set one of the following values in boolean or text format:
| value | Description |
|---|---|
| true | Set the input for the main section. |
| false | Set the input to the show more sections. If you configure at least one input as true, all other inputs where the x-ibm-multiline property is not configured use this value as the default one. |
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": {
"id": {
"x-ibm-important": true
},
"dogName": {
"x-ibm-important": "true"
},
"category": {
"x-ibm-important": "true"
},
"animal": {
"x-ibm-important": true
},
"status": {
"x-ibm-important": false
}
}
}
}
}
}
}
}
}
x-ibm-important property must be placed outside of items section if the data type is an array.The following example shows the x-ibm-important property with the data type as an array.
{
"paths": {
"/skillPath": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"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:
| Property | Description |
|---|---|
| skill_id | The unique ID of the skill. This ID follows the structure: <info.title>__<info.version>__<paths[].path.operation.operationId>. For prebuilt apps, you get the skills ID in Skill IDs for prebuilt apps. |
| utterance | The name of the next skill. |
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"
}
}
}
}
}
}
}
}
}
}
Mapping values for the next best skills
To map values to the next best skills specified in the OpenAPI specification, add an element configuration and define the property mappings in it.
In the property mappings, you specify the sourceSkill, targetSkill, and values for the mapped fields. The items that you need to define in the mappings includes:
| Property | Description |
|---|---|
sourceSkill |
The skill ID of the skill from which the value is mapped from. |
targetSkill |
The skill ID of the skill to which the output is mapped to. |
fieldMapping |
In the fieldMapping, you can add information about the output field of the source skill and input field of the target skill. |
In the property fieldMapping, you can configure:
| Property | Description |
|---|---|
sourceSkill |
The flattened field name of the output from the source skill. |
targetSkill |
The field that is mapped to the output of the source skill. |
displayName |
The flattened field name of the source skill. |
The following example demonstrates how to define a next best skill with mappings in an OpenAPI specification. In this example, the Get all the branches skill has no mappings, whereas the Create a bucket skill has mapped fields.
{
"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:
| Property | Required | Description |
|---|---|---|
| component | Yes | The field type, it must be dropdown. |
| pagination | No | Define the skip and limit of the list of options.
|
| actions | Yes | Define the skill_id, type, mappings, and params of the skill that you want to pull data to the list of options.
|
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>
mappings section. Otherwise, the mappings section isn't needed.Mapping inputs of the skill that generate the list of options
If the skill that is used to generate the list of options has inputs, you can map these inputs by using params. In the params property, you can map a static value or a dynamic value based on other skill input.
To map a params with a static value, in the params property add the input from the skill that you want to map and set the static value for this input. The following snippet exemplifies a static mapping:
{
"params": {
"input": "value"
}
}
To map params with a dynamic value, in the params property add the input from the skill that you want to map and then map the input that receives the dynamic value by the user when the skill is used. To map that input,
use the following properties:
| Property | Required | Description |
|---|---|---|
| name | Yes | The name of the input to be mapped with the input of the skill that generates the list of options. The input can be one input that your skill already has or you can create one input in your skill only for propose. |
| value | Yes | The value that is received from the mapped input. It must be __reference__ to pass the value that the user set in the input field. |
The following snippet exemplifies a dynamic mapping:
{
"params": {
"input": {
"name": "inputMapped",
"value": "__reference__"
}
}
}
Example:
To examplify the input mapping, suppose that the skill that generates the data for the list of options has one input that is called startWith.
{
"paths": {
"/skill1": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"startWith": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
Then, to map the startWith input with a static value you need to add this input in the params property and set the static value:
{
"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"
}
}
]
}
}
}
}
}
}
}
}
}
}
}
Or, to a map the startWith input with a dynamic value you need to add this input in the params property and configure the name property with one of the skill inputs and the value property
as __reference__:
{
"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:
| Property | Required | Description |
|---|---|---|
title |
no | The input field title, it overwrites the title that is defined in the name and x-ibm-label properties in the input schema. |
component |
yes | The field type, it overwrites the type that is defined in the type property in the input schema. The accepted values are:
|
expressions |
yes | A list of connections and the rules to dynamically show the input field. For more information, see Configuring dynamic input fields expressions. |
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"
]
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
Configuring dynamic input fields expressions
Use the expressions property in the x-ibm-ui-extension to configure a list of connections and the rules to dynamically show an input field. For each item of this list, configure the following properties:
| Property | Required | Description |
|---|---|---|
type |
yes | The input action when one of the rules that are defined in the rules property is true.It must be display to show the input field dynamically. |
connector |
yes | The connector for the rules defined on the rules property.It must be AND. Therefore, if any rule is true then the input field is shown. |
rules |
yes | A list of rules used to show the input field. For each rule, you need to configure:
|
The following example shows how to configure the expressions property.
{
"x-ibm-ui-extension": {
"expressions": [
{
"type": "display",
"connector": "AND",
"rules": [
{
"referencePropertyName": "using",
"operator": "equals",
"valuesToCompare": [
"Email"
]
}
]
}
]
}
}
Configuring output list pagination
Some APIs might not return all the items in a single request. Therefore, when the user runs a skill it does not show all the possible items in one skill usage. Thus, the user must make multiple uses of the same skill to obtain all items from the API.
Use the x-ibm-pagination property with these APIs to make a pagination for the API responses. The pagination makes multiple requests for the API concatenating the items that are returned for each API response when the user uses
the skill. Therefore, the skill shows all the items in only one usage.
The x-ibm-pagination supports two types of APIs: the "skip" and "limit" API based, and the "next_page_token" API based. You identify the APIs based on the API parameters:
-
To identify an API based on skip and limit, search for the
skipandlimitinput parameters. The parameter names might vary from each API.parameter description skipThe number of items to be skipped to start the response. It is the position of the last item that is returned in the previous API request. limitThe maximum number of items returned by the API. The count of returned items starts from the first item that is found after the item set in skipparameter. -
To identify an API based on next page token, search for the
next_page_tokeninput parameter and thenext_page_tokenoutput response. The parameters name might vary from each API.parameter type description next_page_tokeninput The unique identifier of the items page that needs to be returned from the API. next_page_tokenoutput The unique identifier for the next page.
Configuring skip and limit pagination
To cofigure the pagination for an API based on skip and limit, first configure the skip and limit parameters responsible for the pagination. To do it, add the x-ibm-pagination property in these parameters schemas and then configure:
| Property | Description |
|---|---|
pagination |
Set it to true to identify the parameter as one of that is responsible for the pagination. |
isSkip |
Set it to true to identify the parameter as the skip parameter. Otherwise, don't configure this property. |
isLimit |
Set it to true to identify the parameter as the limit parameter. Otherwise, don't configure this property. |
Then, you need to configure the pagination. To do it, add the x-ibm-pagination property at the method level and then configure:
| Property | Description |
|---|---|
type |
Set it to skip-limit to identify the pagination as a skip and limit pagination. |
skip-parameter |
The JMESPath for the skip parameter. |
limit-parameter |
The JMESPath for the limit parameter. |
x-ibm-show property. For more information about the property, see Hiding inputs and outputs.The following example shows how to configure a skip and limit pagination.
{
"paths": {
"/skip-limit-pagination": {
"get": {
"parameters":[
{
"name": "skip",
"in": "query",
"schema": {
"type": "integer",
"x-ibm-pagination": {
"pagination": true,
"isSkip": true
}
},
"x-ibm-show": false
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"x-ibm-pagination": {
"pagination": true,
"isLimit": true
}
},
"x-ibm-show": false
}
],
"x-ibm-pagination": {
"type": "skip-limit",
"skip-parameter": "skip",
"limit-parameter": "limit"
}
}
}
}
}
Configuring next page pagination
To cofigure the pagination for an API based on next page token, first configure the token input parameter responsible for the pagination. To do it, add the x-ibm-pagination property in this parameter schema and then configure:
| Property | Description |
|---|---|
pagination |
Set it to true to identify this parameter as one of that is responsible for the pagination. |
isNextPageToken |
Set it to true to identify the parameter as the next page token parameter. |
jmesPath |
The JMESPath for the output that returns the next page token. |
Then, you need to configure the pagination. To do it, add the x-ibm-pagination property at the method level and then configure:
| Property | Description |
|---|---|
type |
Set it to token to identify the pagination as a next page token pagination. |
token-request-parameter |
The JMESPath for the input parameter that defines the page that is returned from the API. |
token-response-parameter |
The JMESPath for the output that returns the next page token in your API. |
x-ibm-show property. For more information about this property, see Hiding inputs and outputs.The following example shows how to configure a next page token pagination.
{
"paths": {
"/next-page-pagination": {
"get": {
"parameters":[
{
"name": "next_page_token",
"in": "query",
"required": false,
"schema": {
"type": "string",
"x-ibm-pagination": {
"pagination": true,
"isNextPageToken": true,
"jmesPath": "next.next_page_token"
}
},
"x-ibm-show": false
}
],
"x-ibm-pagination": {
"type": "token",
"token-request-parameter": "next_page_token",
"token-response-parameter": "next.next_page_token"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"next": {
"properties": {
"next_page_token": {
"type": "string",
"x-ibm-show": false
}
}
}
}
}
}
}
}
}
}
}
}
}