Trigger API
Use the SAP Signavio Process Governance trigger API to start cases automatically. The API supports three trigger types.
External systems start new cases in SAP Signavio Process Governance in three ways:
- Public form triggers start cases from HTTP/JSON API requests
- Email triggers start cases from incoming email
- 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 SAP Signavio Process Governance 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/jsonHTTP/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:
- An HTML form that the customer will use to enter feedback
- A JavaScript event handler for the form’s onsubmit event
- A JavaScript object that serialises to the correct JSON using JSON.stringify
- 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 favorite 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" : "SAP Signavio Process Governance ",
"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.enquiryNote 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.
Ist diese Seite hilfreich?
- Ja
- Nein
Möchten Sie uns zu dieser Seite Feedback geben? Senden Sie uns eine E-Mail
Um Produktsupport zu erhalten, wenden Sie sich an unsere Serviceexperten auf dem SAP ONE Support Launchpad.