Commands

Commands are reusable requests that can be executed through the Kustomer API. Commands provide a simple wrapper that allows custom components in Kustomer to interact with external services.

Apps can configure commands for use by Klass Views (KViews), widgets, or workflows also configured by the app. Apps can also configure commands to be available to custom code (for example, configuring a button within a KView or a widget to call a command).

Commands have several benefits over API calls made directly from an iFrame:

• Commands can access app settings to:
  • Make it easy to customize commands for each Kustomer organization
  • Make it possible to use authorization tokens without exposing the tokens to agents
• Command execution can be recorded in the audit log to:
  • Make it easy for administrators to track usage of commands

Commands format in the app definition

The commands property takes an array of properties that define the following for each command: a unique name, a display name, the target URL, the HTTP method, the names of variables that can be interpolated into the URL, app settings, and optional input and output JSON schema for the request and response body.

commands definition example

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

{
  "app": "ecommstore",
  "version": "0.0.1",
  "title": "E-comm Store",
  "commands": [{
    "name": "ecommstore.app.store.refundOrder",
    "displayName": "Refund Order",
    "permittedArgs": ["store"],
    "url": "https://{{{store}}}.example-ecommstore.com/orders",
    "httpMethod": "post",
    "auditLogging": true,
    "cacheSeconds": 15,
    "appSettings": {
      "authToken": {
          "key": "ecommstore.default.authToken"
      }
    },
    "inputSchema": {
       "type": "object",
       "properties": {
         "foo": {
           "type": "string"
         }
       },
       "additionalProperties": false,
       "required": [
         "foo"
       ]
    }, 
    "outputSchema": {
       "type": "object",
       "properties": {
         "foo": {
           "type": "string"
         }
       },
       "additionalProperties": true,
       "required": []
    }
  }]
}

Commands property descriptions

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

name

Required. A globally unique name for the command. Command names should be prefixed with <app name>.app.* .

Validation: Must be globally unique.

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

displayName

A display name for the command. The display name is used for metadata in the command definition but may appear in the Kustomer UI in the future.

Example: "displayName": "Refund Order"

permittedArgs

An array of the names of variables that can be interpolated into the URL, headers, or body using the Handlebars notation. Variable string values can be defined when the command runs. If a value is not provided when the command runs, the variable value resolves to an empty string.

Example: "permittedArgs": ["store"]

url

Required. The URL that the command will target for the request. When the names of variables are defined in permittedUrlArgs, you can use the Handlebars notation to reference where in the URL to inject the variable values defined when the command runs.

Example: "url": "https://{{{store}}}.example-ecommstore.com/orders"

httpMethod

Required. The HTTP method or verb for making the request. Available methods: get, post, put, patch, or delete.

Example: "httpMethod": "post"

auditLogging

Optional. A boolean flag to enable audit-logging of command runs.

Example: "auditLogging": true

cacheSeconds

Optional. A number value between 15 and 600 to enable client-side caching and Cache Fallback Mode.

Example: "auditLogging": 15

Cache Fallback Mode

• We cache every command run response for 24 hours but add a timestamp so we know when a response is older than cacheSeconds
• When Cache Fallback Mode is deactivated, and we find a cached response, we still fetch live data if the cached value is older than cacheSeconds
• When the external API returns a 4xx or 5xx error response status (e.g. daily request limit exceed), Cache Fallback Mode gets activated for the current combination of org ID, command name, URL, request headers and request body
• When Cache Fallback Mode is activated
  • we return cached values even when they are older than cacheSeconds
  • we try to fetch data from the external API every on every 5th command run to check if we receive a response status < 400 again
    • if we receive live data again, Cache Fallback Mode gets deactivated

appSettings

The app settings used by the command. The appSettings property contains a JSON object authToken with values for a key that provides the variable's name to be interpolated into the command headers and body when the command 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"
      }
    }

appAccountName

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

appSettings.authToken.key

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

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

inputSchema

An optional schema that validates the input JSON body of a command. 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 command to the corresponding 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": {
       "type": "object",
       "properties": {
         "foo": {
           "type": "string"
         }
       },
       "additionalProperties": false,
       "required": [
         "foo"
       ]
    }

outputSchema

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

Example:

    "outputSchema": {
       "type": "object",
       "properties": {
         "foo": {
           "type": "string"
         }
       },
       "additionalProperties": true,
       "required": []
    }

Run Commands with the Kustomer API

You can run a command that has been defined using the Kustomer API with the following commands endpoint: /v1/commands/{command name}/run

The example API call below runs the ecommstore.app.store.refundOrder command:

POST https://api.kustomerapp.com/v1/commands/ecommstore.store.refundOrder/run

{
  "body": {
  	"refundOption": true
  },
  "headers": {
   "Authorization": "Bearer {{authToken}}"
  },
  "args": {
   "store": "dunder-mifflin"
  }
}

body

The body of the request sent to the commands endpoint.

Example: "body": {"refundOption": true}

headers

The headers to the command request formatted as a set of key value pairs.

Example: "headers": {"Authorization": "Bearer {{authToken}}"}

📘

Note

If your token includes special characters you will need to place the token in triple brackets {{{authToken}}} to encode the token as a string.

args

An object that represents key-value pairs in which:

• the key maps to a subset of the permittedArgs variables defined in the command
• the value of each key defines the string value to interpolate in the variable referenced in the command URL.

Example: "args": {"store": "dunder-mifflin"} with "store" as the permittedArgs variable and "under-mifflin" as the string value from the command definition.

For the example above, the command has the following URL in its definition:
https://{{{store}}}.example-ecommstore.com/orders.

When the command runs, because the arg provided for "store" is "dunder-mifflin", the URL will resolve to the following:

https://dunder-mifflin.example-ecommstore.com/orders

Caution: if you need to interpolate a secret value, e.g. an API key into a header, you should use a secret appSetting instead of an arg, since args can appear in audit logs.

Run Commands with the Cards SDK

The Cards SDK provides helper functions for working with commands. You can use the Kustomer.command.run() function to access the Kustomer API directly using JavaScript.

You can make the previous API call in the section "Running Commands with the Kustomer API" in JavaScript using the Cards SDK:

const refundOrder = async () => {
  try {
    const response = await Kustomer.command.run('ecommstore.store.refundOrder', {
      body: { "refundOption": true},
      headers: {
       Authorization: "Bearer {{authToken}}"
      },
      urlArgs: {
       store: "dunder-mifflin"
      }
    })
    // do something with the response
  } catch(errResp) {
    const [err, data] = errResp;
    console.error(err);
  }
};