Dokumentation

API
Application Programming Interface

(C) 2022 by CAQ AG Factory Systems

Hinweis API

API

(C) 2022 by CAQ AG Factory Systems

Die Informationen in dieser Dokumentation können ohne Ankündigung geändert werden und stellen für die CAQ AG
Factory Systems keinerlei Verpflichtung, sondern lediglich eine Momentaufnahme zum Zeitpunkt der Erstellung dar.
Die in dieser Dokumentation beschriebene
Software und diese Dokumentation unterliegen ausschließlich den AGB und der Lizenzvereinbarung der CAQ AG
Factory Systems.

Die in dieser Dokumentation dargestellten Abbildungen und beschriebenen Anwendungen beziehen sich auf eine
vollumfängliche, mit allen Optionen freigeschaltete CAQ-Software. Sollten beschriebene Anwendungen in der
Software nicht verfügbar sein, so sind diese unter Umständen lizenzpflichtig und müssen gesondert angefordert
werden.

Die Software und das Handbuch dürfen nur in Übereinstimmung mit den Lizenzbedingungen und AGB der CAQ AG
Factory Systems kopiert oder genutzt werden.

Die vollständigen AGB und Lizenzbedingungen finden Sie unter https://www.caq.de/de/AGB.

Gedruckt: November 2022

CAQ AG Factory Systems

In der Wester 5
D-55494 Rheinböllen
Internet: www.CAQ.de

INFO-Line
E-Mail: Info@CAQ.de
Telefon: +49 6764 90 200 0

Service-Line
E-Mail: Support@CAQ.de
Telefon: +49 6764 90 200 160

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen.
2
 API Inhaltsverzeichnis

Inhaltsverzeichnis

1. Was ist OpenAPI? 4

2. OpenAPI in CAQ.Net 4
2.1 Authentifizierung 6
2.2 Swagger-Definition 7
2.3 Filtermöglichkeiten 7
2.4 Besonderheiten der Prüfdatenerfassung 8
2.5 Anwendungsbeispiel 9

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen, die im Anhang zu finden sind.
3
Was ist OpenAPI? API

1. Was ist OpenAPI?

Mit API (Application Programming Interface) steht Ihnen ein modernes Werkzeug zur Echtzeit-Kommunikation mit
Drittanwendungen zur Verfügung. API bietet die Möglichkeit, CAQ.Net® in beliebige Elemente externer
Systemlandschaften einzubinden und nahezu jede Funktion von CAQ.Net® innerhalb des MES (Manufacturing
Execution System), ERP (Enterprise-Resource-Planning) oder einer individuellen Smartphone-App abzubilden.
Notwendige Frontends oder Browser-Apps können dank offener Dokumentation der API komplett selbstständig
entwickelt werden.
API ist:
Ø offen,
Ø standardisiert,
Ø plattformunabhängig und
Ø individuell einsetzbar.
Die OpenAPI-Spezifikation (OAS) definiert eine standardisierte, programmiersprachenunabhängige
Schnittstellenbeschreibung für REST-APIs, mit der sowohl Menschen als auch Computer die Funktionen eines
Dienstes erkennen und verstehen können, ohne Zugriff auf Quellcode, zusätzliche Dokumentation oder
Überprüfung des Netzwerkverkehrs zu benötigen.
Bei korrekter Definition über OpenAPI kann ein Anwender den Remote-Service mit einem Minimum an
Implementierungslogik verstehen und mit ihm interagieren. Die OpenAPI-Spezifikation beseitigt das Rätselraten beim
Aufrufen eines Dienstes.
Eine OpenAPI-Definition kann dann von Dokumentationsgenerierungstools zum Anzeigen der API oder von
Codegenerierungstools zum Generieren von Servern und Clients in verschiedenen Programmiersprachen oder von
Testtools und vielen anderen Anwendungsfällen verwendet werden.

