Direkte API-Anbindung

Allgemeines

Die SmartProcess REST/ODATA API folgt dem OData Standard: https://www.odata.org/. OData ist ein HTTP-basiertes Protokoll.

Die verschiedenen Operationen, die Sie auf ihre Daten anwenden können, werden durch verschiedene HTTP-Methoden implementiert. Nicht alle Operationen werden von allen Daten unterstützt.

Authentifizierung

Um die API verwenden zu können, müssen Sie sich mit einem gültigen SmartProcess Benutzer über das HTTP BASIC-AUTH Verfahren anmelden. Dies ist nur für Benutzer mit einer Designer-Lizenz möglich, für die in SmartProcess ein API-Profil erstellt wurde.

Die Anmeldung erfolgt mit dem SmartProcess-Benutzernamen und dem zugeteilten API-Schlüssel.

Testen der Authentifizierung

Um die Authentifizierung zu testen, können Sie folgenden Request verwenden. Ist die Authentifizierung erfolgreich, dann wird ihr Benutzername im JSON-Format ausgegeben.

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/UserAuthTest

{"username":"admin"}

Service-Dokument und Metadaten

Eine Beschreibung der API kann über folgende URLs abgerufen werden.

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/$metadata

Objekte in OData

Content Type

Der Standard Content Type der Request-Antworten ist application/json. Die Ausgabe kann durch Anhängen von $format=<format> an die URL (bei GET Requests) geändert werden. Eine weitere Möglichkeit, das Ausgabeformat zu beeinflussen, ist das Setzen des Request Headers Accept.

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/$metadata?$format=xml

Accept: application/xml

Es werden folgende Formate unterstützt:

URL encoding

Für den Zugriff auf Daten über einen Schlüssel, der nicht-URL-konforme Zeichen enthält, wird dieser encodiert.

Aus dem uncodierten Schlüssel „Name mit Leerzeichen“ wird so zum Beispiel der Schlüssel „Name%20mit%20Leerzeichen“.

Operation Lesen (GET)

Das Auslesen funktioniert für alle Entitäten (Katalog, Anhang, Vorgang) gleich und ist abhängig von der im Bereich API-Profil erklärten Konfiguration. Die Schlüssel, um einen einzelnen Eintrag auszulesen, werden dort ebenfalls eingestellt.

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog(12)

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog(Id=12)

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Artikelkatalog(Sprache='Deutsch',Name='bestimmter Artikel')

Navigation

Zwischen Entitäten lässt sich navigieren. Die Metadaten dokumentieren, welche Navigation erlaubt ist. Die Navigation zwischen einer Vorgangsart und dem Anhang sowie einem Katalog und dem Anhang ist immer möglich. Die Navigation zwischen einem Vorgang und einem Subvorgang muss erst in der Konfiguration eingeschaltet werden.

Beispiel einer Navigation

Die folgende URL gibt alle Subvorgänge aus, die zum Hauptvorgang mit der ID 12345 gehören:

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Hauptvorgang(12345)/Subvorgang

Query-Operationen

Folgende Query-Operationen werden unterstützt:

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Vorgang?$orderby=Zuständig asc,Erstelldatum desc

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Vorgang?$select=Vorgangsnummer,Änderungsdatum,Zuständig

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow?$select=Bezeichnung,Gesamtsumme_in_EUR&$count=true

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‘)

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Hauptvorgang(12345)?$expand=Untervorgang,Anhang

GET https://SUBDOMAIN.smartprocess.com/CwaData.svc/Hauptvorgang(12345)?$expand=Untervorgang($filter=Priorität eq 'hoch';$expand=Aktivität($filter=Status eq 'Erledigt'),Anhang

Paging

Pro Anfrage kann nur eine begrenzte Anzahl an Daten ausgelesen werden, dabei liegt das Höchstlimit bei 500 Elementen auf einer Ebene.

Bei einer Beispielabfrage von

https://SUBDOMAIN.smartprocess.com/CwaData.svc/Hauptvorgang?$expand=Subvorgang 

heißt das, es können maximal 500 Hauptvorgänge mit jeweils (!) maximal 500 Subvorgängen ausgelesen werden.

Die Seitengröße lässt sich steuern, indem man den Prefer-Header anpasst. Im Beispiel für eine Seitengröße von 3.

Prefer: odata.maxpagesize=3

Erreicht eine Anfrage das Seitenlimit, enthält sie außerdem die „@odata.nextLink“-Variable, die den Link zur nächsten Seite enthält.

Die $expand-, $format- und $select-Optionen werden übernommen, können aber noch angepasst werden. Außerdem wird ein $skiptoken-Parameter übergeben, anhand dessen die Zuordnung zur nächsten Seite ermöglicht wird. Dieser Parameter darf nicht verändert werden. Die gewünschte Seitenzahl kann ebenfalls bei jeder Anfrage geändert werden. Andere Query-Optionen wie $filter werden nicht berücksichtigt, weil sie bereits in der ersten Anfrage angewandt wurden.

Operation Erstellen (POST)

Das Erstellen von Entitäten ist abhängig von der im Bereich API-Profil erklärten Konfiguration. War das Erstellen erfolgreich, liefert der Server den Status 201 und die neu erstellte Entität zurück.

Eine beispielhafte Abfrage, um einen Vorgang mit einer Feldgruppe und einem Kontakt zu erstellen, wäre:

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

Es lassen sich direkt verknüpfte Entitäten (z.B. Untervorgänge, Anhänge) erstellen.

