api:rest:alarm [Orbiq wiki]

Denna sida är skrivskyddad. Du kan titta på källkoden, men inte ändra den. Kontakta administratören om du anser att du bör kunna ändra sidan.
{{tag>API larmhantering}}
====== Orbiqs API för registrering av larm ======
Orbiq har ett REST-API för registrering av larm. API:et nås via endpointen
  /api/alarm
Autentisering sker via [[https://en.wikipedia.org/wiki/OAuth|Oauth2]]:
  * Token URL: /oauth2/token
  * flow: application
  * Type: Request body
  * Scope: iqalarm
====== Datamodell för payloaden ======
<code>
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)
}
</code>
====== Exempel på anrop ======
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:
<code>
curl --location 'https://test.orbiq.se/oauth2/token' \
--form 'grant_type="client_credentials"' \
--form 'scope="iqalarm"' \
--form 'client_id="myclientID"' \
--form 'client_secret="myClientSecret"'
</code>

Följande anrop registrerar en larmhändelser.
<code>
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"
    }
}'
</code>

Detta anrop kvitterar larmhändelsen.
<code>
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"
    }
}'
</code>

Och detta anrop återställer larmhändelsen.
<code>
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"
    }
}'
</code>
====== Byggnads binding ======

för att bind ett larm till en byggnad så skickar man med under metadata ett eller flera identifierande fält 
<code>objectForeignKey
objectShortName
objectLongName</code>
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

<code>
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"
    }
}'
</code>