Last modified by Steffi F on 2025/06/16 13:10
Show last authors
1 {{aagon.floatingbox/}}
2
3 = **Wozu dient das Arbeiten mit der API?** =
4
5 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 und abspeichert. Zusätzlich wird ein REST-Client benötigt, welcher den Zugriff und das Ausführen der Commands gewährleistet.
6
7 Diese Komponenten ermöglichen den Datenaustausch und kann u.a. von der ACMP App genutzt werden, um Daten aus ACMP auszulesen und zu speichern.
8
9 = **Voraussetzungen für das Arbeiten mit ACMP und der Public API** =
10
11 Um den Datenaustausch zwischen ACMP und AESB über die Public API zu ermöglichen, müssen folgende Voraussetzungen gegeben sein:
12
13 * Sie haben bereits einen AESB im Einsatz, der mit dem ACMP Server verbunden und konfiguriert ist
14 * Sie haben einen REST-Client installiert (z.B. Insomnia REST, dessen vorgefertigte Definitionsdatei Sie von uns erhalten)
15
16 = **Vorbereitung zum Datenaustausch** =
17
18 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.
19
20 == Verbindungsaufbau vom ACMP zum AESB ==
21
22 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.//
23
24 Haben Sie noch keine Informationen zum AESB eingetragen, dann können Sie [[hier>>doc:ACMP.68.ACMP-Solutions.System.Einstellungen.ACMP Server.WebHome||anchor="HSICS-Verbindung"]] nachlesen, wie Sie die Verbindung eintragen.
25
26 {{aagon.infobox}}
27 Beachten Sie unter den Einstellungen der SICS-Verbindung die Einstellung Public API Zugriffsberechtigung. Gewähren Sie über das Aktivieren der Checkbox den Zugriff, dann können SICS-Benutzer ebenfalls Public API Commands ausführen. Auf dem ACMP Server wird dann jede Nachricht von einem unbekannten Benutzer als SICA-Benutzer interpretiert und mit administrativen Berechtigungen versehen. Dadurch greift in diesem Fall keine Berechtigungsüberprüfung!
28 {{/aagon.infobox}}
29
30 == Verbindungsaufbau vom REST-Client zum SICS ==
31
32 {{aagon.infobox}}
33 Als REST-Client wird hier Insomnia REST genutzt.
34 {{/aagon.infobox}}
35
36 I.d.R. erhalten Sie zu Insomnia die Definitionsdatei vom Aagon Support.
37
38 ~1. Öffnen Sie Insomnia und importieren Sie die Definitionsdatei über //Import/Export > Data > Import Data//.
39
40 {{figure}}
41 [[image:XKEfU69IjD.png]]
42
43 Importieren der Definitionsdatei.
44 {{/figure}}
45
46 2. Über Strg + E können Sie die Insomnia Environment Config öffnen. Tragen Sie die Server-URL //https:~/~/ 127.0.0.1:3900/// ein.
47
48 {{aagon.infobox}}
49 Der Standard-Port für die AESB REST-API ist 3900.
50 {{/aagon.infobox}}
51
52 {{figure}}
53 [[image:vmware_STgoccXyHT.png]]
54
55 Eintragen der Server-URL.
56 {{/figure}}
57
58 Diese Verbindungen sollten aufgebaut werden, damit die Datenübertragung einwandfrei funktioniert.
59
60 = Eine Session starten =
61
62 Damit der Datenaustausch überhaupt stattfinden kann, muss eine Session und damit ein Request gestartet werden.
63
64 Loggen Sie sich dazu in Insomnia ein, wählen Sie die Umgebung bzw. das Environment und legen Sie fest, ob Sie für die Session einen ACMP- oder einen SICS-Benutzer verwenden wollen.
65
66 {{figure}}
67 [[image:vmware_ti4pZCCmEj.png]]
68
69 Auswählen des Users
70 {{/figure}}
71
72 == SICS-Benutzer verwenden ==
73
74 Für die Verwendung eines SICS-Benutzers wählen Sie rechts im Befehlsbaum ConnectionRequest aus.
75
76 Im Bearbeitungsfenster tragen Sie dann den Usernamen und das Passwort des SICS-Benutzers ein. Klicken Sie anschließend auf Send.
77
78 == ACMP-Benutzer verwenden ==
79
80 {{aagon.infobox}}
81 Wenn Sie sich für die Verwendung eines ACMP-Benutzers entscheiden, empfehlen wir das Anlegen eines eigenen ACMP-Benutzers für die Verbindung.
82 {{/aagon.infobox}}
83
84 Soll statt eines SICS-Benutzers ein ACMP-Benutzer verwendet werden, muss zunächst ein Hashwert aus einem Passwort generiert werden.
85
86 {{aagon.infobox}}
87 Das Tool zum Generieren des Hashwertes erhalten Sie beim Aagon Support.
88 {{/aagon.infobox}}
89
90 Wählen Sie dann 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.
91
92 {{aagon.infobox}}
93 Der Wert für "PasswordHash" muss mit dem PBKDF2Algorithmus, der HMAC_SHA256 und einer HMAC-Länge von 32 verwendet, anhand der folgenden Werte berechnet werden. Passwort des Benutzers "Salt" aus der Antwort "IterationCount" aus der Antwort.
94 {{/aagon.infobox}}
95
96 Um aus den Daten nun den benötigten Hash zu generieren, starten Sie das Ihnen vom Support zugeschickten 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.
97
98 Tragen Sie nun den generierten Hashwert beim Befehl ConnectionHash ein und führen anschließend beide Befehle (schnell hintereinander) erneut aus, indem Sie bei beiden auf Send klicken.
99
100 = Callback Target erstellen =
101
102 Ein Callback Target dient dazu, die vom ACMP Server gesendete Antwort auf den Request zu speichern. Hierdurch können Sie Fehler erkennen und entsprechend reagieren. Zur besseren Trennung empfiehlt es sich, einen eigenen VirtualRouter zu erstellen, und in diesem das Callback Target abzulegen.
103
104 Gehen Sie folgendermaßen vor:
105
106 ~1. Zum Erstellen eines VirtualRouters wählen Sie aus der Navigation den Befehl CreateVirtualRouter. Im Bearbeitungsfenster tragen Sie den gewünschten Namen ein und klicken auf Send.
107
108 2. Nachdem der VirtualRouter angelegt wurde, kann das eigentliche Callback Target erstellt werden. Wählen Sie hierzu aus der Navigation CreateTarget aus. Wir verwenden in unserem Beispiel den TargetType „Queue“, da hier eingehende Nachrichten so lange gespeichert werden, bis diese manuell ausgelesen werden.
109
110 3. Wenn Sie den Targetnamen und den VirtualRouter eingetragen haben, klicken Sie auf //Send//.
111
112 == Asset anlegen ==
113
114 4. Nachdem das CallbackTarget in einem eigenen VirtualRouter erstellt wurde, können Sie nun ein Asset anlegen. Wählen Sie hierzu den Publish-Befehl aus.
115
116 5. Tragen Sie nun die die Base64 encodete ICQL-Message von SaveAssets in den Body ein und passen Sie die Parameter an.
117
118 6. Klicken Sie anschließend auf //Send//.
119
120 {{aagon.infobox}}
121 Beachten Sie, dass der Inhalt des Bodys immer Base64 encoded sein muss. Zum encoden können Sie entweder das im ACMP vorhandene Client Command nutzen oder den Text auf dieser Seite encoden lassen.
122 {{/aagon.infobox}}
123
124 == Result abholen ==
125
126 7. Um zu prüfen, ob beim Erstellen des Assets ein Fehler aufgetreten ist, wählen Sie nun den Consume-Befehl.
127
128 8. Klicken auf Send.
129
130 9. Auf der rechten Seite des Fensters wird Ihnen nun das Ergebnis vom ACMP angezeigt.
131
132 {{aagon.infobox}}
133 Beachten Sie, dass der Inhalt des Bodys immer Base64 encoded zurückgeliefert wird.
134 {{/aagon.infobox}}
135
136 Zum Decoden können Sie entweder das im ACMP vorhandene Client Command nutzen oder den Text auf dieser Seite decoden lassen.
137
138 = Ressourcen aufräumen =
139
140 Damit nach dem Abschluss der Arbeiten keine Ressourcen verbleiben, sollte man die erstellten Ressourcen aufräumen. Hierbei muss in umgekehrter Reihenfolge wie beim Anlegen der Ressourcen vorgegangen werden.
141
142 Wählen Sie zunächst mit dem Befehle DeleteTarget und klicken Sie auf Send. Hierdurch wird das erstellte CallbackTarget gelöscht.
143
144 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.
145
146 Abschließend wird die Session beendet, indem Sie den Befehl Logout wählen und auf Send klicken.
147
148
149
© Aagon GmbH 2025
Besuchen Sie unsere neue Aagon-Community