Iris has an api endpoint which supports a json post containing information you would like to create events for.


To use it you will need an Iris build newer than 1.2.2(1676) or 1.3.0(363) as well as be able to craft a json post with either a single object, or an list/array of objects, containing the following values:


device - This will be the hostname of the device the event is for

condition - Some condition value for the event

source - A source name/string where the event originated from

severity - The severity of the event as an integer, severity options will be listed below

timestamp - A Unix timestamp integer

ident - A unique string which is used to identify and deduplicate the particular event

status - The status of the event, status options will also be listed below


Severity options:

1 = Down
2 = Critical
3 = Error
4 = Warning
5 = Info
6 = Debug



Status options:

ALARM
CLEAR
LOG


An example of an json object would look like below:

{
"condition": "DOWN",
"device": "my-device.irisns.com",
"ident": "my-device.irisns.comCUSTOMEVENTupdown",
"msg": "my-device.irisns.com is down",
"severity": 1,
"source": "CUSTOMEVENT",
"status": "ALARM",
"timestamp": 1609757544
}

This object was for a device called "my-iris-server.irisns.com" and the event was to report that the device is down. This would create an alarm event, to clear the event you would send the following:

{
"condition": "CLEAR",
"device": "my-device.irisns.com",
"ident": "my-device.irisns.comCUSTOMEVENTupdown",
"msg": "my-device.irisns.com is up",
"severity": 5,
"source": "CUSTOMEVENT",
"status": "CLEAR",
"timestamp": 1609757544
}

Note how the severity and status changed in accordance to the change of state and how the ident remained the same as the previous alarm. This is to allow the system to match the events up, and update it's state. If the ident was different it would create a seperate event instead of updating the previous one.


Next you will need to send the json object/s in a post to the iris server, the URL would contain your servers FQDN but an example would look like this:

https://my-iris-dce.irisns.com/iris/api2/api/hooks/events


If your message is successuly delivered, the API will return a list of the events it received along with a status boolean 'success'

{
"success": true,
"data": [
{
"condition": "CLEAR",
"device": "my-device.irisns.com",
"ident": "my-device.irisns.comCUSTOMEVENTupdown",
"msg": "my-device.irisns.com is up",
"severity": 5,
"source": "CUSTOMEVENT",
"status": "CLEAR",
"timestamp": 1609757544
}
]
}





Another example of a json object list would look like below:

[
{
"condition": "DOWN",
"device": "my-device.irisns.com",
"ident": "my-device.irisns.comCUSTOMEVENTupdown",
"msg": "my-device.irisns.com is down",
"severity": 1,
"source": "CUSTOMEVENT",
"status": "ALARM",
"timestamp": 1609757544
},
{
"condition": "CRITICAL",
"device": "my-other-device.irisns.com",
"ident": "my-other-device.irisns.comCUSTOMEVENTcpuUsage",
"msg": "my-other-device.irisns.com cpu usage is high",
"severity": 2,
"source": "CUSTOMEVENT",
"status": "ALARM",
"timestamp": 1609757544
}
]