Triggers

Learn how to configure Triggers for your app. This page includes descriptions and examples for defining triggers for workflows in a Kustomer app.

You need the following to create an app that can configure a workflow to receive data from an external platform or service:

1. Hooks to define a URL that can receive data
2. Triggers to wrap hooks and give a meaningful name to the hooks for workflows to use
3. Workflows to define the logic for processing inbound data based on the defined triggers and hooks

Every workflow requires a trigger as an initial event because triggers are the entry point for workflows.

While apps can configure workflows that use default triggers, apps can also define their own triggers to be used by app-defined or custom workflows.

Triggers format in the app definition

The triggers property takes an array of properties that define the following for each trigger: a unique event name for the trigger, a trigger description, a template for how the trigger should format input data for the workflow, optional output data validation, and a sample of ecpected output data from the trigger to be included in the Kustomer Workflows visual editor.

The following sample JSON app definition includes a triggers property definition that creates and configures the trigger ecommstore.app.order.update.

Triggers Format In The App Definition

Sample app definition with defined `triggers` property

{
  "app": "ecommstore",
  "version": "0.0.1",
  "title": "E-comm Store",
  "triggers": [{
    "eventName": "kustomer.app.ecommstore.order.update",
    "description": "An Ecommerce Store order update event",
    "outputTemplate": {
      "orderId": "/#data.id",
      "orderAmount": "/#data.amount",
      "orderStatus": "/#data.info.status"
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        },
        "orderAmount": {
          "type": "string"
        },
        "orderStatus": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "sampleOutputContext": {
        "orderId": "123",
        "orderAmount": "27.50",
        "orderStatus": "FULFILLED"
    }
  }]
}

Triggers properties

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

eventName

Required. The globally unique primary id for the event that runs the trigger. The event name should correspond to a built-in Kustomer event or an event generated by a hook. To support debugging and to preserve the uniqueness of the name, prefix app-created event names with kustomer.app.<app-name>..

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

Example: "eventName": "kustomer.app.ecommstore.order.update" for an app with the app id ecommstore.

description

A meaningful summary of what the trigger does. While the description is used for metadata in the trigger definition, the description may appear in the UI in the future.

Example: "description": "An Ecommerce Store order update event"

outputTemplate

Defines the trigger accepts data (usually from an inbound webhook) and structures the data for a workflow to use.

outputTemplate is defined as a JSON object that maps values from the outputSchema property using the /#<value> syntax. This allows you to replace a whole section of JSON with a block from the outputSchema. You can use . dot notation in the sample definition above to access sub properties and to avoid sending through the whole data object.

Example:

JSON

 "outputTemplate": {
      "orderId": "/#data.id",
      "orderAmount": "/#data.amount",
      "orderStatus": "/#data.info.status"
    }

outputSchema

An optional schema that validates the output JSON body of a request. 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:

JSON

"outputSchema": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        },
        "orderAmount": {
          "type": "string"
        },
        "orderStatus": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  }

sampleOutputContext

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

Example:

JSON

"sampleOutputContext": {
        "orderId": "123",
        "orderAmount": "27.50",
        "orderStatus": "FULFILLED"
    }