# ONVIF Generic Events

#### Custom ONVIF Events

#### Introduction

You can create custom rules based on ONVIF camera-generated events inside Macula Console *Events & Actions*. To do so, you need:

1. ONVIF compatible camera connected via ONVIF driver to the Macula,
2. Understanding of the camera events,
3. Basic knowledge of the ONVIF standard XML responses generated by your cameras.

Although ONVIF is a set of rules that standardizes video monitoring hardware and software - the range of available options is extensive, and different cameras may have very different capabilities. In the context of this manual, we will focus on integrating this wide range of varying camera capabilities into the Macula and fully utilize your camera potential.

The scheme below represents the cameras sending Event data to the Macula server.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FQWU0U8GSn506a4MxEBic%2Fimage.png?alt=media&#x26;token=fa6837c6-11d8-49b3-8161-2f18dc5ea4ff" alt=""><figcaption></figcaption></figure>

This event data is sent via RTSP and HTTP in XML format and adheres to the ONVIF-defined standard. Both streams may represent the same or different events, and you must invest your attention to get out the most from your setup.

#### User Defined Events

To begin with the ONVIF-based custom event creation, you must add a camera via the Generic ONVIF driver. You can find how to add your devices in a corresponding part of this manual.

1. After adding a device, find the *Channels* inside *Macula Console -> Configuration* sub-section.
2. Find the corresponding channel and open it in a pop-up window by double-clicking on its name or selecting it and pressing the *Edit* button on the top of the channel list subsection.
3. Find the *User defined events* in the pop-up window at the bottom of the right subsection.

You will see the empty subsection with three buttons on the top. *+New* drop-down button, grayed-out *Edit* button, and *Notification messages* button. You can create a New generic event by clicking the *+New* or *Notification Messages* buttons. Both options will bring the new *Messages* pop-up window with the list of received notification messages in XML format. Received data represented in a table-like form with columns:

* **Time** - Received notification server timestamp (MM/DD/YYYY HH:MM:SS)
* **Source:**
  * **Notification service -** data stream received via HTTP
  * **MetaStream -** data stream received via RTSP
* **Message** - Received data in XML format. The Message column is updated in real-time as the data is received.
* **Matches** - if you have already created a generic event filter, you will see an indication for the events with exact matches for that existing filter.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FQ27yUTvSdA3e9wWBM7ah%2Fimage.png?alt=media&#x26;token=64a3f818-5768-4465-8883-e3dddb7e72e1" alt=""><figcaption></figcaption></figure>

Locate the event you want to use as the prototype for the filter, click on it, and then click on the *+New* button on the bottom-left part of the pop-up window. You may find the same event inside both - *Notification service* and *MetaStream* data. For such cases, our recommendation is to use *MetaStream*. This stream is sent together with the video stream, so it is easier to notice any instability the third-party factors may cause.

{% hint style="info" %}
You can find your camera capabilities in the manufacturer's manual or the Conformant Products - ONVIF webpage.
{% endhint %}

This will bring the Generic event pop-up window.

You will see the following fields inside the Details tab:

* **Type** - Event type (in this case - *GenericEvent*), non-editable.
* **Message source** - *Notification service/MetaStream*, non-editable
* **Title** - the only field that the user should fill in. The display name of the created event. Editable.
* **Id** - Event identifier. The field will be completed automatically after the event is saved. You can identify the event inside log files by this ID.
* **Enable checkbox** - enable event processing. Uncheck it to stop processing the event.

The only field you should fill inside the *Details* subsection is the *Title* field - add a meaningful name that will allow you to recognize this event inside the *Events & Actions Configurator*.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FMov9O5pHaWegdn0gxvvN%2Fimage.png?alt=media&#x26;token=4724d429-bb1a-4809-b585-4c74d9a4e9b9" alt=""><figcaption></figcaption></figure>

#### VCA event mapping

The next step is to map data. Inside the Item subsection, locate the *Mapping*; this will bring the *Mapping* options. You will see three subsections:

* **Notifications message** - the most-right subsection of the *Mapping* section. Provide a detailed view of the selected message.
* **Items** - represents the mapped portions of the *Notification message*. You may create multiple items - only exact matches will be processed (similar to the && conditional operation).
* **Condition** - the left subsection of the *Mapping* section. This subsection allows adjustments to the *Items* created in the *Items* subsection. You will find the following interface elements:
  * **Name** field - You can edit this to make the Items subsection more readable. Provide a meaningful name for the *Condition* Item.
  * **Select node** button - which will bring a pop-up screen with the notification message. Use it if you want to change the part of the message your item is based on.
  * **Evaluate** button - Evaluate if the created *Item* matches the current condition. Use it if you manually adjusted *XPath* or *Text* fields to avoid errors. Values: "true" - if the Item condition matches the Notification message; "false" - if *XPath* value or *Text* does not have an exact match.
  * **XPath** input field - represents the path to the *Item* conditional value in the context of the *Notification message* tree; may contain variables.
  * **Text** input field - represents the value that must match to meet the event's trigger condition.
  * **Regular Expression** checkbox - mark it if REGEX is used for conditioning.
  * **Case sensitive** checkbox - by default, condition matching is registry case-independent. Mark this checkbox only if you need registry case-dependent conditioning.
  * **Save/Apply changes** button - Save changes before switching to the next *Item* or confirming event with the *OK* button at the bottom-right corner of the *Mappings* subsection.
  * **Cancel button** - Cancel current changes made to the selected Item.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2Fyqt1oUG1aawOsYIsHRdX%2Fimage.png?alt=media&#x26;token=f02032d5-08ac-458d-9db3-6ff508891834" alt=""><figcaption></figcaption></figure>

