Commands
Learn how to configure Commands to be used by Klass Views, widgets, and workflows in your app. This page includes descriptions and examples for defining commands in a Kustomer app.
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
- we return cached values even when they are older than
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);
}
};
Updated 7 months ago