Analytics Event and MAD protocol

Protocols

The content of the Analytics Event and the MAD event are formatted as XML. The formats are similar, though the Analytics Event XML contains a few more fields and are more in alignment with how fields and properties are named in MIP, and make more sense when doing other integrations as well.

The method used to transmit can be either:

1. Raw XML sent to Analytics Receive port (default 9090)
2. HTTP POST formatted request, with the XML as content

XProtect Analytics & MAD Compatibility

The Milestone Alert Data (MAD) format was introduced with XProtect Analytics 2.0, and allowed the sending of analytics alerts directly to the analytics server over TCP/IP via the Generic VA interface.

With the Analytics Events feature it is possible to send MAD formatted alerts to the XProtect event server over TCP/IP in exactly the same way. Therefore, no changes are needed to current XProtect Analytics integrations in order for these to work with the XProtect event server.

However, in the XProtect event server, all received alerts are treated as analytics events, and it is therefore necessary to create an alarm definition in the XProtect Management Client before alarms can be triggered and managed in the XProtect Smart Client.

The analytics events format supports all the information of the MAD format, as well as some additional information. For developers who have not already implemented a solution using the MAD format it is recommended using the analytics events format instead.

Analytics Event XML

Analytics events will be treated just like any other internal event and can generate alarms the same way.

When sending analytics events to the XProtect event server, the analytics events should be formatted in XML, as defined by the XML Schema Definition (XSD): AnalyticsEvent.xsd.

The most important element in the analytics event format is the Message in the EventHeader, which is used to match against the alarm definition created in the management client, and determines whether or not an alarm should be triggered.

Another important element in the analytics event format is the Source in the EventHeader. For VCA (Video Content Analysis) systems, this will typically be a camera. If an alarm is triggered, the source camera will be displayed in the XProtect Smart Client when the alarm is selected. In addition, any overlay information specified in the ObjectList and RuleList will also be displayed on the camera, when the XProtect Smart Client is in playback mode. Cameras may be specified using the IP address (followed by : and port if different from 80) in the Name element of the source.

Finally, the EventHeader ID must be specified. It is recommended to pass a zero GUID, as shown in the examples, in which case a new GUID will be assigned by the XProtect event server. This ID is a unique identification of each event.

This is an example of an analytics event with the IP address of a source camera, and a single object with a bounding box:

<?xml version="1.0" encoding="utf-8"?>
<AnalyticsEvent xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:milestone-systems">
  <EventHeader>
    <ID>00000000-0000-0000-0000-000000000000</ID>
    <Timestamp>2011-01-26T15:19:39.7342498+01:00</Timestamp>
    <Message>My Analytics Event</Message>
    <Source>
      <Name>10.100.50.23</Name>
    </Source>
  </EventHeader>

  <ObjectList>
    <Object>
      <BoundingBox>
        <Top>0.2</Top>
        <Left>0.4</Left>
        <Bottom>0.9</Bottom>
        <Right>0.6</Right>
      </BoundingBox>
    </Object>
  </ObjectList>
</AnalyticsEvent>

Furthermore, specific channels on video servers may be specified by appending the (0-indexed) channel number separated by a comma. This would therefore represent “Camera 4 on 10.100.50.23”:

<Source>
  <Name>10.100.50.23,3</Name>
</Source>

Alternatively, the source can be specified precisely using the “Fully Qualified ID” of the device in the Source FQID element. This is required for non-camera sources, but may also provide a small performance gain.

In this example, the device and server ID’s are used, as well as the static “kind” of a camera:

<Source>
  <FQID>
    <ServerId>
      <Id>beef2f96-03db-4815-a33c-adcc9fcb8610</Id>
    </ServerId>
    <ObjectId>6832da9f-a09b-49c2-bbaa-d52f430b8a90</ObjectId>
    <Kind>5135ba21-f1dc-4321-806a-6ce2017343c0</Kind>
  </FQID>
</Source>

MAD Event XML

For MAD XML the Source node need to be filled for the Alarm Definition to match on it, just like the “Rule Name” is used to match on the Alarm Definition’s message, e.g. what most properly is defined on the AnalyticsEvent setup (even though it is MAD).

The Polygon and Object nodes are used by the Smart Client preview to create an overlay.

<?xml version="1.0" encoding="utf-8"?>
<Alert xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" ID="0"
  TimeStamp="2008-09-29T20:06:02.0720778+02:00"
  Name="WalkingWrongWay" xmlns="http://tempuri.org/Alert.xsd">
  <Source>
    <Server GUID="CCCF8C51-94DB-49b2-9718-0800A151D76B" Name="10.10.11.26">
      <Description>Milestone Surveillance Server</Description>
    </Server>
    <Device GUID="D23414E5-B03F-4C78-8AB9-A36D1488F9C2" Hostname="10.10.50.28"
      Name="[Axis 221] Camera 1">
      <Location Name="Exit Door" />
    </Device>
  </Source>
  <Rule Name="WalkingWrongWay" Type="Behaviour">
    <Polygon>
      <Point X="241" Y="63" />
      <Point X="65" Y="140" />
      <Point X="75" Y="284" />
      <Color R="0" G="0" B="255" A="255" />
    </Polygon>
  </Rule>
  <Object ID="42" Name="John Doe" Type="Person" Size="2.39" Count="1">
    <BoundingBox Top="194" Left="286" Bottom="429" Right="408">
      <Color R="255" G="0" B="0" A="255" />
    </BoundingBox>
    <Motion Speed="1.816466" ScreenSpeed="0.2389245" SpeedAngle="1.546658">
      <Path>
        <Point X="88" Y="288" />
        <Point X="129" Y="300" />
        <Point X="150" Y="304" />
        <Color R="0" G="255" B="0" A="255" />
      </Path>
    </Motion>
  </Object>
  <Description>Walking the wrong way at the exit door</Description>
  <Vendor Name="VCA Vendor" />
</Alert>

Protocol

XML formatted analytics event may be sent to the XProtect event server using the HTTP POST method or directly over a TCP/IP connection. A small performance gain may be achieved using HTTP. When using HTTP, the content length must be specified.

A minimal sample of an analytics event including an HTTP header is as follows:

POST / HTTP/1.1
Content-Type: text/xml
Content-Length: 426
Connection: Keep-Alive

<?xml version=”1.0” encoding=”utf-8”?>
<AnalyticsEvent xmlns:i=”http://www.w3.org/2001/XMLSchema-instance” xmlns=”urn:milestone-systems”>
  <EventHeader>
    <ID>00000000-0000-0000-0000-000000000000</ID>
    <Timestamp>2013-01-26T15:19:39.7342498+01:00</Timestamp>
    <Message>My Analytics Event</Message>
    <Source>
      <Name>10.100.50.23</Name>
    </Source>
  </EventHeader>
</AnalyticsEvent>

The XProtect event server will respond with an HTTP response regardless of the method used to send the analytics event. The HTTP response will report on the success of the processing of the received data.

The following HTTP responses may be expected:

Instead of using the XSD for validating the XML, you can submit the XML. The response will indicate what is wrong with the XML format.

It is possible to get an “HTTP/1.1 500 Internal Server Error”. This can happen briefly while the Event Server is starting. Unforeseen Event Server conditions could in theory cause this error. You can consider to re-send the event a few seconds later.

Configuration considerations

Configuring analytics events is done from the XProtect Management Client or through the Configuration API. The following screenshots offer a brief introduction to the configuration process. See the XProtect documentation for more details.

Enable the Analytics Event feature by changing the option menu: