API Verbindungen

Mit einer API-Verbindung wird die Verbindung zur externen API (Schnittstelle, Application Programming Interface) hergestellt. API-Verbindungen werden in Modulen benötigt, die eine Verbindung zu einer externen Schnittstelle herstellen (z.B. zu einer REST-Schnittstelle). Eine API-Verbindung ist stark von der API abhängig.

Grundsätzlich wird die Schnittstelle mit den Verbindungsdaten abgefragt und es kommt ein JToken zurück (als Objekt oder Array). Im Workflow-Modul, das für die Abfrage im Workflow zu Einsatz kommt, muss dann nur noch die in der Verbindung angegebene Basis URL durch die Ressource erweitert werden um Daten zu lesen oder zu schreiben.

Bei der Verwendung einer API-Schnittstelle ist eine enge Zusammenarbeit mit dem Betreuer der Gegenstelle (z.B. ein DMS-System, siehe auch DMS Anbindung) unbedingt erforderlich.

Um eine API-Verbindung zu erstellen, zu bearbeiten oder zu löschen, gehen Sie wie folgt vor:

Um die Webadministration zu öffnen, geben Sie im Webbrowser http://<Hostname>/webadmin ein (wobei Hostname dem Server entspricht, auf dem das IQ4docs WebAdmin installiert wurde). In einer Mandantenumgebung geben Sie die URL ein, die Sie vom Mandantenverwalter erhalten haben (z.B. http://server/webadmin/#/cf992178-4bd6-431c-b815-b9d734d0ded3). Wenn Sie noch nicht angemeldet sind, melden Sie sich mit einem Anwender mit Administratorrechten (Login und Passwort) oder dem IQ4docs Systemadministrator (standardmäßig administrator mit Passwort admin) an.

Klicken Sie in der Webadministration im Menü auf Workflows und anschließend auf API-Verbindungen.

In der Listenansicht der API-Verbindungen klicken Sie auf + API Verbindung erstellen und eine Verbindung anzulegen. Sie gelangen direkt zu den Einstellungen der API-Verbindung.

Um eine Verbindung zu bearbeiten klicken Sie auf das Bearbeitungssymbol, zum Löschen auf das Löschsymbol.

Für jeden Typ einer API-Verbindung gibt es ein zugehöriges, gleichnamiges Workflow-Ziel-Modul. In diesem werden die hier hinterlegten Einstellungen automatisch zum übertragen der Daten an das entsprechende DMS-System verwendet.

Die Verbindungseinstellungen kann auch z.B. in einem Rest-Modul ausgewählt und zum Lesen von Daten verwendet werden.

Ist der gewünschte Typ ausgegraut, existiert schon eine API-Verbindung dieses Typs. Es kann nur eine API-Verbindung je Typ angelegt werden.

Der Name der Verbindung ist frei wählbar. In einem Workflow-Modul (z.B. Interview Auswahl (REST)) wird dieser Name als Bezeichnung für die in den Moduleinstellungen auswählbare Verbindung verwendet.

Die Webadresse (URL) auf der der Server Daten zurückliefert oder entgegennimmt. Diese Basis URL wird bei der Abfrage um die Ressource erweitert, die im Modul eingestellt ist.

Beispiele:

  • https://api-server/

  • https://graph.microsoft.com:443/v1.0/

Wählen Sie aus der Klappliste Authentifizierung den Authentifizierungstyp, den die externe API anbietet (wird bereits passend voreingestellt). Je nach Authentifizierungstyp sind unterschiedliche Angaben erforderlich:

Es findet keine Authentifizierung an der API statt, die API kann auch ohne Authentifizierung abgefragt werden.

Die Basis-Authentifizierung ist der einfachste Weg eine Authentifizierung zu ermöglichen. Anmeldename und Passwort werden im HTTP-Header übertragen.

  • Anmeldename: Anmeldename, der für die Authentifizierung an der Schnittstelle verwendet werden kann.

  • Passwort: Passwort für den Anmeldenamen. Kicken Sie zum Erfassen eines neuen Passwortes auf Passwort eingeben oder um ein bestehendes Passwort zu ändern auf Passwort ändern.