2. OpenAPI in CAQ.Net
Mit der Option Connect.Net – OpenAPI Interface (GFL-Lizenz erforderlich) können Daten aus CAQ.Net® in Echtzeit
abgefragt und verändert werden. Die Schnittstelle entspricht der OpenAPI-Spezifikation und kann daher von einer
Vielzahl an Drittanwendungen direkt angesprochen werden.
Ø Die CAQ.Net®-API bietet vordefinierte Funktionen ("Operations") an, die von externen Software-Systemen
aufgerufen werden können. Der Aufruf einer Funktion kann prinzipiell verschiedene Folgen haben:
· Abruf von Daten aus dem CAQ.Net®-System
· Neue Daten im CAQ.Net®-System anlegen
· Aktualisierung von Daten im CAQ.Net®-System
· Löschen von Daten im CAQ.Net®-System
· Auslösen verschiedener Aktionen/Funktionen im CAQ.Net®-System
Ø Je nach Definition einer Funktion, ist für den Aufruf die Angabe von einem oder mehreren Parametern („Args“)
verpflichtend, damit sie funktioniert. Die Verwendung weiterer, optionaler Parameter zur weiteren Spezfikation der
Funktion ist ebenfalls möglich. Außerdem ist zu jeder Funktion spezifiziert, welche Informationen in welcher Form
als Antwort („response“) zurückgegeben werden.

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen.
4
 API OpenAPI in CAQ.Net

Beispiel eines API-Calls:

Anfrage an API - Menschenlesbar Anfrage an API - Maschinenlesbar

Gib mir eine Liste von Prüfaufträgen gefiltert nach dem Data:
Prüfplatz "Fertigung". Ich bin übrigens der Klaus.
{
Call: Inspections/GetOrderList
"LocationFilter": {
"Value" : "Fertigung"
},
"AuthID": "0db8*********"
}

Antwort von API - Menschenlesbar Antwort von API - Maschinenlesbar

