Loading Data From External Applications And Services
It is possible to load data into an AMS message from an external web application or service. This can be used as a way to look up records from external databases.
To allow AMS to load data from an external web application you must provide a web service accessible over the internet using HTTP or HTTPS that accepts a XML POST request and replies with a correctly formatted XML response.
General Request - Response Process
- User selects Remote Load command from the phone menu.
- Current data in the message is sent to the AMS message gateway.
- This data is transformed into XML.
- The message XML is wrapped inside a XML tag with name "remoteLoadRequest"
- An optional "authKey" attribute is added to the "remoteLoadRequest" element and as a custom HTTP header with name "x-ams-auth-key". This key is an encrypted version of the key provided in the Remote Load command definition, details of the format are provided below.
- The XML is sent as an HTTP form POST to the url provided in the Remote Load command definition.
- The response from the remote server, if successful, is read and parsed by the AMS gateway into binary for merging into the current message on the phone. The response from the remote server must have content type "application/xml" and be wrapped in a "remoteLoadResponse" element.
- The data is merged with the current message on the phone and the screen refreshed. Data from the response will replace any existing data in the message.
Verifying Hashed Auth Keys
The general process used to verify the hashed value of the auth key is:
- Get the hash size in bytes for the algorithm used (SHA256 by default)
- Decode the auth key from Base64
- Extract the salt
- Compute the hash of the auth key using the salt
- Compare the generated hash with the one provided in the request
The general process used to compute the hashed value of the auth key is:
- Generate a random salt of any size, or use one provided
- Convert your auth key into bytes using UTF8 encoding
- Combine your encoded key with your salt
- Hash the combined result using SHA256 algorithm
- Combine your hash result with your salt
- Encode the combined hash and salt with Base64 encoding
This is a basic sample outlining the above process in C# targeting .Net 3.5. It is only for illustration and is not suitable for production use.