#### Blurry mainstream Custom VCA Event scenario

At first glance, Generic events may seem complicated, but they provide an unprecedented level of elasticity if needed or allow the creation of simple event triggers from otherwise incompatible devices. The example below will create a generic event based on the ONVIF camera's mainstream blurriness.

1. Ensure the camera is connected via the ONVIF driver and the Camera analytics is up and running.
2. Go to *Configuration -> Channels ->* 'Your Channel' and double-click on it.
3. At the bottom of the right section, find *User defined events*, select it, then on the top of the right subsection, click the *+New* button -> *New generic event*.
4. Locate relevant event. In the example case, this will be an event sent via Metastream containing information on the image quality. Click on the *+New* button at the *Messages* window's bottom-left side.
5. In the provided example  the event is named  "HikiEntrance\_tooBlurry." Click on the *Mapping*. You will see already created *Item* based on the event topic.
6. For Example, the camera has both mainstream and substream, and the mainstream is found under the *Message/Source/VideoSource\_1*. To evaluate only mainstream, you need to create one more *Item*.
7. At the *Notification Message* subsection, locate *Message/Source* and click on the node; then, in the *Items* subsection (the one in the middle), click the *+New condition* button. You can change the *Item name* to something more meaningful, like in the provided example, "MainStream," and confirm the adjustment with the *Create* button..
8. Now, the system knows "where to look." All that's left is to tell the system what it must look for. Create one more *Item* from the *Message/Data* node. In the provided example, you need to evaluate if the image is blurry, so you are looking for the value - "true." Select the Data node, Click the *+New condition* button, rename the *Item* as "TooBlurry," and confirm it with the *Create* button.
9. Confirm Generic Event with the *OK* button, then confirm it again with the *Apply* button under the *User defined events* subsection.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2F64psnT05vkUPUN3fOLNO%2Fimage.png?alt=media&#x26;token=7f82e0c6-3c0a-45c1-a895-e9ebefd37457" alt=""><figcaption></figcaption></figure>

From now on, you are ready to build *Actions* based on the blurriness of the camera mainstream. To do so:

1. Go to the *Macula Console -> Events & Actions -> Events*
2. At the top-left part of the *Events* subsection, find the *+New event* button and click it.
3. Find the *VCA event* (Stands for Video Camera Analytics) from the pop-up window and confirm with the *OK* button.
4. Add the *Event Title*, which will be displayed inside the configurator. Name it "blurry entrance cam."
5. Click the *Change* button on the right side from the *Source* field and select the camera you used to create that generic event.
6. To bring a custom event to its full potential, you must add the *VCA rule*. Click the *Change* button and find your generic event name in the pop-up window. It will likely be at the bottom of the list. Confirm your selection with the OK button, then click the *Apply* and the OK buttons to save your event.
7. Go to the *Rules* subsection and open the configurator. The goal is to log this event to the server, generate an alert, and pop up the channel inside the Macula Monitor.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FMzVv7N3KsQcveTdjTr1M%2Fimage.png?alt=media&#x26;token=dfc05ab1-a3f9-4cd6-89c9-f0a8f33e3488" alt=""><figcaption></figcaption></figure>

That's it. All the Actions are now available for your event. This way, very complicated scenarios might be created, starting with basic notifications for the simple analytics event and up to very specific conditioning for the VCA value for the particular case.

#### Import/export custom events

Once the event is mapped, it is possible to export it. To do so, go to:

1. *Configuration -> Channels ->* Your channel *-> User defined events*
2. Select your *Event* and click the *Export* button at the top of the window.

<figure><img src="https://412599993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeNXnJx0OpvxnmpWqOBNm%2Fuploads%2FWJJFcOopvBAvcMqss2Vz%2Fimage.png?alt=media&#x26;token=af64384a-57fd-4542-be7d-9bdf797bda36" alt=""><figcaption></figcaption></figure>

To import event, go to:

1. *Configuration -> Channels ->* Your channel *-> User defined events*
2. Select your *Event* and click the *Import* button at the top of the window.

find saved json file and confirm it with the *Ok* button.

{% hint style="danger" %}
Although it is possible to import any custom event to any ONVIF compatible camera, it will be working only with the cameras that sends exactly the same notification messages.
{% endhint %}