Configuring inputs and outputs types for your skills

Date

To configure a date input or output combine a type: string property with the format: date property in your input or output schema.

{
  "type": "string",
  "format": "date"
}

The date format is a simple date field where is requested or displayed for the user a year, month, and day of the date.

Date and time

To configure a date and time input or output, combine a type: string property with the format: date property in your input or output schema.

{
  "type": "string",
  "format": "date-time"
}

The date and time format requests or displays for the user a year, month, day, hour, minute, period, and time zone of the date.

EPOCH

You can use type: string or type: integer properties with the format: epoch property to configure dates in EPOCH format.

{
  "type": "integer",
  "format": "epoch"
}

When an EPOCH date is configured, for an input it is displayed for the user as a text or numeric input field. In the other hand, for outputs the EPOCH date is displayed in a human readable format. It follows the structure: YYYY-MM-DD.

Configuring operators of elements in queryable parameters

Use the x-ibm-supported-operators property to configure the operators of an element in a queryable parameter.

To configure the x-ibm-supported-operators property, add the property inside the schema of the queryable parameter. Then, in the property configure a list with of operations the element supports.

On watsonx Orchestrate, only the equivalence operator is supported. Therefore, configure the and list and then use eq to configure the equivalence operation.

The following example shows how to configure the x-ibm-supported-operators property:

{
  "parameters": [
    {
      "x-ibm-queryable-fields": {
        "properties": {
          "id": {
            "x-ibm-supported-operators": {
              "and": [
                "eq"
              ]
            }
          }
        }
      }
    }
  ]
}

Fixed list of options

A fixed list of options is the one that you as a developer, previously configured for the user.

You can configure the values of the list of options directly in the OAS file. To do it, configure an enum list in the OAS file.

To configure a fixed list of options, add the enum list in the input schema and then list all possible input options. The options that are listed in that enum list need to be in the same type of the input schema. For example, whether or input is a string all values that are listed in that list need to be a string type.

{
  "type": "string",
  "enum": [
    "A",
    "B",
    "C"
  ]
}

Dynamic list of options

A dynamic list of options is generated automatically in a dynamic form based on the output of other skills. You configure a dynamic list of options with the x-ibm-ui-extension.

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

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

{
  "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

In the mappings specify the values and labels, it defines how the data gathered from a specific skill can populate a list of options:

To map the values and labels properties, create a link to the output object that populates the list of values. The 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>

Mapping inputs of the skill that generate the list of options

If the skill used to generate the list of options has inputs, you can map the 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 params with a static value, in the params property add the input from the skill you want to map and set a static value for the 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:

The following snippet exemplifies a dynamic mapping:

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

Example:

To examplify the input mapping, suppose the skill that generates the data for the list of options has one input named startWith as shown below:

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

Then, to map the startWith input with a static value you must add the input in the params property and set the static value as in the below snippet:

{
  "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 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__"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Single file

To create a single file input, combine the type: "string" and format: binary properties in your skill schema.

{
  "type": "string",
  "format": "binary"
}

This configuration presents a file upload widget to the user as skill input. It accepts a single file and sends a JSON payload to the API with the content of the uploaded file as a base64 encoded string.

Multiple files

You can create a multifile upload widget to allow users to upload any number of files to the API. To do it, configure the single file schema inside an array and object schema.

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "fileName": {
        "type": "string"
      },
      "content": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}

This configuration presents a file upload widget to the user as skill input. It accepts multiple files and sends a JSON payload to the API with the content of the uploaded file as a base64 encoded string.