Introduction
TMA ASAP replaces the legacy SOAP via VPN CSAA message broker for ASAP to PSAP, using a REST interface with mutual authentication for communication. (TMA used to be CSAA.) The XML messages are essentially unchanged - they are just communicated via REST. The XML schema can be found at: http://www.apcointl.com/new/commcenter911/external-alarm.xsd
Like the legacy broker, TMA ASAP requires two one-way channels for communication, one from Alarm to Dispatch, and one from Dispatch to Alarm. Configuration of these endpoints is controlled through the appsettings.json.
Driver file
The TMA ASAP dispatch driver's file is TmaAsapDispatchProvider.dll.
Configuration file settings
appsettings.json has an object section called "TMAASAP" that contains all configuration for this driver. The default configuration is shown below, and is fully documented in the file.
| "TMAASAP": { // The URL of the TMAASAP service "url": "https://test.asapmb.tma-asap.org:28443/ASAPWebService.asmx"", //"url": "https://prod.asapmb.tma-asap.org:28443/ASAPWebService.asmx"", // The port on which the ASAP response listener will listen. // Note that the ASAP response route is .../api/asap-message. "listenPort": 443, // The thumbprint of the client certificate to use. // The certificate is provided by TMA and must be placed in the 'Local Computer' store, 'Personal' folder. "clientCertificateThumbprint": "", // The thumbprint of the server certificate to use. // The certificate is provided by TMA and must be placed in the 'Local Computer' store, 'Personal' folder. "serverCertificateThumbprint": "", // CSAA Service Provider ID "providerId": "<NOTSET>", // When disabled, phone extensions will not be sent. // Sending extensions is the standard behavior. "phoneExt": true, // When disabled, contact phone numbers will be sent without any formatting - i.e. only numeric characters in phone. // Sending formatted phone numbers is the standard behavior. "phoneFormatting": true } |
URL
Note the test endpoint vs. the production endpoint. Each Central Station will be required to test their setup with TMA before switching to production use.
ListenPort
This driver will set up a pseudo-IIS server listening on the specified port for messages from TMA. Note that the response route is fixed at /api/asap-message. For example, if we had TMA ASAP set up on sdksupport.boldgroup.solutions, listenPort 33443, TMA would send responses to https://sdksupport.boldgroup.solutions:33443/api/asap-message. The Central Station will have to let TMA know what the appropriate URL is.
Client and Server Certificate Thumbprints
TMA will create their own certificates and give them to the Central Station. Currently, the same certificate applies to both the client (Central Station -> TMA) and server (TMA -> Central Station), so the thumbprints would be the same. If these are ever split, the configuration allows them to be different. See the certificate section below for complete information about installing the certificate and setting the thumbprints here. This driver's client and server processes use the thumbprint to find the appropriate certificate.
ProviderId
This is the ID (typically 3 characters) provided by TMA to identify the Central Station.
PhoneExt/Formatting
These options should remain the default values unless the standard behavior needs to be overridden.
Certificates
TMA requires mutual authentication in its communications with Central Stations. This means both sides will verify each other before messages are sent. When the Central Station initiates a transaction with TMA, the Central Station client will verify TMA's server certificate and the TMA server will verify the Central Station's client certificate to ensure each side is who they say they are. The same thing happens when TMA initiates a response to the Central Station.
Important! Make sure to open the Server certificate manager (certlm), not the user-based one.
TMA will create and supply the Central Station with the appropriate certificate file. This file must be imported into the Local Computer store Personal location, which will import 2 certificates. After importing, the ca.tma-asap certificate should be moved to the Trusted Root folder. Only the Central Station's certificate must remain in the Personal folder, and only the ca.tma-asap certificate must remain in the Trusted Root folder. Notice that the Central Station's certificate intended purposes covers both server and client authentication.
The thumbprint can be found by opening the Central Station's certificate, going to the Details tab, and scrolling down to Thumbprint:
This value is then copied to the client and server certificate thumbprints in the configuration file. If the server and client certificates are ever separated, each would have its own thumbprint that would be copied to the appropriate setting in the configuration file.
Reverse Commands
This integration uses the same reverse commands as the legacy integration, except that the parameters are no longer position-based - they are identified by the label. The database migration corresponding to this new integration will add the appropriate labels to all reverse command details of APCO Alarm reverse commands. New reverse command details must have the appropriate labels applied during data entry.
Parameter changes from legacy integration to this one:
1. Service Provider ID (SVID) is now defined in the configuration file, so the parameter is no longer necessary.
2. Service Provider Address (SVAD) is not used by TMA, so the parameter is no longer necessary.
Note that because the parameters are no longer position-based, it is not a problem to include these parameters - they will simply be ignored by TMA ASAP. The database migration will not remove them, maintaining backward compatibility with the legacy integration (existing reverse commands at the time of the database migration could be used with either the legacy integration or this one).
TMA ASAP requires three reverse commands to be configured: ALRM, UPD, and VRFY.
ALRM
| Field Type | Data Type | Label | DB Value |
|---|---|---|---|
| Database | Text | CONT | Contact's Name |
| Database | Text | CPNT | Contact Point |
| Database | Text | ALID | Alarm Unique Id |
| Database | Text | CMPY | Monitoring Company Name |
| Database | Text | OPID | Operator ID |
| Database | Text | UCBN | CS/User Call-back Number |
| Database | Text | TIME | Event Time |
| Database | Text | EVNT | Event Description |
| Database | Text | EVCD | Event Category Description |
| Database | Text | PTID | Point ID |
| Database | Text | ZNTX | Zone Description |
| Database | Text | Confirmation Text | Confirmed Alarm Text |
| Database | Text | Call To Premises Text | Call To Premises Text |
| Database | Text | PRMT | Permit Number |
| Database | Text | PRMC | Permit Category Description |
| Database | Text | CUST | Customer Name |
| Database | Text | CTYP | Customer Type |
| Database | Text | CROS | Customer Cross Street |
| Database | Text | SUBD | Customer Subdivision |
| Database | Text | CPHN | Customer Site Phone |
| Database | Text | ADDR | Full Address |
| Database | Text | ADNO | Address Number |
| Database | Text | ADPR | Address Pre-direction |
| Database | Text | ADST | Address Street Name |
| Database | Text | ADTY | Address Street Type |
| Database | Text | ADPO | Address Post-direction |
| Database | Text | ADUN | Address Unit |
| Database | Text | CITY | City Name |
| Database | Text | REGN | Region Name |
| Database | Text | POST | Post Code |
| Database | Text | GPSL | GPS Location |
| Database | Text | VURL | Video/Image Link |
| Database | Text | DLID | Dealer ID |
| Database | Text | DLNM | Dealer Name |
| Database | Text | DLPH | Dealer Site Phone |
| Database | Text | COTY |
County[Addr3] |
UPD
| Field Type | Data Type | Label | DB Value |
|---|---|---|---|
| Database | Text | CONT | Contact's Name |
| Database | Text | CPNT | Contact Point |
| Database | Text | ALID | Alarm Unique Id |
| Database | Text | INCD | Authority Incident Number |
| User Input | Text | Update Comment |
VRFY
| Field Type | Data Type | Label | DB Value |
|---|---|---|---|
| Database | Text | CONT | Contact's Name |
| Database | Text | CPNT | Contact Point |
| Database | Text | CSER | Customer Serial Number |
| Database | Text | CUST | Customer Name |
| Database | Text | ADDR | Full Address |
| Database | Text | ADNO | Address Number |
| Database | Text | ADPR | Address Pre-direction |
| Database | Text | ADST | Address Street Name |
| Database | Text | ADTY | Address Street Type |
| Database | Text | ADPO | Address Post-direction |
| Database | Text | ADUN | Address Unit |
| Database | Text | CITY | City Name |
| Database | Text | REGN | Region Name |
| Database | Text | POST | Post Code |
| Database | Text | COTY | County[Addr3] |
| Database | Text | UCBN | CS/User Call-back Number |