Es existiert ein Auftrag mit der Nummer "CAQ-Test 01" [

und dem Artikel "Testartikel" aus der Artikelgruppe "800-
{
Testdaten".
"ID": 4,
"Number": "CAQ-Test 01",
"ExternalNumber": "",
"Tag": "",
"Article": {
"Name": "Testartikel",
"Group": {
"Name": "800-Testdaten",
"ID": 6
},
"Number": "10",
"Index": "1",
"ID": 7
....
]

Ø Die verfügbaren Funktionen und ihr Aufbau werden als JSON (JavaScript Object Notation) zur Verfügung gestellt,
das der OpenAPI-Spezifikation entspricht. JSON ist ein kompaktes Datenformat in einer einfach lesbaren Textform.

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen, die im Anhang zu finden sind.
5
OpenAPI in CAQ.Net API

2.1 Authentifizierung
Der Zugriff auf die CAQ AG OpenAPI muss immer authentifiziert sein. Zur Authentifizierung an der OpenAPI wird der
Call "System/Login" verwendet.
Ø Bei einer gültigen Anmeldung gibt dieser Call eine AuthID zurück, welche an alle weiteren OpenAPI-Funktionen
übergeben werden muss, um so den Anwender eindeutig zu identifizieren.
· Die AuthID ist nach einem OpenAPI-Aufruf maximal zehn Minuten gültig, wird dann verworfen und ist damit
ungültig. Wird innerhalb dieser zehn Minuten einer weiterer Call ausgeführt, beginnt der Zeitraum erneut.
· Die verwendete Programmlizenz wird ebenfalls für diesen Zeitraum festgehalten.
Ø Um zu verhindern, dass die Authentifizierung ungültig wird, kann der optionale Parameter "CreateStaticID" mit
"true" übergeben werden. Das System merkt sich nun die AuthID über einen Zeitraum von sechs Monaten. Der
Zeitraum wird bei einem Zugriff nach fünf Monaten automatisch um weitere sechs Monate verlängert. Solch eine
AuthID kann problemlos für externe Schnittstellen eingesetzt werden, die dauerhaft mit dem CAQ AG System
verbunden sind.
· Ein weiterer Login ist nicht notwendig, es kann direkt auf eine beliebige Funktion des Systems zugegriffen
werden.
· Das Erkennungsmerkmal einer statischen AuthID ist das vorangestellte "XB".

Abbildung: OpenAPI - statische AuthID

Ø Zur Gültigkeitsüberprüfung einer statischen oder nicht statischen AuthID, wird der Call "System/IsLoggedIn"
verwendet. Hiermit wird die übergebene AuthID geprüft, eine Fehlermeldung wird ausgegeben, wenn die AuthID
ungültig ist.
Ø Der Call "System/IsLoggedIn" kann auch zum Beschleunigen des Zugriffes auf die OpenAPI verwendet werden. Die
Funktionen der OpenAPI speichern aus Performancegründen eine AuthID maximal zehn Minuten im
Arbeitsspeicher. Wird nun bei einer statischen AuthID alle 15 Minuten eine Abfrage ausgeführt, muss bei jedem
Zugriff zuerst die Datenbankverbindung, der Benutzer, die Rechte des Benutzers etc. geladen werden. Es kann also
sinnvoll sein, den Aufruf "System/IsLoggedIn" alle fünf Minuten aufzurufen, um die AuthID weiterhin im
Arbeitsspeicher zu erhalten.
Ø Um für ein externes System eine statische AuthID zu erstellen, kann die Webseite {WebCAQ.Net-
Pfad}/api/default.html verwendet werden.

Abbildung: CAQ AG - OpenAPI - Login

Ø Nach erfolgreicher Authentifizierung sind an dieser Stelle einige Beispiele zu finden.

Abbildung: CAQ AG - OpenAPI - Beispiele/Available pages

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen.
6
 API OpenAPI in CAQ.Net

2.2 Swagger-Definition
Die OpenAPI Swagger-Definition kann unter der URL {WebCAQ.Net-Pfad}/api/v1/doc/index eingesehen werden.
Ø Dort sind alle OpenAPI-Calls passend zu Ihrem Software-Release aufgelistet.
Ø Um die Swagger-Definitionsdatei herunterzuladen, kann die URL {WebCAQ.Net-Pfad}/swagger/docs/v1 verwendet
werden.

Abbildung: Swagger-Dokumentation

2.3 Filtermöglichkeiten
Es können verschiedene Filtermöglichkeiten angewendet werden.
Ø Eine Vielzahl von OpenAPI-Funktionen unterstützen das Filtern nach frei definierbaren Attributen.
· Um eine Liste von Entitäten abrufen zu können, die frei definierbare Attribute zur Verfügung stellen, wird der Call
"System/GetAvailableAttributesEntities" verwendet.
· Die möglichen Attribute für eine dieser Entitäten werden per Call "System/GetAvailableAttributes" abgerufen.
· Diese Attribute können den einzelnen Aufrufen, welche diese Filtermöglichkeit besitzen (z.B.
"Gauges/GetGaugeList"), übergeben werden.
Ø Viele Funktionen (z.B. "Inspections/CreateSample") erlauben zum Filtern sowohl die Angabe einer ID sowie eines
Namens, einer Bezeichnung oder Datensatznummer. Dabei kann entweder die ID des Datensatzes oder der Name,
die Nummer oder die Bezeichnung übergeben werden. Jedoch sollte niemals beides Übergeben werden, da
dadurch eine eindeutige Identifizierung eines Datensatzes unter Umständen nicht mehr möglich ist. Grundsätzlich
ist es besser und performanter die ID zu übergeben, sobald diese bekannt ist.
Ø Mehrere Aufrufe für Listen von Datensätzen (z.B. "Inspections/GetOrderList") können auf eine einzelne ID gefiltert
werden.
· Wird diese ID angegeben, werden alle anderen übergebenen Filter ignoriert. Es werden nun nur die Daten für
diese eine ID zurück gegeben. Sämtliche andere Filtermöglichkeiten müssen trotzdem valide sein. Es empfiehlt sich
daher, alle anderen Filtermöglichkeiten nicht zu übergeben.

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen, die im Anhang zu finden sind.
7
OpenAPI in CAQ.Net API

2.4 Besonderheiten der Prüfdatenerfassung

In der Prüfdatenerfassung können einige Merkmaltypen nur auf eine bestimmte Art und Weise Messwerte
übergeben. Hierzu gibt es feste Vorgaben.
Ø Der Call, zur Prüfdatenerfassung lautet "WriteSampleData" und kann im Swagger 7 unter "Inspections" gefunden
werden.

Abbildung: Swagger Dokumentation - Prüfdatenerfassung

Merkmaltypen und deren Vorgaben

Merkmaltyp Vorgabe
Positionsbezogen -Vorher definierte Fehlerpositionen (kommasepariert) oder
-für keine Position: „-“
Qualitativ -"OK" und
-"Error"
Qualitativ nummerisch -Ein gültiger Double-Wert oder
-eine ungenaue Angabe wie z.B. „>1,234“
Klassierend Die einzelnen Einträge aus dem dazugehörigen
Klassierungskatalog können kommasepariert angegeben
werden.
Quantitativ Gültiger Double-Wert

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen.
8
 API OpenAPI in CAQ.Net

2.5 Anwendungsbeispiel
Mit der openAPI-Schnittstelle ist es möglich, Prozesse in Echtzeit zu automatisieren. Es können Daten mehrerer
Module gleichzeitig bzw. nacheinander abgerufen, aktualisiert, angelegt und gelöscht werden.
Ø So können bei einer Anmeldung an einer Maschine Daten des Maschinenbedieners abgefragt werden, um eine
sichere Anmeldung zu gewährleisten, z.B. ob der Bediener alle notwendigen Qualifikationen zum Bedienen der
Maschine besitzt. Dies funktioniert mit dem Call "Qualifications/GetQualifications".
{
"NameFilter": {
"Value": "Mustermann",
"Operator": "Equal"
},
"IncludeCurrentUserStatus": true,
"AuthID": "XB****************"
}

· Hierbei können alle Qualifikationen des Bedieners, oder auch die notwendigen Qualifikationen der Maschine
abgerufen werden. Hat der Maschinenbediener alle erforderlichen Qualifikationen, gibt die Maschine die
Anmeldung frei, hat er sie nicht, bleibt sie gesperrt.
Ø Auch der Prüfungsstand z.B. einer Maschine kann überprüft werden. Somit besteht die Möglichkeit, die Maschine
bei einer ungültigen Prüfung zu sperren, um große Sicherheitsrisiken zu vermeiden. Hierzu wird der Call
"Inspections/GetOrderList" verwendet.
{
"IDFilter": 10,
"AuthID": "XB****************"
}

Ø Ob alle erforderlichen Materialien, um das gewünschte Produkt herzustellen, vorhanden sind, wird mit dem Call
"Articles/GetArticleList" abgefragt.
{
"NumberFilter": {
"Value": "1000",
"Operator": "Like"
},
"AuthID": "XB****************"
}

Ø Selbst wenn eine Unregelmäßigkeit auftritt, kann diese an der Maschine über API bearbeitet und abgeschlossen
werden. Mit dem Call "Nonconformities/GetNonconformitiesList" können beliebige Unregelmäßigkeiten
abgerufen werden.
{
"ArticleFilter": {
"Value": "Drehteil",
"Operator": "Like"
},
"StatusFilter": {
"Value": "In Arbeit",
"Operator": "Equal"
},
"AuthID": "XB****************"
}

· "Nonconformities/CompleteNonconformity" vervollständigt die Unregelmäßigkeit mit den in der Funktion

definierten Parametern.
{

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen, die im Anhang zu finden sind.
9
OpenAPI in CAQ.Net API

"Nonconformity": {
"Number": "IR-001",
},
"CompletionStatus": {
"Name": "In Arbeit",
},
"DateCompletion": "2020-11-17T05:29:09.760Z",
"CompleteSubitems": true,
"AuthID": "XB****************"
}

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen.
10
 API

Index
-A-
Allgemeines 4
Anwendungsbeispiel 9
Authentifizierung 6

-B-
Besonderheiten bei Prüfdatenerfassung
Merkmaltyp 8
Vorgabe 8

-E-
Einleitung 4

-F-
Filtermöglichkeiten
Attribute 7
Filter auf ID 7
Listen auf ID filtern 7

-L-
Login
AuthID 6

-O-
OpenAPI in CAQ.Net 4

-S-
Swagger 7

© 1993 - 2022 Copyrights by CAQ AG Factory Systems Rheinböllen. Alle Rechte vorbehalten. Es gelten ausschließlich unsere AGB und Lizenzbedingungen, die im Anhang zu finden sind.
11