Data Exchange with ACMP via Public API
What is the purpose of working with an API?
An API enables the quick and easy exchange of data between systems. In ACMP, the public API communicates between the ACMP Server and the AESB, reading and storing information using public API commands. Additionally, a REST client is required to access and execute the commands.
These components enable data exchange and can be used by the ACMP app, among other things, to read and save data from ACMP.
Requirements for Working with ACMP and the Public API
To enable data exchange between ACMP and AESB via the public API, the following requirements must be met:
- You already have an AESB in use that is connected to and configured with the ACMP Server.
- You have installed a REST client, such as Insomnia REST. You will receive the predefined definition file from us.
Preparing for Data Exchange
The following explains the steps that must be taken in ACMP and the REST client to enable proper data exchange. The settings for the REST client are shown using Insomnia REST as an example. However, any other REST client can be used in principle.
Verbindungsaufbau vom ACMP zum AESB
If you are already working with the AESB, you have likely established a connection from the ACMP to the AESB via the SICS. You can verify this in the ACMP console by navigating to System > Settings > ACMP Server > SICS Connection.
If you have not entered any information about the AESB yet, you can read here how to set up the connection.
Note:
Please note the public API access rights setting in the SICS connection settings. Enabling access by checking the box will allow SICS users to execute public API commands. On the ACMP Server, every message from an unknown user will be interpreted as a SICS user and assigned administrative permissions. In this case, no permission check will be performed!
Establishing a connection from the REST client to SICS
Note:
Insomnia REST is used here as the REST client.
You will usually receive the definition file for Insomnia from Aagon Support.
1. Open Insomnia and import the definition file via Import/Export > Data > Import Data.
Import the definition file.
2. Press Ctrl + E to open the Insomnia Environment Config. Enter the server URL https:// 127.0.0.1:3900/.
Note:
The default port for the AESB REST API is 3900.
Enter the server URL.
These connections should be established to ensure that data transmission works properly.
Starting a Session
In order for data exchange to take place, a session — and thus a request — must be initiated.
Log in to Insomnia, select the environment, and specify whether you want to use an ACMP or SICS user for the session.
Selecting the user
Using SICS users
To use a SICS user, select "ConnectionRequest" on the right side of the command tree.
Enter the SICS user's name and password in the editing window. Finally, click Send.
Use ACMP users
Note:
We recommend creating a separate ACMP user for the connection if you decide to use an ACMP user.
If an ACMP user is to be used instead of a SICS user, a hash value must first be generated from a password.
Note:
The tool for generating the hash value is available from Aagon Support.
Then select Use Acmp under Activate Environment, enter the user name and the Acmp server name. Now click Send to obtain the salt and iteration count for hashing the password.
Note:
The value for “PasswordHash” must be calculated using the PBKDF2 algorithm, which uses HMAC_SHA256 and a HMAC length of 32, based on the following values. User password ‘Salt’ from the response “IterationCount” from the response.
To generate the required hash from the data, start the command line tool sent to you by Support. Enter the parameters "Password," "Salt," and "IterationCount," then press the Enter key. The specified parameters will be displayed, and the hash value will be generated.
Enter the generated hash value in the ConnectionHash command, then quickly execute both commands by clicking Send for both.
Create Callback Target
A callback target stores the response that the ACMP Server sends in response to a request. This allows you to detect errors and respond accordingly. For better organization, it is recommended that you create a separate virtual router and store the callback target in it.
Proceed as follows:
1. Create a VirtualRouter by selecting the CreateVirtualRouter command from the navigation menu. 2. Enter the desired name in the editing window and click Send.
2. Once the virtual router has been created, you can create the actual callback target. To do so, select "Create Target" from the navigation menu. In our example, we use the "Queue" TargetType because incoming messages are stored here until they are read manually.
3. After entering the target name and VirtualRouter, click Send.
Create Asset
4. After creating a CallbackTarget in a separate VirtualRouter, you can create an Asset. Select the Publish command to do this.
5. Enter the Base64-encoded ICQL message from SaveAssets in the body, then customize the parameters.
6. Then, click Send.
Note:
Please note that the content of the body must always be Base64 encoded. To encode, you can either use the Client Command available in ACMP or encode the text on this page.
Collect result
7. To check whether an error occurred when creating the asset, select the Consume command.
8. Click Send.
9. The result from the ACMP is now displayed on the right side of the window.
Note:
Please note that the content of the body is always returned Base64 encoded.
To decode, you can either use the Client Command available in ACMP or decode the text on this page.
Clean up resources
To ensure that no resources remain after the work is complete, clean up the resources you created. To do so, undo the steps you took to create the resources in reverse order.
First, select the DeleteTarget command and click Send. This will delete the CallbackTarget that you created.
If the VirtualRouter does not contain any additional Callback Targets, you can delete it as well. If the virtual router still contains callback targets, you must first delete them. To delete the virtual router, select the DeleteVirtualRouter command and click Send.
Finally, exit the session by selecting the Logout command and clicking Send.