Das JSON Web Token (JWT) ist ein genormtes Webtoken mit dem sich JSON-Objekte sicher zwischen den Kommunikationspartnern austauschen lassen.

  • Anmeldename: Anmeldename, der für die Authentifizierung an der Schnittstelle verwendet werden kann.

  • Passwort: Passwort für den Anmeldenamen. Kicken Sie zum Erfassen eines neuen Passwortes auf Passwort eingeben oder um ein bestehendes Passwort zu ändern auf Passwort ändern.

  • Login-URL: Die URL zum Server, der das Login-Token zurückgibt. Dies muss nicht zwingend der gleiche Server sein, der die Daten liefert, z.B. https://api-server/auth/

  • LoginRequest Template: Da jede Schnittstelle unterschiedliche Daten erfordern kann, wird hier in einem JSON-Tempate festgelegt, welche Daten für die Authentifizierung benötigt werden, z.B.:
    {"AuthMode":"Credentials","Username":"{{username}}","Password":"{{password}}"}

OAuth2 ist der aktuelle Quasi-Standard für eine sichere API-Authentifizierung (auch Microsoph Graph kann per OAuth2 abgefragt werden).

  • Login-URL: Die URL zum Server, der das Login-Token zurückgibt. Dies muss nicht zwingend der gleiche Server sein, der die Daten liefert, z.B. https://api-server/auth/

  • Scope: Geben Sie den Scope an, der die Zugriffsberechtigungen abgrenzt, z.B. https://graph.microsoft.com/.default

  • Client Id: Die Client-ID wird vom Azure-AD beim Registrieren der Anwendung vergeben (Client-ID und Client-Secret sind die Zugangsdaten). Sie werden vom WorkflowService für die Abfrage der API verwendet.

  • Client Secret: Das Client-Secret wird - wie die Client-ID - bei der Registrierung der App erzeugt. Haben Sie bereits ein Client-Secret erfasst, können Sie es über die Schaltfläche Client-Secret ändern ändern. Nach dem Eintragen wird das gespeicherte Client-Secret aus Sicherheitsgründen nie mehr an den Browser übertragen.

Die Microsoft Azure Authentifizierung ist der OAuth2-Authentifizierung ähnlich, anstatt der login-URL muss die Mandantendomäne angegeben werden.

  • Mandatendomäne: Geben Sie die Microsoft Azure Mandantendomäne an.

  • Scope: Geben Sie den Scope an, der die Zugriffsberechtigungen abgrenzt, z.B. https://graph.microsoft.com/.default

  • Client Id: Die Client-ID wird vom Azure-AD beim Registrieren der Anwendung vergeben (Client-ID und Client-Secret sind die Zugangsdaten). Sie werden vom WorkflowService für die Abfrage der API verwendet. Die dafür nötigen Rechte müssen gegeben sein, siehe auch IQ4docs App in Microsoft Azure registrieren.

  • Client Secret: Das Client-Secret wird - wie die Client-ID - bei der Registrierung der App im Azure-AD erzeugt. Haben Sie bereits ein Client-Secret erfasst, können Sie es über die Schaltfläche Client-Secret ändern ändern. Nach dem Eintragen wird das gespeicherte Client-Secret aus Sicherheitsgründen nie mehr an den Browser übertragen.

Ein API-Key ist ein eindeutiger Schlüssel, den die Gegenstelle (also die abzufragende Ressource) zur Verfügung stellen muss. Durch diesen Schlüssel wird IQ4docs eindeutig identifiziert und autorisiert bestimmte Ressourcen abzufragen oder Daten zu übertragen. Ein Api Key könnte z.B. so aussehen: 4ab061697d644c88b1f30f50ebdf0a83

Kicken Sie zum Erfassen eines neuen API-Keys auf API-Key eingeben oder um ein bestehendes Passwort zu ändern auf API-Keyändern.