Skip to main content
Skip table of contents

Ajax Systems

About Ajax Systems

Ajax manufactures smart security systems and sensors for homes. Also it provides customers with event service.

Mirasys VMS communicates with Ajax event queue through UDD so Ajax alarm events are transferred to VMS events and are shown in Spotter.

Ajax System Requirements

  • Please ensure that you have configured Ajax System to work with AWS and that all necessary alarms are configured, which is needed to send to the Mirasys VMS

  • Check that AjaxDataValidator is enabled in the Mirasys VMS license

Ajax queue and events

Ajax Events queue is implemented as SQS FIFO type queue. The order in which events messages are sent by the Ajax Cloud server and 

received by the Partner server is strictly preserved. It is crucial for forming a coherent series of events generated by the Ajax security system devices.

At this moment UDD supports all Ajax events (395). All events are located in AjaxEventsDescription.xml file. It is possible to add new events that will be published in the future or delete some unnecessary events by changing the xml file.

For that it's needed just add new line with new event like in following example:

CODE 
<Event ID="M_01_20" name="opening detected" description="%3$s: opening detected, %1$s in %2$s" />

where ID - is unique event code of Ajax event (all event codes with description can be found on Ajax site (What is Enterprise API and how to use it | Ajax Systems Support) and description can be found on the Ajax site also in section "Event Codes" (don't forget to change the UDD4Ajax.xml file as well).

All event codes should be unique.

For translating Ajax events to VMS events is used AjaxDataValidator.dll library and UDD4Ajax.xml file.

If some new events are added to AjaxEventsDescription.xml file, they should be added to UDD4Ajax.xml too, to EventCode array and to EventName array (if short description (name) of new event differs from others in EventName array).

Before getting events from Ajax it is needed to connect to Ajax Endpoint by address "api.ajax.systems" with credentials (login, password and user role) and receive session and refresh tokens. Refresh token is used for refresh session every 14 minutes.

Ajax Queue

After get all necessary tokens is needed to connect to Amazon Web Services (AWS) queue service which called Simple Queue Service (SQS).

Ajax recommends long polling technique to use. Long polling requests let receive messages promptly and, at the same time, reduce the number of empty responses returned.

Long polling does not return a response until a message arrives in the message queue or the long poll times out.

Is used maximum value of a long-polling timeout - 20 seconds (AWS works with 20-second long polls by default).

For work with AWS SQS was downloaded C++ SDK (AWS SDK for C++ - Developer Guide (amazon.com)) source code from 

the Amazon GitHub repository (GitHub - aws/aws-sdk-cpp: AWS SDK for C++) and was compiled libraries in MS Visual Studio 2019 (Ninja compiler).

Here is a list of libraries which required for work with AWS SQS:

  • aws-cpp-sdk-sqs.dll

  • aws-cpp-sdk-core.dll

  • aws-cpp-sdk-sts.dll

  • aws-crt-cpp.dll

  • aws-c-s3.dll

  • aws-c-event-stream.dll

  • aws-checksums.dll

  • aws-c-mqtt.dll

  • aws-c-auth.dll

  • aws-c-http.dll

  • aws-c-io.dll

  • aws-c-cal.dll

  • aws-c-compression.dll

  • aws-c-sdkutils.dll

  • aws-c-common.dll

Also these libraries used in static version (*.lib). Moreover for success compilation are used following system libraries: 

  • wininet.lib

  • userenv.lib

  • rpcrt4.lib

  • winhttp.lib

  • version.lib

  • ws2_32.lib

  • winmm.lib

  • comsuppw.lib

  • bcrypt.lib

  • ncrypt.lib

  • crypt32.lib

  • secur32.lib

There are some differences in static and dynamic compilation of AWS SDK C++.

For dynamic compilation is needed:

  • Add preprocessor definition USE_IMPORT_EXPORT

  • Use dynamic versions of AWS SDK static libs (aws-cpp-sdk-sqs.lib, etc.)

For static compilation is needed:

  • Doesn't use preprocessor definition USE_IMPORT_EXPORT

  • Use static versions of AWS SDK static libs (aws-cpp-sdk-sqs.lib, etc.)

Moreover for making static versions of AWS libraries there is needed to set correctly some settings for building AWS SDK C++ via CMake.

It is important to set following flags as below:

BUILD_SHARED_LIBS = OFF 

CMAKE_C_FLAGS_DEBUG = /MTd ...

CMAKE_C_FLAGS_RELEASE = /MT ...

CMAKE_C_FLAGS_RELWITHDEBINFO = /MT ...

CMAKE_CXX_FLAGS_DEBUG = /MTd ...

CMAKE_CXX_FLAGS_RELEASE = /MT ...

CMAKE_CXX_FLAGS_RELWITHDEBINFO = /MT ...

FORCE_SHARED_CRT = OFF

STATIC_LINKIG = ON

STATIC_CRT = ON

While building SDK might be an error appears from one of the Unit tests.

Error: DirectoryTreeTest.CreateDirectoryIfNotExistedTest failed

Explanation: Path components on Windows can't exceed 255(_MAX_FNAME) chars. To cover the Windows case where the path with length over 260(MAX_PATH) chars,

set one path part to be 255 characters, so dir1/dir2/dir3/[longDirName] is over 260 chars.

So that cause is that not have long file name enabled.

Fix 1: Enabling Windows Long Path (Windows 10 - 1803 build):

  • Click Window key and type gpedit.msc, then press the Enter key. This launches the Local Group Policy Editor.

  • Navigate to Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem.

  • Double click Enable NTFS long paths.

  • Select Enabled, then click OK.

Fix 2

The same thing we can do through the registry: Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem : set LongPathsEnabled to 1

Ajax data models

For integration Ajax event service into VMS the AWSSQSChannelBase class was implemented that is used as a base class for all channels which use AWS SQS service for connecting to Amazon queue service. 

AWSSQSChannelBase encapsultes all functionality for use AWS SDK. AjaxChannel class inherits from AWSSQSChannelBase and implements communication via HTTP with Ajax Endpoint.

Ajax Integration files

  1. Browse to C:\Program Files\DVMS\DVR\UDDConfigExamples

  2. Copy files UDD4Ajax.xml, AjaxDataValidator.dll, AjaxEventsDescription.xml and AmazonWSRegions.xml to the C:\Program Files\DVMS\DVR

Text Channel configuration

  1. Open Mirasys VMS System Manager

  2. Go to the VMS servers tab

  3. Open Text channels

  4. Select first free text channel slot and click Add channels

  5. Open Model dropdown menu and select UniversalDataAjaxModel

  6. Define the AWS Region

    • The field contains list of supported AWS regions (Regions, Availability Zones, and Local Zones - Amazon Relational Database Service). 

    • Each AWS Region is designed to be isolated from the other AWS Regions. This design achieves the greatest possible fault tolerance and stability.

    • Should use AWS region that geographically more suitable. Ajax’s events queue is available in Europe (Ireland) AWS infrastructure region. 

    • The code of the region is eu-west-1 (this value is used by default).

  7. AWS Events Queue name: This is the name of your Events queue. It is used for storing alerts and events of the Ajax security system in Amazon SQS.

  8. AWS access key ID: This key is used to sign the request you send to Amazon SQS

  9. AWS secret access key: Access Key ID and AWS secret access key are used for programmatic (API) access to Amazon SQS.

  10. AWS Request Timeout:Socket read timeouts for HTTP clients on Windows. Make sure the request timeout is larger than the maximum possible long poll time (AWS Wait time), that equals 20 sec, so that valid ReceiveMessage requests don't fail on long poll queues. Valid values: 1000 to 50000. Default: 25000. It is recommended not to change this value.

  11. AWS Max number of messages: The maximum number of messages to return. Amazon SQS never returns more messages than this value (however, fewer messages might be returned). Valid values: 1 to 10. Default: 1. It is strongly recommended not to change this value.

  12. AWS Wait Time(sec): This is long-poll timeout, the duration (in seconds) for which the call to the queue waits for a message to arrive in the queue before returning. If a message is available, the call returns sooner than AWS Wait time.If no messages are available and the wait time expires, the call returns successfully with an empty list of messages.
    To avoid HTTP errors, ensure that the AWS Request Timeout is longer than the WaitTimeSeconds parameter. Valid values: 1 to 20. Default: 20. It is strongly recommended not to change default value.

  13. Ajax User Role: The type of user account. It might be USER or PRO.

  14. Ajax Username: Login for the access to Ajax Endpoint.

  15. Ajax Password: Hash for access to the Ajax Endpoint.

  16. X-API-Key: This is a unique identifier that you will use to authenticate all requests to the Enterprise API.

  17. Validation: It is supported only custom validation now.

  18. Configuration file: Type UDD4Ajax.xml to the field. This is a name of xml file for showing Ajax events after the validation. At this moment exists UDD4Ajax.xml file only

  19. Custom validator: Type AjaxDataValidator.dll to the field. This is a name of library for validation Ajax events. At this moment exists AjaxDataValidator.dll library only

  20. Send the "End" event after N:  It is recommended to leave 0.

  21. Forward incoming messages to: It is recommended to leave blank.

  22. Click OK to confirm settings

Creating an alarm from Ajax event

  1. Open Mirasys VMS System Manager

  2. Go to the VMS servers tab

  3. Open Alarms

  4. Click New Alarm

  5. Enter the name of the alarm

  6. Select the View alarm in profiles

  7. Go to the Trigger tab

  8. Select Text data from the Type dropdown box

  9. Select the Ajax text channel

  10. Select the Ajax event from the list

  11. Open Actions

  12. Select alarm action from the Type dropdown box

  13. Add the to the Visible list

  14. Open Calendar

  15. Define that when the alarm is active

  16. Click OK

  17. Opening an alarm from the list shows the overview of the created alarm.

  18. Click OK to confirm alarm adding

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close