Workflow Actions

Workflow actions are reusable elements of a workflow that any workflow can use to interact with Kustomer and with external services. Apps can configure workflow actions to be used in the workflows also configured by the app or in custom user workflows.

Workflow Actions format in the app definition

The workflow actions property takes an array of properties that define the following for each workflow action: a unique name, a workflow action description and type, app settings, the structure of values to be entered and returned from the workflow action, and optional input and output JSON schema for the request and response body.

Workflow actions definition example

The following sample JSON app definition includes a workflow actions property definition that creates and configures the workflow action ecommstore.store.refundOrder in Kustomer.

{
  "app": "ecommstore",
  "version": "0.0.1",
  "title": "E-comm Store",
  "actions": [{
    "name": "kustomer.app.ecommstore.store.refundOrder",
    "description": "Refund Order",
    "type": "rest_api",
    "appSettings": {
      "authToken": {
          "key": "ecommstore.default.authToken"
      }
    },
    "inputTemplate": {
      "uri": "https://api.ecommstore.com/orders/{{orderId}},
      "method": "POST",
      "headers": {
      	"authorization": "Bearer {{authToken}}"
    	},
      "qs": "/#querystring",
      "data": {
        refund: true
       },
      "json": true
    },         
    "sampleOutputContext": {
      "data": {status: "REFUNDED"}
    },
    "inputSchema": {
      "properties": {
        "querystring": {
          "type": "string",
        }
      },
      "required": [],
      "additionalProperties": false
    }, 
    "outputTemplate": {
      "response": "/#response"
      "body": "/#body"
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "response": {
          "type": "object"
        },
        "body": {
          "type": "object"
        }
      },
      "additionalProperties": false
    }
  }]
}

Workflow Action properties

The basic workflow actions definition properties and their descriptions are listed below:

name

Required. The primary id for the workflow action. Workflow action names should be prefixed with kustomer.app.<app name>.* .

Validation: Must be globally unique. Must use alphanumeric characters,., - and _. Max length of 128 characters, including spaces.

Example: "name": "kustomer.app.ecommstore.store.refundOrder" for an app with the app id ecommstore.

description

A meaningful summary of what the workflow action does.

Validation: Max length of 4096 characters, including spaces.

Example: "description": "Refund Order"

type

Required. A type for the workflow action. Must be always set as rest_api.

Example: "type": "rest_api"

appSettings

The app settings used by the workflow action. The appSettings property contains a JSON object authToken with values for a key that provides the name of the variable available to be interpolated into the inputTemplate when the workflow action runs. authToken contains an object with a key property that provides the lookup string for the app setting.

Example:

"appSettings": {
      "authToken": {
          "key": "ecommstore.default.authToken"
      }
    }

appSettings.authToken.key

The lookup string for the app setting. Format as "key": "<app>.<category>.<value>".

Example: "key": "ecommstore.default.authToken"

appAccountName

The name of an app account being referenced from a configured Oauth 2.0 client. For example usage, please refer to the OAuth 2.0 client documentation.

inputTemplate

Defines the structure of the values entered into the workflow action. A JSON object that takes the following properties depending on the type of the action.

Type: rest_api

• uri
  • The URL to make a request to. You can reference values from the inputSchema property as needed using Handlebars syntax.
  • Example: "uri": "https://api.ecommstore.com/orders/{{orderId}}
• method
  • The HTTP method or verb for making the request. Available methods: get, post, put, patch, or delete.
  • Example: "method": "POST"
• headers
  • The headers for the request. Formatted as an object with key-value pairs for each header. You can reference values from appSettings property as needed using Handlebars syntax.
  • Example: "authorization": "Bearer {{authToken}}"
• qs
  • The query string for the request. The /#<value> syntax replaces the value with a value from the inputSchema property.
  • Example: "qs": "/#querystring"
• data
  • The body of the request as an object. You can reference values from the inputSchema property as needed using Handlebars syntax.
  • Example: "data": {refund: true}
• json
  • A boolean determining whether the request should be parsed as a JSON body.
  • Example: "json": true

outputTemplate

Defines the structure of the values returned by the workflow action to the next step in the workflow.

In the case of a rest_api action, you can refer to the body of a rest response via /#body and the full contents of the response object via /#response. If you specified json: true in the inputTemplate, the body will be parsed as an object. If not, the body with be returned in string format

outputTemplate is defined as a JSON object that maps values from the outputSchema property using Handlebars syntax and the /#<value> syntax. This allows you to replace a whole section of JSON with a block from the outputSchema.

Example: "outputTemplate": {"body": "/#body"}

sampleOutputContext

A sample of expected output data from a workflow action. You can use sampleOutputContext to improve usability in the workflow builder.

Example: "sampleOutputContext": {"body": {status: "REFUNDED"}}

inputSchema

An optional schema that validates the input JSON body for a workflow action. The schema validation uses a subset of the JSON schema validation specification.

• The schema supports the following data types: string, boolean, number, object, and array.

• The schema supports the following top level object types: properties, required, and additionalProperties.

The schema defined in inputSchema automatically converts properties in the input JSON body of a workflow action to the type specified in the schema.

• If required properties are not specified in the request body, the request will be rejected.

• If additionalProperties are specified in the request body but not permitted in the schema, the request will be rejected.

Example:

"inputSchema": {
      "properties": {
        "querystring": {
          "type": "string",
        }
      },
      "required": [],
      "additionalProperties": false
    }

outputSchema

An optional schema that filters and converts the output JSON response of a workflow action invocation. If an outputTemplate is provided, the response is filtered and formatted through the output template first before being passed through the outputSchema.

The schema validation uses a subset of the JSON schema validation specification.

• The schema supports the following data types: string, boolean, number, object, and array.

• The schema supports the following top level object types: properties, required, and additionalProperties.

The schema defined in outputSchema automatically converts properties in the output JSON body of a workflow action to the type specified in the schema.

• If a required property in the output body is not specified, the property won't be transmitted in the response.

• If additionalProperties are provided when additionalProperties are defined as false, those properties will be filtered out of the response object.

Example:

 "outputSchema": {
      "type": "object",
      "properties": {
        "response": {
          "type": "object"
        },
        "data": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }