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 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": {
        "systemID": "2e28b431-7dbc-4ebc-56ef-98e04e777225",
        "alarmCategory": "test"
    },
    "eventId": "219364f7-935b-ec5a-7e5b-77d91edb4677",
    "source": {
        "hrid": "test1@test.orbiq.se"
    }
}'