You can start a process instance via the POST route /application/incidents/:processName. Thereby, the process name will be given as parameter processName. Another required parameter is the number of the desired start step (step). This will be transferred into the HTTP request body. Additionally, you can define a processing period for the step and the process, indicate the initiator, directly assign a certain user to the step, and transfer data for process fields and subtable fields. Further parameter can be gathered from the REST API reference.
Please note: If you would like to send the step immediately after starting the instance, the mandatory fields and activated checkboxes must be specified when sending. Alternatively, use the POST route /application/steps to obtain a workflow ID. Then pass all form fields when sending.
Data transfer for process tables
Process table data are delivered in a processtable array. Specify the name and value for a field as follows:
•The field name is defined with the key name: processtable[fields][0][name]
•The value is defined with the key value: processtable[fields][0][value]
The numbering indicates the single name/value pairs. Further table fields are than defined under processtable[fields][1]..., processtable[fields][2]... etc. in each case with its name and value.
Data transfer for subtables
The structure of subtables is a bit more complex. First the subtables to be filled has to be listed in the subtables array:
subtables[0][name] = 'ERSTE_TABELLE', subtables[1][name] = 'ZWEITE_TABELLE' etc.
The data follow the process table data pattern, though here an additional row number is specified to be able to identify the data of the same row:
•Field name: subtables[0][rows][0][fields][0][name]
•Value: subtables[0][rows][0][fields][0][value]
Further rows follow with subtables[0][rows][1]..., subtables[0][rows][2]... etc. Further subtable data are specified with subtables[1]..., subtables[2]... etc. Thereby, always the same index has to be used as in the subtable name.
Response
The response is in JSON format and contains, among others, the workflow ID and the instance number:
{
"incidents": [
{
"workflowId": "efb6df7ad40f6dbcbbd54c75881a58530000001475",
"stepId": "efb6df7ad40f6dbcbbd54c75881a58530000001771",
"processId": "efb6df7ad40f6dbcbbd54c75881a58530000001384",
"incidentnumber": 1100,
"jobfunction": "approver",
"username": "jdoe"
}
]
}
Example: Start instance with transfer of process and subtable data
guzzlehttp
// User has been authenticated already
// Define instance data
$input = [
[
'name' => 'step',
'contents' => '1',
],
[
'name' => 'summary', // Process subject
'contents' => 'Instance started via REST API',
],
[
'name' => 'step_escalation_date', // Step escalation
'contents' => '2017-10-12T11:00:00+01:00',
],
[ // Process table fields
'name' => 'processtable[fields][0][name]',
'contents' => 'INVOICENR',
],
[
'name' => 'processtable[fields][0][value]',
'contents' => 'IN02984',
],
[
'name' => 'processtable[fields][1][name]',
'contents' => 'INVOICE_DATE',
],
[
'name' => 'processtable[fields][1][value]',
'contents' => '2017-08-29T00:00:00+01:00',
],
[
'name' => 'processtable[fields][2][name]',
'contents' => 'AMOUNT',
],
[
'name' => 'processtable[fields][2][value]',
'contents' => '12000.78',
],
[
'name' => 'processtable[fields][3][name]',
'contents' => 'INVOICE_FILE',
],
[
'name' => 'processtable[fields][3][value]',
'contents' => fopen('/path/to/invoice/file.pdf', 'r'),
],
[
'name' => 'subtables[0][name]',
'contents' => 'SINVOICE_ATTACHMENTS' // Subtable name
],
[ // here starts the first row of the subtable
'name' => 'subtables[0][rows][0][fields][0][name]',
'contents' => 'ATT_IN_DATE',
],
[
'name' => 'subtables[0][rows][0][fields][0][value]',
'contents' => '2017-09-02T14:30:00+01:00',
],
[
'name' => 'subtables[0][rows][0][fields][1][name]',
'contents' => 'ATT_FILE',
],
[
'name' => 'subtables[0][rows][0][fields][1][value]',
'contents' => fopen('/path/to/attachment/note.txt', 'r'),
],
[ // here starts the second row
'name' => 'subtables[0][rows][1][fields][0][name]',
'contents' => 'ATT_IN_DATE',
],
[
'name' => 'subtables[0][rows][1][fields][0][value]',
'contents' => '2017-09-06T11:28:43+01:00',
],
[
'name' => 'subtables[0][rows][1][fields][1][name]',
'contents' => 'ATT_FILE',
],
[
'name' => 'subtables[0][rows][1][fields][1][value]',
'contents' => fopen(
'/path/to/another/attachment/confirmation.pdf', 'r'
),
],
];
try {
// Start instance with the data defined above
// (as multipart/form-data)
$response = $client->request('POST', 'application/incidents/invoice',
[
'multipart' => $input,
]
);
// Edit response
echo "Status code: " . $response->getStatusCode() . "\n";
$body = $response->getBody();
$decodedBody = json_decode($body->getContents(), true);
$incidentData = $decodedBody['incidents'][0];
echo "Workflow ID: " . $incidentData['workflowId'] . "\n";
echo "Step number: " . $incidentData['stepId'] . "\n";
echo "Process ID: " . $incidentData['processId'] . "\n";
echo "Instance number: " . $incidentData['incidentnumber'] . "\n";
echo "Job Function: " . $incidentData['jobfunction'] . "\n";
echo "User: " . $incidentData['username'] . "\n";
} catch (Exception $e) {
echo "Error during performance: " . $e->getMessage() . "\n";
}
// Finish user session
cURL
// User has been authenticated already
// Define instance data
$mainFile = new CURLFile('/path/to/invoice/file.pdf');
$fileForFirstRow = new CURLFile('/path/to/invoice/myTest1.txt');
$fileForSecondRow = new CURLFile('/path/to/invoice/myTest2.txt');
$inputData = [
'step' => '1',
'initiator' => 'REST',
'summary' => 'Vorgang gestartet über REST API', // Process subject
'step_escalation_date' => '2017-10-12T11:00:00+01:00', // Step escalation
'processtable[fields][0][name]' => 'INVOICENR',
'processtable[fields][0][value]' => 'IN02984',
'processtable[fields][1][name]' => 'INVOICE_DATE',
'processtable[fields][1][value]' => '2017-08-29T00:00:00+01:00',
'processtable[fields][2][name]' => 'AMOUNT',
'processtable[fields][2][value]' => '12000.78',
'processtable[fields][3][name]' => 'INVOICE_FILE',
'processtable[fields][3][value]' => $mainFile,
'subtables[0][name]' => 'SINVOICE_ATTACHMENTS', // Subtable name
// here starts the first row of the subtable
'subtables[0][rows][0][fields][0][name]' => 'ATT_IN_DATE',
'subtables[0][rows][0][fields][0][value]' => '2017-09-02T14:30:00+01:00',
'subtables[0][rows][0][fields][1][name]' => 'ATT_FILE',
'subtables[0][rows][0][fields][1][value]' => $fileForFirstRow,
// here starts the second row
'subtables[0][rows][1][fields][0][name]' => 'ATT_IN_DATE',
'subtables[0][rows][1][fields][0][value]' => '2017-09-06T11:28:43+01:00',
'subtables[0][rows][1][fields][1][name]' => 'ATT_FILE',
'subtables[0][rows][1][fields][1][value]' => $fileForSecondRow,
];
curl_setopt($curlHandle, CURLOPT_URL,
'http://example.org/jobrouter/api/rest/v2/application/incidents/invoice');
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POST, 1);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $inputData);
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, 'path/to/cookie/file.cookie');
$response = curl_exec($curlHandle);
$statusCode = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);
curl_close();
if ($statusCode == 200) {
$incidentData = json_decode($response, true);
echo "Incident: " . $incidentData['incidents'][0]['incidentnumber'] . "\n";
echo "Workflow ID: " . $incidentData['incidents'][0]['workflowId'] . "\n";
} else {
echo "Error during performance: Code - " . $statusCode . ", ";
echo "Response: " . var_export($response, true);
}
// Finish user session
