Events
The Altinn Events component is an a ASP.NET Core MVC Application exposing REST-API to Altinn Apps and other Altinn Platform components.
In addition it contains serveral Azure Functions to support push of events.
See event capabilities for functional description of the platforms event capabilities.
Altinn Event Architecture
The solution is available at https://platform.altinn.cloud/events/api/v1.
API Structure
The API’s is structured so the URLs are filtered queries into the events storage.
Instances events for Org
Endpoint
GET path: platform.altinn.no/events/api/v1/app/{org}/{appName}
Usage
This will be used by application owners to identify changes on instances for their applications.
Authorization
We will use scopes from Maskinporten to authorize access. In this way, it should also be possible for an org to delegate access to events for a given org/app.
The full detail for this API is described in this issue.
Request
The following url parameters and http headers have been defined. Person is given as a http header because of security.
Parameter | Type | Description |
---|---|---|
org | string | Required: the org owning the application |
appName | string | Required: the application related to the event |
after | string | Required**: the id of the last event processed by the client |
from | datetime | Required**: The time (UTC) to search from |
to | datetime | Optional: The time (UTC) to search up until |
party | string | Optional: the partyId |
type | List<string> | Optional: a list of event types |
unit | string | Optional: the organisation number nine digits for reportee |
person | string (http header) | Optional: the f or d number of the person |
size | int | Optional: upper limit for number of returned events |
* Needs to give one identifcator of the subject, unit,person or party parammeter.
** After or from is required
*** Source allows for escaping a single character _
or an undefined number of characters %
Response
Response includes a next header that can be used to get the events following the last event returned by the response. Query parameter after is inserted or replaced and holds the id of the last event returned in the reponse.
https://platform.tt02.altinn.no/events/api/v1/app/ttd/apps-test?after=5beae524-0b3d-4e3b-bf40-450575eaf5d6&from=2020-10-01 11:35:00
Response body includes a list of cloud events on the form
[
{
"id": "8c99c887-3861-4c2a-9ac9-178a20b1ee70",
"source": "https://nav.apps.altinn.no/nav/app/instances/1234324/6fb3f738-6800-4f29-9f3e-1c66862656cd",
"specversion": "1.x-wip",
"type": "instance.created",
"subject": "party/567890",
"time": "2020-10-13T15:46:02.557971Z",
"alternativesubject": "/person/01038712345",
"data": "data field"
},
{
"id": "5beae524-0b3d-4e3b-bf40-450575eaf5d6",
"source": "https://nav.apps.altinn.no/nav/app/instances/1234324/6fb3f738-6800-4f29-9f3e-1c66862656cd",
"specversion": "1.x-wip",
"type": "instance.deleted",
"subject": "party/567890",
"time": "2020-10-14T10:33:33.022379Z",
"alternativesubject": "/person/01038712345",
"data": "data field"
}
]
Events for a given party
A very common scenario is that a party needs to know about events for the party itself or other party that party has a relationship for (client, child unit++).
Endpoint
GET platform.altinn.no/events/api/v1/app/party
Usage
This is used by end users to see events for a given party. This will list all changes for a given party, identified with a partyId, person number or organisation number.
Authorization
Access to events needs to be authorized. To be able to read events, you need to have the read right for the given app for the given party.
The topic and subject would be used to identify the correct XACML-policy to use.
The operation would be read and the proccess task will be set to null
.
This way there would be no need to verify the current state of an instance.
The full detail for this API is described in this issue.
Request
The following url parameters and http headers has been defined. Person is given as a http header because of security.
Parameter | Type | Description |
---|---|---|
after | string | Required**: the id of the last event processed by the client |
from | datetime | Required**: The time (UTC) to search from |
to | datetime | Optional: The time (UTC) to search up until |
party | string | Required* the partyId |
type | List<string> | Optional: a list of event types |
source | List<string> (regex allowed)*** | Optional: a list of strings to match the event source |
unit | string | Required* the organisation number nine digits |
person | string (http header) | Required* the f or d number of the person |
size | int | Optional: upper limit for number of returned events |
* Needs to give one identifcator of the subject, unit,person or party parammeter. |
** After or from is required
*** Source allows for escaping a single character _
or an undefined number of characters %
Response
Response includes a next header that can be used to get the events following the last event returned by the response. Query parameter after is inserted or replaced and holds the id of the last event returned in the reponse.
https://platform.tt02.altinn.no/events/api/v1/app/party?after=5beae524-0b3d-4e3b-bf40-450575eaf5d6&from=2020-10-01 11:35:00
We have this example
[{
"source": "https://skd.apps.altinn.no/skd/skattemelding/234234422/2acb1253-07b3-4463-9ff5-60dc82fd59f8",
"subject": "party/234234422",
"type": "instance.process.completed",
"time": "2020-02-20T09:06:50.3736712Z",
"id": "91f2388f-bd8c-4647-8684-fd9f68af5b14",
"ssid":"orgno:974760673"
}]
To be able to read this event, the authenticated party is required to have the rights for SKD/Skattmelding for the party 234234422. This is something it gets throug roles for that specific application.
Adding events
Endpoint
POST {platformurl}/events/api/v1/app
This returns the created ID for the event.
Usage
This is used by the application to publish app events. Events are submitted as CloudEvents.
A CloudEvent consists of a number of attributes, such as the ID of the event and the type of the event.
The following attributes is used by the Events component.
Attribute Name | Type | Note |
---|---|---|
id | String | Optional. The ID of the event. A CloudEvent is uniquely identified with its source and id. The Events component will assign the id of the event. |
source | String (URI-reference) | Required. The source of the event. |
specversion | String | Required. The version of CloudEvents Specification the Cloud Event uses. |
type | String | Required. The type of the event. |
subject | String | Required. The subject of the event. |
time | String (Timestamp) | Optional. The timestamp when the event happens. The Events component will set this. |
alternativesubject | String | Optional. The alternative subject of the event. |
We have this example
[{
"specversion": "1.0",
"type": "instance.created",
"source": "skd/skattemelding/234234422/2acb1253-07b3-4463-9ff5-60dc82fd59f8",
"id": "91f2388f-bd8c-4647-8684-fd9f68af5b14",
"time": "2020-02-20T08:00:06.4014168Z",
"subject": "party/234234422",
"alternativesubject": "party/131555662"
}]
Adding Subscription
Endpoint
POST {platformurl}/events/api/v1/subscriptions/
This returns the created subscription with IDs
Usage
This is used by the consumer to add a subscription.
The consumer needs to ba an org authenticated with maskinporten or a end user autenticated with ID-porten
We have this example that adds a subscription for all events for the app ttd/apps-test to be pushed to a Slack webhook
{
"endPoint": "https://hooks.slack.com/services/TSRSASBVNF3/ADRRSDSSSAahttsasdfasFO3w83456ss",
"sourceFilter": "https://ttd.apps.at21.altinn.cloud/ttd/apps-test"
}
API Documentation
The full detail for this API is described here.
Push Functions
A important part of the Events components are four different Azure Functions that is responsible for the following
- Registration function: Pulls incomming events from queue for further processing
- Inbound Function: Sends every event to subscription matching and authorization
- Outbound Function: Pushes events to subscription endpoints
- Subscription Validation Function
See more details in the construction components for Events