Commands

A command action instructs the client application to perform a task. It defines the API for communication between Diatheke and the code that performs the business logic. For example, in a story for calling another user in the system, Diatheke may first return a lookup command with the name the user specified as an input parameter. The client application would query its own back-end to determine whether the person with that name is an available user, and would return the result of that lookup as an output parameter.

Because this defines the API, it is strongly encouraged to use comments to document information about each parameter. Comments can be included in the yaml file by starting a line with #.

All parameter values are passed as strings.

Properties of a command action

Example

# This command does a lookup for the given user name. It
# also checks availability status.

inputs:
  - user_name

outputs:
  # (Required) This indicates what condition was found.
  # The following shows expected values for this parameter:
  #
  #  "not_found" = could not find a user with the given user_name
  #  "unavailablet" = the recipient is not available
  #  "available" = the recipient is available
  #  "multiple" = there are multiple recipients who match user_name
  - user_status

  # (Required) The first name of call recipient
  - first_name

  # (Required) The last name of the first matching call recipient
  - last_name1

  # (Optional) Comma-separated list of additional last names if 
  # there are multiple people who match user_name
  - last_name2

Fulfillment Webhook

A command may optionally be handled by webhook. If the use_webhook field is set to true, Diatheke will attempt to make an http/https POST request to the fulfillment webhook specified in the Diatheke server config. It is important to note that when a webhook is used, the server will make the request and execute the command immediately when it is encountered in a story. Commands that don’t have a webhook are returned to the client application as part of a list of actions to be executed whenever the client application chooses.

If Diatheke is unable to successfully make the POST request, or if there is an error parsing the returned response body, it will be treated as a fatal error (i.e., Diatheke will log the error and return to the main story of the model).

Webhook Request Body

{
  "id": "some_command_id",
  "modelID": "diatheke_model_id",
  "sessionID": "unique_session_id",
  "inputParameters": {
    "param1": "val1",
    "param2": "val2"
  },
  "metadata": "serialized_data",
}

Webhook Response Body

{
  "id": "some_command_id",
  "outParameters": {
    "param3": "val3",
    "param4": "val4"
  },
  "error": "Error message to be logged for fatal errors",
  "metadata": "serialized_data"
}