Eine beispielhafte Abfrage, um einen Vorgang mit einem Sub-Vorgang vom Typ "Maßnahme" zu erstellen, wäre:

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

Eine neue Entität kann mit bestehende Entitäten über @odata.bind verknüpft werden (z.B. wenn ein Sub-Vorgang oder eine Aktivität zu einem Hauptvorgang hinzugefügt werden soll).

Eine beispielhafte Abfrage, um einen neuen Sub-Vorgang vom Typ "Maßnahme" zu einem bestehenden Vorgang hinzuzufügen, wäre:

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

Operation Verändern (PATCH / PUT)

Das Verändern ist dem Erstellen fast identisch, mit wenigen Unterschieden:

- Die URL muss einen Schlüssel für das Objekt enthalten, das geändert werden soll.

- Einige Felder lassen sich nach Erstellung nicht mehr verändern. Im Fall eines Änderungsversuchs wird ein Fehler ausgegeben.

Wenn ein Vorgang mit Feldgruppen geändert wird, gilt folgendes Vorgehen:

PATCH

- Feldgruppen, die mit einem Schlüssel eines Objekts im Request-Body übereinstimmen, werden überschrieben.

- Feldgruppen, die mit keinem Schlüssel übereinstimmen, werden beibehalten.

- Objekte im Request-Body, die mit keiner existierenden Feldgruppe übereinstimmen, werden neu angelegt.

- Um eine Feldgruppe zu löschen, gibt es das künstliche Feld „Gelöscht“. Indem dieses Feld (in der Konfiguration aktiviert und) auf true gesetzt wird, signalisiert man dem System, dass die Gruppe gelöscht werden soll.

- Wird im Request-Body „Feldgruppen“: null angegeben, werden alle Feldgruppen gelöscht.

PUT

Bei PUT wird jede nicht angegebene Feldgruppe gelöscht (das gilt auch, wenn keine Feldgruppen angegeben werden).

War die Änderung erfolgreich, wird der Statuscode 204 ohne Inhalt zurückgegeben.

Eine beispielhafte Abfrage, um einen bestehenden Vorgang zu ändern und einen Feldgruppeneintrag zu löschen, wäre:

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

Operation Löschen (DELETE)

Für das Löschen wird ein eindeutiger Schlüssel des Objekts benötigt.

War das Löschen erfolgreich, gibt der Server den Statuscode 204 zurück.

Eine beispielhafte Abfrage, um einen bestehenden Vorgang mit der Vorgangsnummer 40413013 zu löschen, wäre:

DELETE https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow('40413013')
Authorization: Basic {{apiUsername}} {{apiPassword}}

 HTTP Statuscodes

Der Status einer API-Abfrage wird in HTTP Codes zurückgegeben, die zur Untersuchung möglicher Fehler beitragen können. Mögliche Statuscodes und Beispiele sind:

https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow(123456)

https://SUBDOMAIN.smartprocess.com/CwaData.svc/API_Workflow('123456')

Zugriffsbegrenzung

Damit SmartProcess durch API-Aufrufe nicht zu sehr ausgelastet wird, werden API-Zugriffe gemessen und limitiert. Unter normalen Einstellungen sind erlaubt:

- Alle 2 Minuten 50 Aufrufe zu maximal 60 Sekunden Bearbeitungsdauer.

- Alle 60 Minuten 1000 Aufrufe zu maximal 900 Sekunden Bearbeitungsdauer.

- Pro GET-Aufruf maximal 500 zurückgegebene Entitäten (mit jeweils maximal 500 Sub-Entitäten).

Einschränkungen

Aus den Sachzusammenhängen und der Komplexität der Anwendung ergeben sich einige Einschränkungen in der Benutzung der REST-API:

Allgemein

Es werden nur Namen erlaubt, die kein ‘-‘ oder ‘.‘ enthalten und dem NCName-Schema entsprechen.

Vorgänge

Sichtbarkeitsbeschränkungen und die Validierung aus den Formularfeldern werden wie beim Import ignoriert.

Die Optionen „(…) nur aus Kontaktverwaltung (…)“ und „Kontakte automatisch (…) übernehmen“ aus Kontaktfeldern werden wie beim Import ignoriert.

Zyklische Vorgänge werden nicht unterstützt. Wenn also ein Vorgangsbaum wie folgt aussieht: Hauptvorgang -> Subvorgang_Eins -> Subvorgang_Zwei -> Hauptvorgang, dann kann die REST-API nur bis Subvorgang_Zwei arbeiten.

Anhangtypbeschränkung und Anhangmindestzahl werden ignoriert.

Zwingende Eingabe wird ignoriert, damit per REST unvollständige Vorgänge manuell vervollständigt werden können.

„Eindeutig für Import“ gilt nicht für die REST-API.

Bei der Datenquelle „Organisationseinheit, Rolle und Benutzer“ wird die Validität der Eingabe nicht geprüft.

Bis auf die Kennzahlerfassung sind alle besonderen Workflows von der API ausgeschlossen.

Anhänge

Anhänge können nur angelegt, nicht aber geändert werden.

Anhänge können nur im Kontext anderer Objekte verwendet werden. Es können z.B. nicht alle Anhänge ausgegeben werden, wohl aber alle Anhänge, die zu Vorgang x oder Katalogeintrag y gehören.

Kataloge

Sprache und Kategorie sind nach Erstellen nicht per API änderbar.

Zwingende Eingabe wird analog zum Vorgang ignoriert.

Nur Katalog-Typ Standard wird unterstützt (SAP, Benutzerverwaltung, etc. nicht).