Central Services integrations

This article describes the available integrations for Central Services.

Dispatch (CAD)

Central Services can integrate against a Computer Aided Dispatch (CAD) system. This allows the CAD to dispatch missions, messages and requests to be supplied to Mobile Device Terminals (MDT) running Vehicle Services. Additionally, Central Services will forward logs, messages and other requests back to the CAD.

There are several ways this can be achieved depending on the use case:

  • GD92: Central Services hosts a GD92 node, including a Router and Message Transfer Agent. The transport is done using a WebSocket secured by TLS, the message format being raw binary GD92 data in both directions (Central Services to CAD and CAD to Central Services).

  • HTTP client: Central Services can run a HTTP client and connect to a remote server to retrieve mission information, and also supply data back. This can be achieved using the JSON or XML formats, using REST APIs or Websockets, with a large set of authentication methods. Due to variety of server implementations, this setup is out of the scope of this article, please contact us at support@evam.life if you are interested in this solution.

  • Other: Please contact us at support@evam.life to discuss your use case, we are always interested in new collaborations.

GD92 websocket

In this setup, the GD92 node in Central Services can be reached through a Websocket over TLS, using OAuth2 as authentication protocol.

You need a Central Services account to authenticate. This account will be used to identify your CAD as user. Keep in mind this is not the same account as your Central Services admin user, which you typically use for managing your organisation and its users.

Please follow those steps to get started with this integration:

  1. Please send a mail at support@evam.life with the subject “Central Services access for GD92 websocket” using your work email. In this mail, specify the email address for this Central Services user, this mail address must have the same domain as your work email.

  2. Your request will be processed, and if granted your Central Services user will be created and a temporary password will be sent back to your work email. You will also be provided with the URL to the Central Services instance and other details you will need to access the websocket.

  3. Login in Central Services using the provided URL. You will be prompted for a password change, make sure to use a complex password and save it in a secure location. It will not be possible to retrieve it if lost, but we can reset it if needed.

  4. When prompted, setup your 2FA device for security hardening.

  5. Once done, you should be in the Central Services web portal:

Central Services web portal

Portal

  1. At that stage, your account is ready and you can close this page.

  2. Now, you should connect to the GD92 websocket and send GD92 messages - if successful they will show in the interface.

Achieving this is dependent on the stack used by your CAD system backend and you should adhere to its best practices in terms of websocket connection and OAuth2 usage. You can find below a basic example “CAD MTA”, written in Python 3. This code connects to the GD92 socket and sends a TEXT message to a given GD92 address, then waits for an answer and prints it before exiting.

The following dependencies should be installed for this code to run:

  • oauthlib

  • requests-oauthlib

  • requests

  • websockets

You also need to define these environment variables:

  • INTEGRATION_URI: The URI to the GD92 websocket, you can find it in the mail received at step 2,

  • TOKEN_URL: The URL to the token endpoint for OAuth2, you can find it in the mail received at step 2,

  • USERNAME: Your Central Services user email,

  • PASSWORD: The complex password you have set at step 3.

from os import environ

from oauthlib.oauth2 import LegacyApplicationClient
from requests_oauthlib import OAuth2Session
from websockets.sync.client import connect

integration_uri = f"wss://{environ['INTEGRATION_URI']}"

client = LegacyApplicationClient(client_id="integration", scope="profile email openid")

token_url = environ["TOKEN_URL"]
session = OAuth2Session(client=client)

print("Fetching token...")
tok = session.fetch_token(
    token_url=token_url,
    username=environ["USERNAME"],
    password=environ["PASSWORD"]
)
print("Token obtained successfully")

headers = {"Authorization": f"Bearer {tok.get('access_token')}"}

print("Connecting...")
ws = connect(integration_uri, additional_headers=headers)
print("Connected")


# TEXT message: 'Hello from Python', destination '47.201.50'
text_message = bytes.fromhex('11002d07012f327211005b1b0101001148656c6c6f2066726f6d20507974686f6e75')

print("Sending TEXT...")
ws.send(text_message)

print("Waiting for answer from CS...")
msg: bytes = ws.recv()

print(f"[Received message] {' '.join(list(map(lambda b: '{:02X}'.format(b) ,msg)))}")

Running this code will produce this output:

Fetching token...
Token obtained successfully
Connecting...
Connected
Sending TEXT...
Waiting for answer from CS...

If you get some error, some of the environment variables may be incorrect, please double check them.

Shortly after, you should get a message back from CS:

[Received message] (...)

If all is working, then you are ready to use the GD92 websocket in your own CAD application, simply use the same parameters as above.

Keep in mind this is a basic setup, with minimal security and no retry mechanism in case the connection were to fail.

Other

Please contact us at support@evam.life to discuss your specific use case.