What is an HTTP Generic Event?
The DW Spectrum™ Server API provides a standard set of API calls for 3rd party systems. With the DW Spectrum Server API 3rd party systems can send DW Spectrum events using a standard API call in the form of an HTTP string - also known as the CreateEvent API call.
- The full Server API can be accessed on any installed DW Spectrum Server at http://serveripaddress:7001/static/API.xml.
- To access the Server API right now on our HQ Demo System users would enter http://47.181.14.73:7001/static/api.xml - and login with username:demo, password:demo1234.
- This document describes sending Generic Events to DW Spectrum on a local system. It is also possible to route the information thru DW Cloud. For more information please see How to make API requests to the cloud-connected system through the internet?
How to Build a CreateEvent API Call
The CreateEvent API is an API call from the DW Spectrum Server API that allows 3rd party systems and devices to send Generic Events to DW Spectrum for use in the Rules Engine.
CreateEvent API calls are generated outside of DW Spectrum but must follow the proper format in order to be read and acted upon by an DW Spectrum Server.
Every CreateEvent API call begins with: http://address:port/api/createEvent?
address:port stands for the DW Spectrum Server address(ip or domain) and port you are planning on sending your request to.
---------------------------
Create Event Modifiers
To complete a CreateEvent API call developers can add any of the following modifiers, which allow developers to provide additional information for use in searching Events & Rules or even triggering actions (e.g. start recording) in DW Spectrum.
---------------------------
Timestamp
A text field that contains the date and time an event was generated accurate to the millisecond.
- Required: No
- Format: YYYY-MM-DDTHH:MM:SS
- Use: The Timestamp is used to synchronize events between 3rd party systems and devices and DW Spectrum. If no timestamp is used the event will be captured and timestamped according to when it was received by the Server. The Timestamp is useful because it removes any potential problems surrounding latency.
Example:
http://address:port/api/createEvent?timestamp=YYYY-MM-HHTHH:MM:SS
---------------------------
Source
A text field that contains the name of the device or system creating an event.
- Required: No
- Format: Text
- Use: The Source name is used for creating rules. In a System with default Generic Event rules it will also be displayed as the name of the Event in the Notifications Panel.
Example:
http://address:port/api/createEvent?timestamp=YYYY-MM-HHTHH:MM:SS&source=sourcename
---------------------------
Caption
A text field that contains a short description of an event.
- Required: No
- Format: Text
- Use: The Caption is used for creating rules. If, for example, you wanted to integrate a 3rd party system like a Point-of-Sale the Caption would be an ideal place to put the transaction data from the POS system.
Example:
http://address:port/api/createEvent?timestamp=YYYY-MM-HHTHH:MM:SS&source=sourcename&caption=shorttextcaption
---------------------------
Description
A text field that contains a long description of an event.
- Required: No
- Format: Text
- Use: The Description is also useful when creating rules. If, for example, you wanted to integrate a 3rd party system generating a long string of data - like a customs officer filing a report for a truck inspection at the border - Description would be the right place to put that data when sending an Event to DW Spectrum for use in creating a Bookmark after each successful inspection.
Example:
http://address:port/api/createEvent?timestamp=YYYY-MM-HHTHH:MM:SS&source=sourcename&caption=shorttextcaption&description=textdescriptionoftheevent
---------------------------
Metadata
Additional information associated with an event, in the form of a JSON object.
- Required: No
- Format: JSON Object
- Use: Metadata allows developers to create events related to specific camera(s) using the “cameraRefs” API call. What this means is that when a notification is received and is displayed in the Notifications panel (default System rule for HTTP Generic Events) it will display one or more video streams when clicked on. Also if email generation is triggered by the event snapshots from all mentioned in "cameraRefs" parameter will be added to the message.
Example:
http://address:port/api/createEvent?timestamp=YYYY-MM-HHTHH:MM:SS&source=sourcename&caption=shorttextcaption&description=textdescriptionoftheevent&metadata={"cameraRefs":["cameraIDforcamera1","cameraIDforcamera2"]}
Methods of Finding the CameraIDs:
- The Easy Way: In the DW Spectrum Desktop Client users can find the CameraID in the Camera Settings Dialog under the Advanced Tab.
- The Hard Way: Navigate to a browser and input the following URL, authenticate, and then use CTRL+F to search all text for “ID”. http://<serverIPaddress>:<port>/ec2/getCamerasEx?extraFormatting
Quick API Generator
DW Spectrum provides a fancy tool to generate your URL within seconds.
To access the API Generator right now on our HQ Demo System users would enter http://47.181.14.73:7001/static/index.html#/developers/events - and login with username:demo, password:demo1234.
