Trigger API

Use the Workflow Accelerator trigger API to start cases automatically. The API supports three trigger types.

Three trigger types: public forms, email and Salesforce messages
Three trigger types: public forms, email and Salesforce messages

External systems start new cases in Workflow Accelerator in three ways:

  1. Public form triggers start cases from HTTP/JSON API requests
  2. Email triggers start cases from incoming email
  3. Salesforce triggers start cases from Salesforce events

You can use public form triggers and email triggers from external systems, by sending HTTP requests and email.

API limitation

To ensure our platform remains stable and fair for everyone, we ask developers to use industry standard techniques for limiting requests, caching results, and re-trying requests responsibly.

API rate limits 50 requests/60 seconds
Concurrency limits Read: 5, Write: 1

Public forms HTTP API

The API for submitting a Workflow Accelerator public form uses JSON data sent in an HTTP POST request to start a new case. The JSON data holds an ‘instance’ of the trigger form.

The HTTP request includes the IDs for the process to start (the sourceWorkflowId) and each of the form fields. Each form field also has a data type. To discover these field IDs and types, fetch the form definition from the trigger API:

GET /api/v1/public/start-form/1ac791d862f8a02e51300000 HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8

    {
        "form": {
            "fields": [
                {
                    "elementType": "fieldInstance",
                    "id": "p6rsah4otbmkll1j90",
                    "name": "Type of feedback",
                    "required": true,
                    "type": {
                        "name": "choice",
                        "options": [
                            {
                                "id": "0",
                                "name": "Praise"
                            },
                            {
                                "id": "1",
                                "name": "Question"
                            },
                            {
                                "id": "2",
                                "name": "Complaint"
                            }
                        ]
                    },
                    "visible": true
                },
                {
                    "elementType": "fieldInstance",
                    "id": "p6rscwnlqfrzkot2zj",
                    "name": "Feedback",
                    "required": true,
                    "type": {
                        "multiLine": true,
                        "name": "text"
                    },
                    "visible": true
                },
                {
                    "description": "When did you start using the product?",
                    "elementType": "fieldInstance",
                    "id": "pgoxccp25d71iyj680",
                    "name": "Product start date",
                    "type": {
                        "kind": "date",
                        "name": "date"
                    },
                    "visible": true
                },
                {
                    "elementType": "fieldInstance",
                    "id": "p6rsd7xwzvxg6aimww",
                    "name": "Contact email address",
                    "type": {
                        "name": "emailAddress"
                    },
                    "visible": true
                }
            ]
        },
        "submitAction": "Send Feedback"
    }

Most of these fields are unnecessary: the HTTP request you send to trigger the workflow and start a case only needs to include each field’s ID, type and value, as shown in the following literal HTTP request (most HTTP headers omitted for brevity). Note that you can omit the field type for text types.

POST /api/v1/public/cases HTTP/1.1
    Content-Type: application/json
    Host: workflow.signavio.com

    {
      "triggerInstance": {
        "data": {
          "formInstance": {
            "value": {
              "fields": [
                {
                  "id": "16rsah4otbmk000000",
                  "value": "0"
                },
                {
                  "id": "16rscwnlqfrz000000",
                  "value": "I’m so happy!"
                },
                {
                  "id": "pgoxccp25d71iyj680",
                  "type": {
                    "name": "date",
                    "kind": "date"
                  },
                  "value": "2018-01-01T00:00:00.000Z"
                },
                {
                  "id": "16rsd7xwzvxg000000",
                  "value": "bob@example.com"
                }
              ]
            }
          }
        },
        "sourceWorkflowId": "1ac791d862f8a02e51000000"
      }
    }

Note that the value for a Choice type field, is the choice type option ID, not the option name.

The HTTP response includes the newly-created case’s ID and name (most headers omitted):

HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8

    {
      "id": "1ac79962d1dfff2e36000000",
      "name": "Feedback #6 - Praise"
    }

HTML/JavaScript form example

There’s more than one way to build a custom form that uses the HTTP workflow API. For simplicity, this example uses:

  1. An HTML form that the customer will use to enter feedback
  2. A JavaScript event handler for the form’s onsubmit event
  3. A JavaScript object that serialises to the correct JSON using JSON.stringify
  4. A JavaScript Fetch API request to submit the form

The following example code aims for simplicity and no external dependencies, but does not support older web browsers and doesn’t implement a proper user experience. In practice, you would modify this to take advantage of your favourite JavaScript libraries.

A minimal plain HTML document containing the form could look like this:

<!DOCTYPE HTML>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Custom form</title>
  <script type="text/javascript" src="sendForm.js"></script>
</head>
<body>
  <form action="https://workflow.signavio.com/api/v1/public/cases">
    <p>
      <label for="type">Type of feedback</label>
      <select id="type" name="type">
        <option>Praise</option>
        <option>Question</option>
        <option>Complaint</option>
      </select>
    </p>
    <p>
      <label for="feedback">Feedback</label>
      <textarea id="feedback" name="feedback" rows="8" cols="40"></textarea>
    </p>
    <p>
      <label for="id">E-mail address</label>
      <input type="email" id="email" name="email">
    </p>
    <p><button type="submit">Send Feedback</button></p>
  </form>
</body>
</html>

The script tag refers to the following JavaScript (ES2016), which uses the fetch API to send the HTTP request:

// Sends the form data to the workflow’s public form trigger.
const sendForm = (event) => {
  event.preventDefault()
  const triggerData = {
    triggerInstance: {
      sourceWorkflowId: '1ac791d862f8a02e51000000',
      data: {
        formInstance: {
          value: {
            fields: [
              {
                "id": "16rsah4otbmk000000",
                "value": document.querySelector('#type').value
              },
              {
                "id": "16rscwnlqfrz000000",
                "value": document.querySelector('#feedback').value
              },
              {
                "id": "16rsd7xwzvxg000000",
                "value": document.querySelector('#email').value
              }
            ]
          }
        }
      }
    }
  }
  const requestOptions = {
    mode: 'no-cors',
    method: 'POST',
    body: JSON.stringify(triggerData),
    headers: new Headers({
      'Content-Type': 'application/json'
    })
  }
  var currentTime = new Date().getTime();
  fetch(document.querySelector('form').action, requestOptions)
    .then(response => console.log('Form submitted'))
    .catch(error => console.error(error))
}

// When the DOM has loaded, attach the 'sendForm' function to the form.
document.addEventListener('DOMContentLoaded', () => {
  document.querySelector("form").addEventListener('submit', sendForm)
})

Use the form’s submit button to start a new case. Check the JavaScript console for the Form submitted message, to check that there were no errors.

Email trigger API

Email triggers start cases from incoming email. When an email trigger starts a case, the email data is available to the workflow. If you generate trigger emails programmatically, you can use trigger emails to asynchronously start cases using structured data.

For example, a customer contact form might include a Product name selection, and an Enquiry text input. To use this with an email trigger, encode this form data as a JSON trigger email body:

{
  "product" : "Signavio Workflow Accelerator ",
  "enquiry" : "Is it available in French?"
}

In the workflow, add a JavaScript action to parse the trigger email. Add the built-in Trigger email variable, and text fields for the Product and Enquiry. In the script, parse the JSON to extract the values:

const enquiryForm = JSON.parse(triggerEmail.bodyText)
product = enquiryForm.product
enquiry = enquiryForm.enquiry

Note that the lack of error handling code means that invalid JSON will cause the script task to fail when executing the case, which will halt the workflow. To continue without setting the product value, wrap the code in try-catch statements.