Sunshine Workflows API
Important: The Sunshine Workflows API is in early access. This API is subject to change and should not be used in a production environment. Visit the Sunshine Workflows API EAP forum to provide feedback.
Introduction
A Sunshine workflow is a series of tasks performed in sequence to automate procedures in your Zendesk account. The tasks can interact with Zendesk resources such as tickets, custom objects, and more.
Workflows are represented by workflow definitions, which are JSON objects that contain all the relevant information about what work needs to be done and what data is necessary to complete that work.
To learn more, see Workflow API developer guide.
Sunshine Workflows schema
The Sunshine Workflows service requires that every workflow definition adhere to a schema that mandates certain requirements. Various fields must be given values; others must have values of a certain type. This section details the expectations of the schema and explores its restrictions in more depth.
Topics covered:
Global Required Fields
Global required fields are the top-level fields of a workflow definition that must be given a value. At present, these include the name
, description
, and tasks
fields. Note that for a task, the workflow-level name
field is called key
to emphasize the uniqueness requirement at the task-level.
name
- String
The name of your workflow must be provided. For tasks within the same workflow, each task's key
field must be a unique string.
Note: name
is mandatory for workflows & key
is mandatory for tasks.
description
- String
A short description of your workflow for you and your team to reference.
tasks
- List
Contains a list of tasks. The tasks will execute from top to bottom. The (choice)[#choice] task is an exception though, allowing you to navigate the execution to a path in the workflow.
Global Optional Fields
input
- Object
The input
field can provide global data for the workflow. The values provided in the initial
definition will be available upon every execution of the workflow. However, these values
can be overridden by execution input.
inputSchema
- Object
If one of your tasks requires input (for example, the ID of a custom object or the
description for a new ticket), you may define a schema in the inputSchema
field of the definition body. If you do so, structure your
schema based on draft 7 of the Json Schema Standard.
When executing the workflow, Sunshine Workflows will validate the execution input based on the (Json Schema Draft 7) input schema
that was provided in the workflow definition.
If an inputSchema
was provided, during execution, provide valid input
that matches the schema.
You can also get the schema using the workflow definition schema endpoint. This can be helpful to use in conjunction with validator clients like json-validator which will allow you to validate your workflows before sending requests to Sunshine Workflows.
Required Task Level Fields
key
- String
A name given to the task. Note the key must be unique in the context of the entire workflow.
type
- String
The type of task to execute. Must be one of the following:
- CREATE_SUPPORT_TICKET
- READ_SUPPORT_TICKET
- UPDATE_SUPPORT_TICKET
- CREATE_SIDE_CONVERSATION
- READ_SIDE_CONVERSATION
- LIST_SIDE_CONVERSATIONS
- UPDATE_SIDE_CONVERSATION
- REPLY_TO_SIDE_CONVERSATION
- CREATE_CUSTOM_OBJECT
- READ_CUSTOM_OBJECT
- CREATE_RELATIONSHIP_RECORD
- READ_RELATIONSHIP_RECORD
- DELETE_RELATIONSHIP_RECORD
- UPDATE_CUSTOM_OBJECT
- CREATE_SUNSHINE_PROFILE
- UPDATE_SUNSHINE_PROFILE
- READ_SUNSHINE_PROFILE
- CREATE_SUNSHINE_EVENT
- READ_SUNSHINE_EVENTS
- CHOICE
- PAUSE
- LAMBDA
input
- Object
The input
given to an individual task.
The input
field in a task object functions differently from the input
field at the top-level of the workflow definition. Think of the top-level input
field as a staging area, a place to organize and centralize the different contextual information your workflow will need to execute properly. The task-level input
field is a consumer of this staging area: it references the various key-value pairs and uses their values in the tasks' execution.
To reference a value passed as input to the workflow from a task object, use the previously mentioned string interpolation syntax "${ ... }"
.
Optional Task Level Fields
description
- String
A short description of your task for you and your team to reference.
optional
- Boolean
This boolean value can be set for any task in the workflow. If set to true, the task failure will not interrupt the workflow execution. Defaults to false.
Sunshine Workflows APIs
The Sunshine Workflows API consists of the following endpoints:
- Post New Workflow Definition
- Get Workflow Definition by ID
- Get Workflow Definitions by Account
- Update Workflow Definition
- Delete Workflow Definition
- Execute a Workflow
- Get the Workflow Schema
- Get the Status of Running Workflow
- Resume Running Workflow
- Resume Running Workflow with Input Validation
Post New Workflow Definition
POST /api/sunshine_workflows/workflows
Creates a workflow with a list of all its tasks.
Creating a workflow does not invoke it. To execute the workflow, use the Execute a Workflow endpoint.
Allowed For
- Administrators
Example request body:
{
"name": "create-ticket-test",
"description": "Refund approval for Z1",
"tasks": [
{
"key": "create_ticket",
"type": "CREATE_SUPPORT_TICKET",
"description": "Create a support ticket for the refund request.",
"input": {
"ticket": {
"subject": "New refund requested for test user",
"description": "hello world"
}
}
},
{
"type": "READ_CUSTOM_OBJECT",
"key": "read_custom_object",
"description": "Read Custom Object Based on UUID",
"input": {
"by" : "id",
"id": "${workflow.input.object_id}"
}
},
{
"key": "create_ticket_with_co",
"type": "UPDATE_SUPPORT_TICKET",
"description": "create ticket with custom object",
"input": {
"get_id_from_task": "${create_ticket.output.response.body.ticket.id}",
"ticket_id": "",
"ticket": {
"subject": "custom object ticket",
"description": "${read_custom_object.output.response.body.data}"
}
}
}
]
}
Example response
Status: 201
{
"id": "d3fb7ef8-92d3-11e9-95ac-0f81bfd8ba3e"
}
Get Workflow Definition by ID
GET /api/sunshine_workflows/workflows/{workflow-id}
Accesses the definition of the workflow specified by the ID.
Allowed For
- Agents
- Administrators
Example response
Status: 200
{
"name": "create-ticket-test",
"description": "Refund approval for Z1",
"tasks": [
{
"key": "create_ticket",
"type": "CREATE_SUPPORT_TICKET",
"description": "Create a support ticket for the refund request.",
"input": {
"ticket": {
"subject": "New refund requested for test user",
"description": "hello world"
}
}
}
]
}
Get Workflow Definitions by Account
GET /api/sunshine_workflows/workflows
Returns all workflows associated with the account.
Allowed For
- Agents
- Administrators
Example response
Status: 200
{
"workflows": [
{
"name": "create-ticket-test",
"description": "Refund approval for Z1",
"tasks": [
{
"key": "create_ticket",
"type": "CREATE_SUPPORT_TICKET",
"description": "Create a support ticket for the refund request.",
"input": {
"ticket": {
"subject": "New refund requested for test user",
"description": "hello world"
}
}
}
]
},
{
"name": "update-ticket-test",
"description": "Update ticket for Z1",
"tasks": [
{
"key": "update_ticket",
"type": "UPDATE_SUPPORT_TICKET",
"description": "Update a support ticket for the refund request.",
"input": {
"ticket_id": "${workflow.input.ticket_id}",
"ticket": {
"subject": "Updated user information",
"description": "updated description of issue"
}
}
}
],
"meta": {
"created_at": "1565808600870",
"updated_at": "1565808600870"
}
}
]
}
Update Workflow Definition
PUT /api/sunshine_workflows/workflows/{workflow-id}
Allowed For
- Administrators
Example request body
{
"name": "12345_z1_approval",
"description": "Read ticket and choose",
"tasks": [
{
"type": "READ_SUPPORT_TICKET",
"key": "read_ticket",
"description": "Read support ticket for channel.",
"input": {
"ticket_id": "${workflow.input.ticket_id}"
}
},
{
"type": "CHOICE",
"key": "check for twitter",
"condition": "if ($.channel == 'twitter') { 'twitter' } else { 'other' }",
"input": {
"channel": "${read_ticket.output.response.body.data.channel}"
},
"choices": {
"twitter": [
{
"type": "UPDATE_SUPPORT_TICKET",
"key": "update_ticket_true",
"input": {
"ticket_id": "${workflow.input.ticket_id}",
"ticket": {
"description": "twitter ticket",
"priority": "low"
}
}
}
],
"other": [
{
"type": "UPDATE_SUPPORT_TICKET",
"key": "update_ticket_false",
"input": {
"ticket_id": "${workflow.input.ticket_id}",
"ticket": {
"description": "not a twitter ticket",
"priority": "low"
}
}
}
]
}
}
]
}
Delete Workflow Definition
DELETE /api/sunshine_workflows/workflows/{workflow-id}
Allowed For
- Administrators
Example response
Status: 204
Execute a Workflow
POST /api/sunshine_workflows/workflows/{workflow-id}/execute
Executes the specified workflow. Specify any data that the workflow needs in the input
object. The data is specified in the workflow's inputSchema
, which was defined when the workflow was created.
Allowed For
- Agents
- Administrators
Example
The following inputSchema
, which was defined when the workflow was created, specifies that the workflow requires a ticket id of type string.
{
"inputSchema": {
"type": "object",
"required": [
"ticket_id"
],
"properties": {
"ticket_id": {
"type": "string"
}
}
}
}
When executing the workflow, specify its id in the API path and the required property in the request body:
{
"input": {
"ticket_id": "121"
}
}
Example response
Status: 201
{
"workflowId": "80c900da-916c-487a-9a8f-f1c6decbd0a6",
"workflowInstanceId": "258e2acd-c4c5-493d-b7ab-07291bd570f5"
}
Reserved field in the execution input
The following is a reserved field in the execution input:
workflow-metadata
Sunshine Workflows will not accept a request where the field is a property in the execution body.
Get the Workflow Schema
GET /api/sunshine_workflows/workflows/schema/definition
The schema is based on draft 7 of the JSON schema specification. Tools like this json validator can be used to verify workflows dynamically.
Allowed For
- Agents
- Administrators
Example Response
Status: 200
{
"$id": "...",
"$schema": "...",
"title": "Workflow",
"type": "object",
"required": [...],
...
}
Get the Status of Running Workflow
GET /api/sunshine_workflows/instances/{workflow-instance-id}/status
When a workflow is executed, a workflow instance ID is assigned to it. This endpoint exposes the status of the workflow's execution. If the workflow is currently executing, the endpoint additionally returns the current task's key, status, and identifier.
Allowed For
- Agents
- Administrators
Example response
Status 200
{
"status": "COMPLETED"
}
Resume Running Workflow
POST /api/sunshine_workflows/workflows/{workflow-id}/instances/{workflow-instance-id}/resume
Resumes a paused workflow. See Pause.
Allowed For
- Administrators
Example request body
POST requests only.
{
"foo": "bar"
}
Example response
Status: 201
{
"success": "true"
}
Future tasks can see the inputted request body as the output of the PAUSE task:
${pause_task.output.foo} // outputs "bar"
Resume Running Workflow with Input Validation
If an inputSchema
exists for the PAUSE task, the body of the request is validated against that schema.
In the following inputSchema
for a PAUSE task, the foo
property is required for validation.
{
"type": "pause",
"name": "pausing workflow",
"inputSchema": {
"type": "object",
"required": [
"foo"
],
"properties": {
"foo": {
"type": "string"
}
}
}
}
Example request body:
{
"foo": "bar"
}
Example responses
Status: 201
{
"success": "true"
}
Status: 422
{
"message": "There were errors validating your execution input",
"errors": [
"required key [foo] not found"
]
}
Product limits
Limit on number of workflows & tasks
Currently the maximum number of workflows for an account is 10. Additionally, the maximum number of tasks for a given workflow is 30.
Limit on the size of a workflow
The maximum size for a posted/updated workflow is 64kb.
Rate limits
Limit on number of requests per day
We limit the number of requests from an account to 1,000 per day.
Product Access Requirements
Sunshine workflows use the following APIs, which have the following requirements:
Sunshine Workflows API | Purchase Requirement |
---|---|
Support Enterprise | Support Enterprise |
Sunshine Enterprise | Sunshine Enterprise |
Side Conversations | Collaboration Add-On |
The Sunshine Workflows service will validate your usage of workflow tasks based on which products you have purchased.
Support Enterprise gives you access to the following tasks:
- CREATE_SUPPORT_TICKET
- UPDATE_SUPPORT_TICKET
- READ_SUPPORT_TICKET
Sunshine Enterprise gives you access to the following tasks:
- CREATE_CUSTOM_OBJECT
- READ_CUSTOM_OBJECT
- UPDATE_CUSTOM_OBJECT
- CREATE_RELATIONSHIP_RECORD
- READ_RELATIONSHIP_RECORD
- CREATE_SUNSHINE_PROFILE
- UPDATE_SUNSHINE_PROFILE
- READ_SUNSHINE_PROFILE
- CREATE_SUNSHINE_EVENT
- READ_SUNSHINE_EVENTS
The Collaboration Add-On gives you access to the following task:
- CREATE_SIDE_CONVERSATION
- READ_SIDE_CONVERSATION
- LIST_SIDE_CONVERSATIONS
- UPDATE_SIDE_CONVERSATION
- REPLY_TO_SIDE_CONVERSATION
By default, you have access to the following tasks:
- CHOICE
- PAUSE
- LAMBDA