Wozu dient das Arbeiten mit der API?

Mithilfe einer API haben Sie die Möglichkeit, einen Datenaustausch zwischen einzelnen Systemen schnell und unkompliziert durchzuführen. Im ACMP wird dafür die Public API genutzt, welche zwischen dem ACMP Server und dem AESB kommuniziert und mittels Public API-Befehlen bzw. Commands Informationen ausliest, abspeichert sowie Aktionen ausführt. Zusätzlich wird ein REST-Client benötigt, welcher den Zugriff und das Ausführen der Commands gewährleistet.

Diese Komponenten ermöglichen den Datenaustausch und kann u.a. von der ACMP App genutzt werden, um Daten aus ACMP auszulesen und zu speichern.

Voraussetzungen für das Arbeiten mit ACMP und der ACMP Public API

Um den Datenaustausch zwischen ACMP und AESB über die Public API zu ermöglichen, müssen folgende Voraussetzungen gegeben sein:

• Sie haben bereits einen AESB im Einsatz, der mit dem ACMP Server verbunden und konfiguriert ist
• Sie haben einen REST-Client installiert (z.B. Insomnia REST, dessen vorgefertigte Definitionsdatei Sie von uns erhalten)

Vorbereitung zum Datenaustausch

Im Folgenden werden die notwendigen Schritte erläutert, welche im ACMP und im REST-Client vorgenommen werden müssen, um einen einwandfreien Datenaustausch zu ermöglichen. Die Einstellungen für den REST-Client werden hier am Beispiel von Insomnia REST aufgezeigt. Prinzipiell aber kann jeder andere REST-Client ebenfalls dazu genutzt werden.

Verbindungsaufbau vom ACMP zum AESB

Arbeiten Sie bereits mit dem AESB, dann werden Sie i.d.R. eine Verbindung vom ACMP zum AESB über den SICS hergestellt haben. Kontrollieren können Sie diese in der ACMP Console unter System > Einstellungen > ACMP Server > SICS-Verbindung.

Haben Sie noch keine Informationen zum AESB eingetragen, dann können Sie hier nachlesen, wie Sie die Verbindung eintragen.

Außerdem sollten Sie unter dem Abschnitt Public API Antwort die maximale Anzahl an Elementen der Public API Antwort erhöhen.

Verbindungsaufbau vom REST-Client zum SICS

I.d.R. erhalten Sie zu Insomnia die Definitionsdatei vom Aagon Support.

1. Öffnen Sie Insomnia und navigieren Sie in der obersten Leiste zu Application > Preferences.

2. Unter General steuern Sie zum Absatz Request/Response und deaktivieren das Häkchen unter Validate Certificates.

Nun können Sie mit dem Importieren der Insomnia-Definitionsdatei beginnen.

1. Öffnen Sie Insomnia und importieren Sie die Definitionsdatei über Import/Export > Data > Import Data > Import Data as > Request Collection.

2. Wählen Sie die Definitionsdatei im JSON-Format aus. Ist der Import erfolgreich verlaufen, erscheint ein Hinweis, der den Import bestätigt.

3. Öffnen Sie dann über Strg + E die Insomnia Environment Config.

3. Klicken Sie im linken Arbeitsbereich auf Base Environment und tragen Sie unter „BaseUrl“ die Server-URL https:// 127.0.0.1:3900/ ein.

4. Klicken Sie dann auf Done.

Diese Verbindungen sollten aufgebaut werden, damit die Datenübertragung einwandfrei funktioniert.

Eine Session starten

Damit der Datenaustausch stattfinden kann, muss erst eine Session und damit ein Request gestartet werden.

Loggen Sie sich dazu in Insomnia ein und legen Sie die Umgebung fest, indem Sie für die Session einen ACMP- oder einen SICS-Benutzer verwenden.

SICS-Benutzer verwenden

Für die Verwendung eines SICS-Benutzers gehen Sie folgendermaßen vor:

1. Wählen Sie rechts im Befehlsbaum ConnectionRequest aus.
2. Im Bearbeitungsfenster tragen Sie dann den Usernamen und das Passwort des SICS-Benutzers ein.
3. Klicken Sie anschließend auf Send.

ACMP-Benutzer verwenden

Für die Verwendung und das anschließende Arbeiten mit einem ACMP-Benutzer, muss zunächst ein Hashwert aus einem Passwort generiert werden.

