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.

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.

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 optional fields
• Required task level fields
• Optional task level 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.

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.

A short description of your workflow for you and your team to reference.

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.

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.

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.

A name given to the task. Note the key must be unique in the context of the entire workflow.

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

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 "${ ... }".

A short description of your task for you and your team to reference.

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.

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 /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.

• 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}"
        }
      }
    }
  ]
}

Status: 201

{
  "id": "d3fb7ef8-92d3-11e9-95ac-0f81bfd8ba3e"
}

GET /api/sunshine_workflows/workflows/{workflow-id}

Accesses the definition of the workflow specified by the ID.

• Agents
• Administrators

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 /api/sunshine_workflows/workflows

Returns all workflows associated with the account.

• Agents
• Administrators

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"
       }
    }
  ]
}

PUT /api/sunshine_workflows/workflows/{workflow-id}

• Administrators

{
  "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 /api/sunshine_workflows/workflows/{workflow-id}

• Administrators

Status: 204

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.

• Agents
• Administrators

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"
  }
}

Status: 201

{
    "workflowId": "80c900da-916c-487a-9a8f-f1c6decbd0a6",
    "workflowInstanceId": "258e2acd-c4c5-493d-b7ab-07291bd570f5"
}

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 /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.

• Agents
• Administrators

Status: 200

{
    "$id": "...",
    "$schema": "...",
    "title": "Workflow",
    "type": "object",
    "required": [...],
    ...
}

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.

• Agents
• Administrators

Status 200

{
  "status": "COMPLETED"
}

POST /api/sunshine_workflows/workflows/{workflow-id}/instances/{workflow-instance-id}/resume

Resumes a paused workflow. See Pause.

• Administrators

POST requests only.

{
  "foo": "bar"
}

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"

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"
}

Status: 201

{
  "success": "true"
}

Status: 422

{
  "message": "There were errors validating your execution input",
  "errors": [
    "required key [foo] not found"
  ]
}

Currently the maximum number of workflows for an account is 10. Additionally, the maximum number of tasks for a given workflow is 30.

The maximum size for a posted/updated workflow is 64kb.

We limit the number of requests from an account to 1,000 per day.

Sunshine workflows use the following APIs, which have the following requirements:

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