User Event: HTTP Generic Event

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: http://address:port/api/createEvent?

address:port stands for the Nx Witness 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 Nx Witness.

---------------------------

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 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. The Easy Way: In the Nx Witness Desktop Client users can find the CameraID in the Camera Settings Dialog under the Advanced Tab.
2. 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

---------------------------

Demo Video

Here is a quick example of how the HTTP CreateEvent API can be used to integrate with a 3rd party video analytics system from VCA Technology in the UK.

Questions

If you have any questions related to this topic or you want to share your experience with other community members or our team, please visit and engage in our support community or reach out to your local reseller.