Workflows

Workflows are automations in Kustomer that combine triggers, or specified events from within Kustomer or from a connected service, and conditional logic to perform specified workflow actions (for example, add tags, assign users, create customers, or make calls to external systems).

Apps can configure workflows that make it easy for users to copy and customize the workflows as needed to automate repetitive manual processes or to build on their Kustomer platform with custom business logic.

You can use workflows in apps to process data entered into Kustomer from webhooks and to automate responses to changes to Customers, Conversations, and other standard and custom data objects on the Kustomer platform.

📘

Note

We currently recommend that you use the Workflows visual editor in Kustomer to design workflows and the conditional logic. You can export these workflows as JSON objects and modify the JSON objects as needed to use in the workflows definition for your app. See Generating a Workflows definition.

Workflows format in the app definition

The workflows property takes an array of properties that define the following for each workflow: a unique name, a workflow description, the trigger event for the workflow, and the steps in the workflow after the trigger event.

Workflows definition example

The following sample JSON app definition includes a workflows property definition that creates and configures the workflow simple-company-create-workflow in Kustomer.

{
  "app": "ecommstore",
  "version": "0.0.1",
  "title": "E-comm Store",
  "workflows": [{
    "name": "simple-company-create-workflow",
    "description": "Create a company from a request.",
    "trigger": {
      "eventName": "kustomer.app.ecommstore.company.create",
      "transitions": [
        {
          "target": "step2",
          "condition": {
            "op": "true",
            "values": [
              true
            ]
          }
        }
      ]
    },
    "steps": [
      {
        "transitions": [],
        "errorCases": [],
        "id": "step2",
        "action": "kustomer.company.create",
        "params": {
          "name": "/#steps.1.companyName"
        },
        "appVersion": "kustomer-^1.4.11"
      }
    ]
  }]
}

Workflows properties

The basic workflows definition properties and their descriptions are listed below:

name

Required. The primary id for the workflow. Can use alphanumeric characters, periods, hyphens, and underscores. Must be 128 characters or shorter, including spaces. The workflow name appears in the Kustomer UI and should be meaningful and human-readable.

Since workflow names are unique across workflows that are app-installed and user installed, you should make the name of your workflow as clearly coupled to the contents of your app as possible. Although using a user based workflow is often a great starting point for developing logic, you will need to update its name to be unique for your app in order to install the app in your own org.

Example: "name": "simple-company-create-workflow"

description

A short 1-3 sentence description of the workflow purpose. Max length of 4096 characters, including spaces. The workflow description appears in the Kustomer UI for administrators when they manage workflows.

Example: "description": "Create a company from a request."

trigger

Defines the trigger event trigger.eventName and trigger.transitions properties.

Example:

"trigger": {
      "eventName": "kustomer.app.ecommstore.company.create",
      "transitions": [
        {
          "target": "step2",
          "condition": {
            "op": "true",
            "values": [
              true
            ]
          }
        }
      ]
    }

trigger.eventName

The name of the trigger event that runs the workflow. The trigger event can be built in Kustomer or be defined by a trigger and hook pairing in the app.

Example: "eventName": "kustomer.app.ecomstorecompany.create"

trigger.transitions

An array of the connections to the "next steps" in the workflow.

Example:

"transitions": [
        {
          "target": "step2",
          "condition": {
            "op": "true",
            "values": [
              true
            ]
          }
        }
      ]

steps

A list of the workflow steps after the trigger.

Example:

"steps": [
      {
        "transitions": [],
        "errorCases": [],
        "id": "step2",
        "action": "kustomer.company.create",
        "params": {
          "name": "/#steps.1.companyName"
        },
        "appVersion": "kustomer-^1.4.11"
      }
    ]

Generate a workflow definition

At this time, we don't recommend that you write Kustomer workflows from scratch. Instead, we suggest that you do the following to create workflows:

1. Build a workflow in the Kustomer visual editor.
2. Export the workflow as a JSON definition.
3. Edit and change the JSON definition as needed for your app.

Modify exported definitions

Common changes you can apply to an exported JSON workflows definition for your app include the following:

• Switching out a custom hook event for a hook event defined by your app
• Switching a hardcoded value to use App Settings

Use app versions to create definitions

Another option for creating a workflow definition is to do the following:

1. Create a version of your app that exposes any workflow actions and app settings.
2. Use the workflow editor to incorporate those elements into your workflow.
3. Create a new version of the app that incorporates the workflow.