Generic Events are a powerful way to integrate 3rd party systems with your VMS. By sending a simple API request, external systems (like Access Control, IoT sensors, or custom scripts) can trigger actions within the VMS Rules Engine.

What is an Generic Event?

A Generic Event is an HTTP POST request sent to the VMS API. When the VMS receives this request, it processes it through the Rules Engine, allowing you to automate responses such as:

• Starting high-quality recording on specific cameras.

• Displaying a desktop notification to operators.

• Triggering an alarm output or PTZ preset.

• Sending an email or mobile push notification.

Note: Generic Events can also be sent from the VMS to itself using the "Do HTTP Request" action, enabling complex internal logic.

API Documentation & Endpoints

To explore the full range of capabilities, you can access the interactive documentation directly on your server:

• Full REST API Documentation: https://<serverIp>:7001/#/api-tool/main

• Generic Event Specifics: https://<serverIp>:7001/#/api-tool/rest-v4-events-generic-post

How to Build a Generic Event request API Call

Every Generic Event API request call is a POST request that begins with:

https://<serverIp>:7001/rest/v4/events/generic

Request Body (JSON)

The body of the request defines the context of the event. Here is a standard template:

{
    "timestamp": "2024-06-16T16:02:41Z",
    "state": "instant",
    "source": "<source>",
    "caption": "<caption>",
    "description": "<description>",
    "deviceIds": [
        "<deviceId1>",
        "<deviceId2>"
    ]
}

NOTE: All values between the <> should be replaced by the actual values and are casesensitive

Event Parameters & Modifiers

You can customize the following fields to provide better filtering options within the VMS Rules Engine:

Timestamp

Event date and time, as a string containing time in milliseconds since epoch, or a local time formatted like "YYYY-MM-DDTHH:mm:ss.zzz" - the format is auto-detected. If "timestamp" is absent or "now", the current Server date and time is used.

State

Generic Events can be used either with "prolonged" actions like "Device recording", or instant actions like "Send email". This parameter should be specified in case "prolonged" actions are going to be used with Generic Events. The Event is considered instant in case of parameter absence.

The following values can be used: 

• started
• stopped
• instant

Source

Name of the Device which has triggered the Event. It can be used in a filter in VMS Rules to assign different actions to different Devices. Also, the user could see this name in the notification panel.

Caption

Short Event description. It can be used in a filter in VMS Rules to assign actions depending on this text.

Description

Long Event description. It can be used as a filter in VMS Rules to assign actions depending on this text.

Device IDs

Specifies the list of Devices which are linked to the Event (e.g. the Event will appear on their timelines), in the form of a list of Device ids (can be obtained from "id" field via /rest/v4/devices).

How to find the Device IDs

Method 1: Desktop Client (Manual)

1. Right-click on a camera and select Camera Settings.

2. Navigate to the General tab.

3. Click the More Info arrow to reveal the Camera ID.

4. Click the ID to copy it to your clipboard.
    

Method 2: REST API (Programmatic)

You can retrieve a list of all devices and their IDs by visiting:

https://<serverIp>:7001/rest/v4/devices?_with=id,url,name

Setting Up the Rule in the VMS

Once you have successfully sent a test API call, you must configure the VMS to react to it:

1. Open Site Administration > Event Rules.

2. Click Add Rule.

3. Set the WHEN EVENT to Generic Event.

4. In the Source, and/or Caption, and/or Description fields, enter the text you sent in your API call to filter for this specific event.

5. Select the desired DO ACTION (e.g., Show Desktop Notification or Camera Recording).

6. Click Apply.