What is an HTTP Generic Event?


The qulu™ Server API provides a standard set of API calls for 3rd party systems. With the qulu Server API 3rd party systems can send qulu events using a standard API call in the form of an HTTP string - also known as the CreateEvent API call.

How to Build a CreateEvent API Call

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

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


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

address:port stands for the qulu 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 qulu

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

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 qulu. 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 qulu 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 qulu 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


Example - And Testing Your HTTP Generic Event

  1. Determine the HTTP syntax you require; an example (below) may help;                        
  2. On your 3rd Party device; enter the string under the menu [HTTP Event] as well as the qulu login ID and Password! Refer to manufacture’s manual for help.
  3. Open your qulu Client and log-in to your system.
  4. Open Alarm/Event Rules by right-clicking System, then | System Admin | General | Alarm Event Rules
  5. You will see in the event list a default rule already titled “On generic Event + Show notification” (fig 2.)
  6. Select it and click on “Advanced…” button -> you’ll see rule settings.
  7. Leave the fields “Source”, “Caption” and “Description” empty to start with. We’ll return to them later. 
  8. Open web browser on your PC, copy and paste the HTTP string into the address bar and press [Return].This emulates the 3rd Party device sending the string – should receive the alert above (fig 3.) in qulu.
  9. If working correctly; your 3rd Party device should also be able to trigger the same event – test it.
  10. If working, repeat steps 4 to 7, but complete the “Advanced…” settings for the rule – example below.

The below example shows for the rule to be activated\valid, the received HTTP string must contain “device1” within the [Source] element, i.e source=”device1” .

As an [Action] the example drives a chosen camera to a PTZ pre-set. Simply select your [Action] as required. 

To add additional 3rd party devices, simply add a new [On generic Event] rule for each, but make each unique by simply providing a new and unique device string in each case, i.e. source=”device2”, source=”device3” etc 



This completes the procedure.