Orbiq har ett REST-API för registrering av larm. API:et nås via endpointen

/api/alarm

Autentisering sker via Oauth2:

• Token URL: /oauth2/token
• flow: application
• Type: Request body
• Scope: iqalarm

Alarm {
	event (string): The type of event that occurred. Valid values: 'New event', 'Alarm off normal', 'Alarm normal', 'Alarm cleared', 'Acknowledge event', 'Comment'. ,
	type (string): The type of alarm. ,
	time (Alarm Times): Object containing times for the alarm ,
	subject (string),
	message (string),
	severity (string),
	state (string, optional): Required when "type" is "alarm". ,
	ackState (string, optional): Acknowledgement status ,
	ackTime (string, optional): string ,
	ackUser (string, optional),
	ackSystem (string, optional),
	clearTime (string, optional),
	clearUser (string, optional),
	clearSystem (string, optional),
	metadata (Metadata, optional),
	comment (object, optional),
	eventId (string): Local alarm event id from the alarm event source. ,
	source (Alarm Source): Information regarding the source of the alarm
}
Alarm Times {
	eventTime (string),
	receivedTime (string, optional)
}
Metadata {
	objectShortName (string, optional),
	objectLongName (string, optional),
	sourceName (string, optional),
	sourceDescription (string, optional),
	anyOtherProperty (string, optional)
}
Alarm Source {
	id (integer, optional),
	hrid (string, optional)
}

Nedan ges exempel på några anrop som ni kan testa med hjälp av en API-klient, exempelvis Postman. Ni behöver få uppgifter om client-id och client_secret för den aktuella installationen från iquest.

Följande anrop autentiserar mot API:et med hjälp av Oauth2 och tar emot en Bearer token som används för anropen:

curl --location 'https://test.orbiq.se/oauth2/token' \
--form 'grant_type="client_credentials"' \
--form 'scope="iqalarm"' \
--form 'client_id="myclientID"' \
--form 'client_secret="myClientSecret"'

Följande anrop registrerar en larmhändelser.

curl --location 'https://test.orbiq.se/api/alarm' \
--header 'Accept-Language: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer myOauth2BearerToken' \
--data-raw '{
    "event": "Alarm off normal",
    "type": "alarm",
    "time": {
        "receivedTime": "2023-04-18T09:15:58.250Z",
        "eventTime": "2023-04-18T09:15:58.250Z"
    },
    "subject": "123_subject_test",
    "message": "This is a test alert",
    "severity": "C",
    "state": "offNormal",
    "ackState": "unacked",
    "metadata": {
        "systemID": "2e28b431-7dbc-4ebc-56ef-98e04e777225",
        "alarmCategory": "test"
    },
    "eventId": "219364f7-935b-ec5a-7e5b-77d91edb4677",
    "source": {
        "hrid": "test1@test.orbiq.se"
    }
}'

Detta anrop kvitterar larmhändelsen.

curl --location 'https://test.orbiq.se/api/alarm' \
--header 'Accept-Language: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer myOauth2BearerToken' \
--data-raw '{
    "event": "Acknowledge event",
    "type": "alarm",
    "time": {
        "receivedTime": "2023-04-18T09:30:58.250Z",
        "eventTime": "2023-04-18T09:30:58.250Z"
    },
    "subject": "123_subject_test",
    "message": "This is a test alert",
    "severity": "C",
    "state": "offNormal",
    "ackState": "acked",
    "metadata": {
        "systemID": "2e28b431-7dbc-4ebc-56ef-98e04e777225",
        "alarmCategory": "test"
    },
    "eventId": "931b1f1c-0fdd-430b-b324-6c9030ae75ec",
    "source": {
        "hrid": "test1@test.orbiq.se"
    }
}'

Och detta anrop återställer larmhändelsen.

curl --location 'https://test.orbiq.se/api/alarm' \
--header 'Accept-Language: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer myOauth2BearerToken' \
--data-raw '{
    "event": "Alarm normal",
    "type": "alarm",
    "time": {
        "receivedTime": "2023-04-18T10:15:58.250Z",
        "eventTime": "2023-04-18T10:15:58.250Z"
    },
    "subject": "123_subject_test",
    "message": "This is a test alert",
    "severity": "C",
    "state": "normal",
    "ackState": "unacked",
    "metadata": {
        "systemID": "2e28b431-7dbc-4ebc-56ef-98e04e777225",
        "alarmCategory": "test"
    },
    "eventId": "3e24c9bd-7a8d-40c2-be33-48cecf7a50c7",
    "source": {
        "hrid": "test1@test.orbiq.se"
    }
}'

för att bind ett larm till en byggnad så skickar man med under metadata ett eller flera identifierande fält

objectForeignKey
objectShortName
objectLongName

Dessa motsvarar det som står i orbiq under objekts formuläret (Främmande nyckel, Kortbeteckning och Beteckning)

t.ex. skulle ett anrop för att skapa ett pågånede larm till orbiq för byggnade med kortbetecking 12345 se ut enligt följande

curl --location 'https://test.orbiq.se/api/alarm' \
--header 'Accept-Language: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer myOauth2BearerToken' \
--data-raw '{
    "event": "Alarm off normal",
    "type": "alarm",
    "time": {
        "receivedTime": "2023-04-18T09:15:58.250Z",
        "eventTime": "2023-04-18T09:15:58.250Z"
    },
    "subject": "123_subject_test",
    "message": "This is a test alert",
    "severity": "C",
    "state": "offNormal",
    "ackState": "unacked",
    "metadata": {
        "objectShortName": "12345",
        "systemID": "2e28b431-7dbc-4ebc-56ef-98e04e777225",
        "alarmCategory": "test"
    },
    "eventId": "219364f7-935b-ec5a-7e5b-77d91edb4677",
    "source": {
        "hrid": "test1@test.orbiq.se"
    }
}'