How to Use HTTP Generic Events?

What is an HTTP Generic Event?

The Nx Witness Server API provides a standard set of API calls for 3rd party systems. With the Nx Witness Server API, 3rd party systems can send Nx Witness 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 Nx Witness Server at

  http://serveripaddress:7001/static/API.xml

How to Build a CreateEvent API Call

The CreateEvent API is an API call from the Nx Witness Server API that allows 3rd party systems and devices to send Generic Events to Nx Witness for use in the Rules Engine.

CreateEvent API calls are generated outside of Nx Witness but must follow the proper format in order to be read and acted upon by an Nx Witness Server.

Every CreateEvent API call begins with:&nbsphttp://address:port/api/createEvent?

address:port stands for the Nx Witness Server address (ip or domain) and port that 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 Nx Witness.

Timestamp

A text field that contains the date and time an event was generated accurately 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 Nx Witness. 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 Nx Witness 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:

1. Through Nx Witness: In the Nx Witness Desktop users can find the CameraID in the Camera Settings Dialog under the Advanced Tab.
2. Through Web Admin: Navigate to a browser and input the URL below, authenticate, and then use CTRL+F to search all text for “ID”.

   http://<serverIPaddress>:<port>/ec2/getCamerasEx?extraFormatting