Table of Contents
Direct API connection
Note: To be able to use the SmartProcess API, it is necessary to configure the API profile in the settings.. As an example for all API calls, the fictitious URL https://SUBDOMAIN.smartprocess.com /Cw…
To be able to use the SmartProcess API, it is necessary to configure the API profile in the settings.
General
The SmartProcess REST/ODATA API follows the OData standard: https://www.odata.org/. OData is an HTTP-based protocol.
The different operations you can apply to your data are implemented by different HTTP methods. Not all operations are supported by all data.
Operation | HTTP Method |
Read | GET |
Create | POST |
Change | PATCH / PUT |
Delete | DELETE |
Authentication
To use the API, you must log in with a valid SmartProcess user using the HTTP BASIC-AUTH method. This is only possible for users with a Designer license for whom an API profile has been created in SmartProcess.
The login is done with the SmartProcess username and the assigned API key.
Testing the authentication
To test authentication, you can use the following request. If the authentication is successful, then your username will be output in JSON format.
Request | GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/UserAuthTest |
Response | {"username":"admin"} |
Service Document and Metadata
A description of the API can be found at the following URLs.
GET https://SUBDOMAIN.smartprocess.com/CwaData.svc
GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/$metadata
Objects in OData
Entities (independent objects) | All operations can be carried out on them, and they in turn consist of complex and primitive objects. |
Complex properties (not independent objects) | They contain several primitive properties. |
Primitive properties | e.g. the ID or the creation date. They are of one of the basic data types (character string, truth value, integer, date, etc.). |
Content Type
The default content type of the server responses is application/json. The output can be changed by appending $format=<format> to the URL (for GET requests). Another way to influence the output format is to set the Accept request header.
Example (URL) | GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/$metadata?$format=xml |
Example (Request Header) | Accept: application/xml |
The following formats are supported:
Format | URL | Accept Header |
JSON | $format=json | application/json |
XML | $format=xml | application/xml |
Atom | $format=atom | application/atom |
URL encoding
To access data using a key that contains non-URL characters, the key must be encoded.
For example, the unencoded key "name with space" becomes the key "name%20with%20space".
- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
- https://www.url-encode-decode.com/
Read operation (GET)
Reading works the same for all entities (catalogue, attachment, process) and depends on the configuration explained in the API profile section. The keys for reading out an individual entry are also set there.
For more information, see Paging.
Retrieve all entries of an entity | GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog |
Retrieve individual entry (single key) | GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog(12) alternatively GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog(Id=12) |
Retrieve individual entry (multiple keys) | Multiple keys are separated by commas GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog(Sprache='Deutsch',Name='bestimmter Artikel') |
Navigation
You can navigate between entities. The metadata documents which navigation is permitted. Navigation between a process and the attachment and between a catalogue and the attachment is always possible. Navigation between an operation and a sub-operation must first be switched on in the configuration.
Example of navigation
The following URL displays all sub-tasks that belong to the main task with the ID 12345:
GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Hauptvorgang(12345)/Subvorgang
Query operations
The following query operations are supported:
$orderby | This option enables sorting. If it is not specified, the keys are used for sorting. If no direction is specified, sorting is in ascending order (asc). Some fields cannot be used for sorting. A corresponding request results in an error output. - The data of an attachment - The deleted field of a field group - The subject of a process - The status of a process - The priority of a process - Text fields with selection Example: GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Vorgang?$orderby=Zuständig asc,Erstelldatum desc | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$select | Select determines which fields are to be output so that unnecessary data does not have to be transferred. Example: GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Vorgang?$select=Vorgangsnummer,Änderungsdatum,Zuständig | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$count | This option can be set to true so that the number of entities found is output together with the entities. The default value is false. Format: $count=[true|false] Example: GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow?$select=Bezeichnung,Gesamtsumme_in_EUR&$count=true | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$filter | The filter option offers many possibilities to limit the search to the desired values. Some fields cannot be used for filter functions. A corresponding request results in an error output. Example: GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Vorgang?$filter=Zuständig eq 'Jochen' and (Änderungsdatum ge 2024-09-15T00:00:00Z or Priorität eq 'Hoch') This query searches for all processes for which the user Jochen is responsible and which have been created since 15 September or have a high priority. Logical operators that are supported:
Arithmetic operations that are supported:
String functions that are supported:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
$expand | The Expand operator specifies entities that are also to be output and is available for all entities that can be navigated to. Example: GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/MainCase(12345)?$expand=SubCase,Attachment Expand can be combined with the other operators so that, for example, the output sub-processes can be filtered. The inner operators are specified in brackets and separated by semicolons. Example: GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/MainCase(12345)?$expand=SubCase($filter=Priority eq 'high';$expand=Activity($filter=Status eq 'Done'),Attachment This query outputs the operation of the type "Main operation" with the ID 12345. In addition, all tasks of the type "Sub-task" that have a high priority are output. Of the sub-tasks, all tasks of the type "Activity" that have been completed are also delivered. Finally, all attachments are returned. |
Paging
Only a limited amount of data can be read out per request, with a maximum limit of 500 elements on one level.
With an example query of
https://SUBDOMAIN.smartprocess.com/CwaData.svc/Hauptvorgang?$expand=Subvorgang
this means that a maximum of 500 main processes with a maximum of 500 sub-processes each (!) can be read out.
The page size can be controlled by adjusting the Prefer header. In this example, a page size of 3 is used.
Prefer: odata.maxpagesize=3
If a request reaches the page limit, it also contains the "@odata.nextLink" variable, which contains the link to the next page.
The $expand, $format and $select options are adopted, but can still be customised. A $skiptoken parameter is also transferred, which is used to enable the assignment to the next page. This parameter must not be changed. The desired number of pages can also be changed for each request. Other query options such as $filter are not taken into account because they were already applied in the first query.
The IDs of the objects to be returned are calculated during the first query. If objects are created or changed between the first and a subsequent query, this no longer affects the selection of objects to be returned.
The data of the objects is in turn read out on a query-by-query basis.
Create operation (POST)
The creation of entities depends on the configuration explained in the API profile section. If the creation was successful, the server returns the status 201 and the newly created entity.
An example query to create a process with a field group and a contact would be:
POST https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow
Content-Type: application/json
Authorization: Basic {{apiUsername}} {{apiPassword}}
{
"Kontakt_Nr": "C1030",
"Kontaktperson": "Thomas Obermann",
"E_Mail": "email-adresse@cwa.de",
"Firma": "TTWW GmbH",
"Artikel": [
{
"Gelöscht": false,
"Anzahl_in_Stk": 3.0,
"Artikel_Bezeichnung": "Monitor",
"Artikel_Nr": "2001",
"Einzelpreis_in_EUR": 429.99
},
{
"Gelöscht": false,
"Anzahl_in_Stk": 3.0,
"Artikel_Bezeichnung": "Keyboard",
"Artikel_Nr": "0817",
"Einzelpreis_in_EUR": 8.15
}
],
"Anforderung___Norm": "ISO 9001:2015",
"Abschnitt": "1",
"Bezeichnung_Anforderung": "Anwendungsbereich",
"Bezeichnung": "Dies ist ein Test",
"Neuanlage_": "Ja",
"Bereich": "Option A",
"Grund": [
"Zwei",
"Drei"
],
"Verantwortlich": "Mustermann, Max",
"Teilbereich": "Geschäftsführung",
"Begründung": "Ja",
"Anzahl_Teile": 5.0,
"Datum_Eingang": "2024-12-19",
"Datum_und_Uhrzeit_Deadline": "2024-12-19T09:00:00+01:00",
"Kommentar": "Dies ist ein Kommentar",
"Ausführlicher_Kommentar": "<p style=\"font-family: Arial; font-size: 10pt;\"><span style=\"font-size: 12pt;\"><strong>Dies ist ein ausführlicher, formatierter Kommentar</strong></span></p>"
}
Deep insert
Directly linked entities (e.g. sub-tasks, attachments) can be created.
An example query to create a task with a sub-task of the type "Task" would be:
POST https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow
Content-Type: application/json
Authorization: Basic {{apiUsername}} {{apiPassword}}
{
"Kontakt_Nr": "C1030",
"Kontaktperson": "Thomas Obermann",
"E_Mail": "demo-e-mail@cwa.de",
...,
"Maßnahme":[
{
"Auslöser": "Sonstiges",
"Feststelldatum": "2024-12-19",
"Geplante_Maßnahme": "<p style=\"font-family: Arial; font-size: 10pt;\">Test der Maßnahme</p>",
"Termin": "2025-12-31",
"Titel_der_Maßnahme": "Test",
"Verantwortlich": "Mustermann, Max",
"Weitere_Maßnahme_erstellen_": "Nein"
}
]
}
Binding
A new entity can be linked to existing entities via @odata.bind (e.g. if a sub-process or an activity is to be added to a main process).
An example query to add a new sub-task of the type "task" to an existing task would be:
POST https://SUBDOMAIN.smartprocess.com/CwaData.svc/Maßnahme
Content-Type: application/json
Authorization: Basic {{apiUsername}} {{apiPassword}}
{
"API_Workflow@odata.bind": "API_Workflow('40413014')",
"Auslöser": "Sonstiges",
"Feststelldatum": "2024-12-19",
"Geplante_Maßnahme": "<p style=\"font-family: Arial; font-size: 10pt;\">Test der Maßnahme</p>",
"Termin": "2024-12-31",
"Titel_der_Maßnahme": "Test",
"Verantwortlich": "Mustermann, Max",
"Weitere_Maßnahme_erstellen_": "Nein"
}
Update operation (PATCH / PUT)
Modifying is almost identical to creating, with a few differences:
- The URL must contain a key for the object that is to be changed.
- Some fields can no longer be changed once they have been created. If an attempt is made to change them, an error is displayed.
If an operation with field groups is changed, the following procedure applies:
PATCH
- Field groups that match a key of an object in the request body are overwritten.
- Field groups that do not match any key are unchanged.
- Objects in the request body that do not match any existing field group are newly created.
- To delete a field group, there is the artificial field "Deleted". By setting this field (activated in the configuration) to true, you signal to the system that the group should be deleted.
- If "Field groups": null is specified in the request body, all field groups are deleted.
PUT
With PUT, any field group not specified is deleted (this also applies if no field groups are specified).
If the change was successful, status code 204 is returned without content.
PATCH means that unspecified fields are ignored.
PUT means that unspecified fields are interpreted as null and thus emptied.
An example query to change an existing process and delete a field group entry would be:
PATCH https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow('40413104')
Content-Type: application/json
Authorization: Basic {{apiUsername}} {{apiPassword}}
{
"Kontakt_Nr": "C1033",
"Kontaktperson": "Christiane Feurig",
"E_Mail": "demo-e-mail@cwa.de",
"Firma": "Bremer Gewürzhandel",
"Artikel": [
{
"Gelöscht": true,
"Anzahl_in_Stk": 5.0,
"Artikel_Bezeichnung": "Monitor",
"Artikel_Nr": "2001",
"Einzelpreis_in_EUR": 429.99
},
{
"Gelöscht": false,
"Anzahl_in_Stk": 3.0,
"Artikel_Bezeichnung": "Keyboard",
"Artikel_Nr": "0817",
"Einzelpreis_in_EUR": 8.15
},
{
"Gelöscht": false,
"Anzahl_in_Stk": 5.0,
"Artikel_Bezeichnung": "PC",
"Artikel_Nr": "2002",
"Einzelpreis_in_EUR": 5429.99
}
],
"Anforderung___Norm": "ISO 9001:2015",
"Abschnitt": "2",
"Bezeichnung_Anforderung": "Normative Verweise",
"Bezeichnung": "Bezeichnung geändert",
"Neuanlage_": "Nein",
"Bereich": "Option D",
"Grund": [
"Eins",
"Zwei"
],
"Verantwortlich": "Perso, Petra",
"Teilbereich": "Geschäftsführung / QM",
"Begründung": "Nein",
"Anzahl_Teile": 99.0,
"Datum_Eingang": "2024-12-20",
"Datum_und_Uhrzeit_Deadline": "2024-12-20T09:00:00+01:00",
"Kommentar": "GEÄNDERT: Dies ist ein Kommentar",
"Ausführlicher_Kommentar": "<p style=\"font-family: Arial; font-size: 10pt;\"><span style=\"font-size: 12pt;\"><strong>GEÄNDERT:Dies ist ein ausführlicher, formatierter Kommentar</strong></span></p>"
}Delete operation (DELETE)
A unique key for the object is required for deletion.
If the deletion was successful, the server returns the status code 204.
An example query to delete an existing case no. 40413013 would be:
DELETE https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow('40413013')
Authorization: Basic {{apiUsername}} {{apiPassword}}HTTP status codes
The status of an API request is returned in HTTP codes that can help investigate possible errors. Possible status codes and examples are:
HTTP status code | Example |
200 -> OK | A READ operation has found and returned an entry. |
201 -> Created | A CREATE operation was successfully performed. |
204 -> No content | An UPDATE or DELETE operation was successfully executed - No content is output as the response, because on the one hand the operation did not cause an error and on the other hand it does not return any content. |
400 -> Bad request | The user did not consider the requested syntax when making the API call. Example: https://SUBDOMAIN.smartprocess.com/CwaData.svc/CatalogueDefinitions(abc) The user tries to call the definition of a specific catalogue. However, the ID of the catalogue is required for this, which is why only numbers are expected in brackets and the letter string "abc" is an incorrect entry. |
401 -> Unauthorized | The user executes an arbitrary API call, but has not authenticated himself with his SmartProcess user + API key before. |
403 -> Forbidden | The user has authorized himself but tries to execute an operation which he is not allowed to execute according to his rights (e.g. a user without Designer license or API Key) |
404 -> Not found | The user's API call meets all syntax requirements, but no corresponding entry is found. Example: https://SUBDOMAIN.smartprocess.com/CwaData.svc/CatalogueDefinitions(123456789) This error code is returned if no process of the type API_Workflow with the process number 123456 exists (or the API user does not have read authorisation for it). |
500 -> Internal server error | An internal server error has occurred. |
501 -> Not implemented | The user is trying to use an API operation that is currently not implemented. |
Access limitation
To ensure that SmartProcess is not overloaded by API calls, API accesses are measured and limited. Under normal settings, the following are permitted:
- 50 calls every 2 minutes for a maximum processing time of 60 seconds.
- 1000 calls every 60 minutes for a maximum processing time of 900 seconds.
- A maximum of 500 returned entities per GET call (with a maximum of 500 sub-entities each).
If you have several profiles, these are not affected by each other.
Restrictions
The technical context and the complexity of the application result in some restrictions in the use of the REST API:
General
Only names that do not contain a '-' or '.' and correspond to the NCName scheme are permitted.
Cases
Visibility restrictions and validation from the form fields are ignored, as with the import.
The options "(...) Choose contact from database (...)" and "Put contacts filled directly in the form of the database (...)" from contact fields are ignored, as with the import.
Cyclical processes are not supported. So if a process tree looks like this: Main_process -> Subprocess_One -> Subprocess_Two -> Main_process, then the REST API can only work up to Subprocess_Two.
Attachment type restriction and minimum number of attachments are ignored.
Mandatory input is ignored so that incomplete operations can be completed manually via REST.
"Unique for import" does not apply to the REST API.
The validity of the input is not checked for the "Organisational unit, role and user" data source.
With the exception of KPI entry, all special workflows are excluded from the API.
Attachments
Attachments can only be created, not changed.
Attachments can only be used in the context of other objects. For example, you cannot retrieve attachments directly, only attachments related to process x or catalogue entry y.
Catalogues
Language and category cannot be changed via API after creation.
Mandatory input is ignored analogue to the process.
Only catalogue type Standard is supported (SAP, user administration etc.).
How did we do?
Introduction SmartProcess API
Connection via Zapier