Wählen Sie im Insomnia unter Activate Environment Use Acmp, tragen Sie dann den Usernamen und den AcmpServerNamen ein. Klicken Sie nun auf Send, um Salt und Iterationcount für das Hashen des Passworts zu erhalten.

Um aus den Daten nun den benötigten Hash zu generieren, starten Sie das Ihnen vom Support zugeschickte Tool über die Kommandozeile. Geben Sie hierbei die Parameter Passwort, Salt und IterationCount an und drücken Sie die Eingabetaste. Ihnen werden die angegebenen Parameter angezeigt und der Hashwert generiert.

Tragen Sie nun den generierten Hashwert unter ConnectionHash ein und führen anschließend beide Befehle (schnell hintereinander) erneut aus, indem Sie bei beiden auf Send klicken.

Callback Target erstellen

Falls diese Option nicht nötig ist, können Sie direkt zu Clientliste laden springen.

Ein Callback Target dient dazu, die vom ACMP Server gesendete Antwort auf den Request zu speichern.

Zur besseren Trennung empfiehlt es sich, einen eigenen VirtualRouter zu erstellen und in diesem das Callback Target abzulegen.

Im Nachfolgenden wird erklärt, wie Sie einen Callback Target erstellen:

1. Vorab muss ein VirtualRouter angelegt werden. Wählen Sie dafür in der Navigation den Befehl CreateVirtualRouter.
2. Tragen Sie im rechten Bearbeitungsfenster den gewünschten Namen für den VirtualRouter ein.
3. Klicken Sie auf Send.

Nachdem der VirtualRouter angelegt wurde, kann das eigentliche Callback Target erstellt werden.

1. Wählen Sie hierzu aus der Navigation Target > CreateTarget aus.
2.  In diesem Beispiel wird der TargetType “Queue” eingetragen, da hier eingehende Nachrichten so lange gespeichert werden, bis diese manuell ausgelesen werden.
3. Tragen Sie einen beliebigen Targetnamen und den VirtualRouter, den Sie im Schritt davor benannt haben, ein.
4. Klicken Sie auf Send.

Mit diesen Schritten haben Sie nun ein CallbackTarget in einem eigenen VirtualRouter erstellt.

Clientliste laden

Nachdem das CallbackTarget in einem eigenen VirtualRouter erstellt wurde, können Sie die API Commands wie folgt nutzen:

1. Wählen Sie hierzu den Befehl Publish in der linken Arbeitsleiste aus.
2. Encoden Sie dann das Command Clientliste laden, indem Sie entweder das im ACMP vorhandene Client Command Encode Base64 string nutzen oder auf einer beliebigen Internetseite den Text encoden lassen.

1. Tragen Sie dann die Base64 encodete ICQL-Message in den Body ein und passen Sie ggf. die Parameter an (z.B. den Callback_VirtualRouter, d.h. den vergebenen VirtualRouter Namen).
2. Klicken Sie anschließend auf Send.

Um zu prüfen, ob beim Laden der Clientliste ein Fehler aufgetreten ist, gehen Sie folgendermaßen vor:

1. Wählen Sie nun den Consume-Befehl im linken Arbeitsbereich.
2. Klicken auf Send. Auf der rechten Seite des Fensters wird Ihnen nun das Ergebnis vom ACMP angezeigt.

1. Zum Decoden können Sie entweder das im ACMP vorhandene Client Command Decode Base64 string nutzen oder den Text auf einer beliebigen Internetseite decoden lassen.

Ressourcen aufräumen

Damit nach dem Abschluss der Arbeiten keine Ressourcen verbleiben, sollten die erstellten Ressourcen aufgeräumt werden. Hierbei muss in umgekehrter Reihenfolge wie beim Anlegen der Ressourcen vorgegangen werden.

Wählen Sie zunächst den Befehl DeleteTarget und klicken Sie auf Send. Hierdurch wird das erstellte CallbackTarget gelöscht.

Sofern der erstellte VirtualRouter keine weiteren Callback Targets enthält, kann dieser dann ebenfalls gelöscht werden.

Sollte der VirtualRouter noch CallbackTargets enthalten, müssen Sie diese nun zunächst löschen. Wählen Sie zum Löschen des VirtualRouters den Befehl DeleteVirtualRouter und klicken auf Send.

Abschließend wird die Session beendet, indem Sie den Befehl Logout wählen und auf Send klicken.