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:

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

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