Integrating with Immix
Sending Alarms to Immix
Alarms are sent to Immix using SMTP, using the parameters for the SMTP server as described in the Immix settings (on the account or on the camera level).
The email will contain the video clip with the detection (i.e. with alarm zones and bounding box for detection drawn into the video) or the frame in which the detection was made (also with alarm zones and bounding box) in case no video was produced.
The body of the email sent will contain an XML document on the form:
<Alarm> <VersionInfo>1</VersionInfo> <Input1>1</Input1> <EventType>MotionDetected</EventType> <ExtraText>MotionDetection: true</ExtraText> <DateTime>2025-02-26T16:27:54Z</DateTime> <Location></Location> <URL></URL> </Alarm>
The contents is as follows:
Parameter | Value |
|---|---|
VersionInfo | Always equal to 1 |
Input1 | This is the calculated Immix Alarm number (see section on Server Id, Alarm Number and Event Type Id below) |
EventType | Currently always set to MotionDetection in the alarm filter. This must be one of the standardized event types in Immix, see their documentation. |
ExtraText | Currently always set to MotionDetection: true (for true alarms) or MotionDetection: false (for false alarms). |
DateTime | Currently always set to the time the alarm was received by the Alarm Filter (in UTC). By default formatted to yyyy-MM-ddTHH:mm:ssZ but can be specified by the user through the Immix settings. |
URL | Always empty |
There is also a Location tag which can be set in the XML but this can currently not be configured in the Alarm Filter.
Note that the default value for the date time format is now in ISO 8601, but always using UTC. The Immix recipient tested with so far (Immix TestMyDevice ) is able to convert the UTC timestamps to server local time.
Setting for Immix integration
The following settings are configurable through the Backend:
|
|
|---|---|
hostname | Hostname of Immix SMTP server. |
port | Immix SMTP server port number. Default is 25. |
username | The username of the SMTP server credentials (omit to disable credentials). |
password | The password of the SMTP server credentials (omit to disable credentials). |
requireStartTls | Set to true to require the use of TLS encryption (using STARTTLS command). |
acceptSystemAlarms | [Ignored at the moment] |
fromEmailAddress | The From address of the email sent. |
emailDomain | The domain part of the email to send (e.g. immix.com). |
alarmNumber | (nullable integer) This is the Alarm Number, can be any integer., |
serverId | The Server ID of the site (as configured in Immix) which is also the username part of the email to send (e.g. S211.A1). |
includeBoundingBoxes | If true, the bounding box (if available) will be drawn onto the video clip. |
emailSubject | Subject to include in the email. Default subject uses the Immix Standard Alarm Type of the actual alarm, e.g. MotionDetected. |
dateTimeFormat | Format of the timestamp sent to Immix. If not set then the format yyyy-MM-ddTHH:mm:ssZ is used. |
Server Id, Alarm Number and Event Type Id
The Immix integration require at least a server id and an alarm number. The Alarm Filter will use these settings from, in order of priority:
- Outgoing Id of the Camera. If the outgoing Id is set an is on the format ‘Sxx.Axx’ then the ServerId and Alarm Number will be taken from here. Examples:
- S4445.A4 => ServerId = S4445, Alarm Number=4
- S4445A7 => ServerId = S4445, Alarm Number=7
- S212=> ServerId = S212, Alarm Number will be taken from the Alarm Notifier settings.
- Incoming Id of the Camera. If the outgoing Id is not set on the camera, then the incoming id will be parsed and if this is on the format ‘Sxx-Axx’, ‘Sxx.Axx’ or ‘SxxAxx’ then the ServerId and Alarm Number will be taken from here. Examples:
- [email protected] => ServerId = S213 and Alarm Number = 5
- [email protected] => ServerId = 213, Alarm Number will be taken from the Alarm Notifier settings.
- The Immix Alarm Notifier used. If the outgoing Id is not set or does not follow the expected format, and the incoming Id does not follow the expected format then both will be taken from the settings.
More details can be found in the documentation: https://docs.irisity.com/alarm-filtering-beta/api-documentation#4a6m6
Notice: the Event Type Id is never used in the Alarm Filter.
Destination Email
- The emails will always be sent to ‘[email protected]’, whereas the Alarm Number will be included in the XML body of the email (the Input1 tag).
Retry Policy
The Alarm Filter uses a retry policy for sending alarms to Immix as follows:
- If the server responds with a 5XX status code then no retry is used.
- If there is a timeout or other status code responded from the server then the system will try again to send the alarm. Up to five attempts is being done, with five seconds sleep time between each attempt.
Receiving Immix Alarms
The alarm filter is also able to receive emails with an Immix XML request body (assuming that the email does in fact also contain an attached video or image).
The Alarm Filter will parse the timestamp of the received Immix request and set this as the ReceivedAt timestamp. The ExtraText and URL are also read and saved but are currently not used anywhere.