Documentation for external integrating systems

Description

Data Integration Service (called D-I-S on a daily basis) is a case flow coordination service. It handles information about the flow of cases between Origin Systems and Consumer Systems.

Origin Systems

A Origin System is the "owner" of a case. It is where the case is created, but it also holds the responsibility to update, close, or delete (if required). Every change made to the case after creation besides closing and deletion is an update.

Each Origin System has the responsibility to create a data model for the CaseDetails and therefore different Origin Systems can have different data models for CaseDetails. It is the responsibility of the Origin System to expose the endpoint for fetching CaseDetails by Consumer Systems. The endpoint should be secured by an access token from KeyCloak. The URL to the endpoint is set in the caseDetailsUri attribute on the Case object.

Consumer Systems

Consumer systems are the subscribers of cases and corresponding data delivered through DIS by the Origin Systems. To authorize a consuming system and make calls to DIS an access bearer token is needed. This token is generated using KeyCloak, with the use of clientId and clientSecret. To add a system to KeyCloak a realm manager (the Cross team) has to set up the client. Once the client has been created the clientId and clientSecret should be provided to the external integrating system. The integrating system should implement the call KeyCloak to obtain the bearer token and place this in the header when sending requests to DIS and the Origin System (for CaseDetails).

The structure of data delivered is dictated by each Origin System depending on the need an available data. Only EGDW.CaseMetadata is static and set by DIS, the content of CaseDetails and how it is mapped is a contract between the Origin System and the Consumer System. This means the Id, Created, and Updated are set by the Origin System. When a case is created and sent to DIS, DIS will save the metadata in a database (DB) and set the Updated attribute to the same value as Created. When the case, later on, is updated by the Origin System, the value in the DIS DB for metadata will be overwritten with the Updated value.

NemJournalisering (NJ)

When fully implemented, DIS will replace NemJournalisering entirely. They differ in functionality as NJ is considered a Data Warehouse System.

Notifications

When a case is created, updated, closed, or deleted by the Origin System each Consumer System is notified with a push notification, by utilizing the SignalR technology.

SignalR is Microsoft's technology which utilizes underlying web technologies like WebSocket's to achieve real-time web functionality without developers worrying about implementation details. You can read more about it here: https://learn.microsoft.com/en-us/aspnet/signalr/overview/getting-started/introduction-to-signalr

You can check out our example app here: https://github.com/EG-A-S/egdw-dis-signalr-example

You need to fill in proper ClientId  and ClientSecret for the proper environment that you want to use and change the hub URL.

A Microsoft general examples can be found here (aside from .NET in Java and JavaScript too): https://learn.microsoft.com/en-us/aspnet/core/signalr/client-features

To get notifications about cases you need to connect to caseHub. URLs:

To get notifications you'll need to have a proper bearer access token from KeyCloak. When your application is connected you can listen to these three different events:

• CaseCreatedNotificationAsync  - for create notifications.
• CaseUpdatedNotificationAsync  - for update notifications.
• CaseDeletedNotificationAsync  - for delete notificationss.

Each notification will show in a string what event (create, update, or delete) and what case (id on the case) was affected. See below code snippet as an example of when a case is created.

private async Task OnCaseCreatedNotificationReceivedAsync(string caseId)
        {
            Console.WriteLine($"Created: {caseId}");
        }

The consumer system will only get notifications about cases that your client (from the access token) has access to.

WIP