Migration and Seeding Tool

The migration and seeding tool can be used to migrate the EWA database, seed locations and configure the EWA system.

Before use

The tool needs a connection string to the MSSQL database it should migrate/insert data to.

Up to version 21.10 this connection string must be set inside the Bliksund.EWA.MigrationTool.exe.config file. In releases after 21.10 the connection string must be set inside the appsettings.json file.

Usage

The tool can be invoked via the command line with command line options or it can be run interactively by double-clicking the Bliksund.EWA.MigrationTool.exe file in file explorer.

Command line options

Option	Description
--help	Display help text for the tool.
-m, --migrate	Migrates the database to the newest version
-s, --seed	Seeds the json files from the Data folder into the database
-v, --validate	Validates that the Data folder contains the required JSON files for seeding
--localad	Use local active directory for authentication and authorization in the system.
---	LocalAD should not be used at the same time as --openid
--openid	Use OpenID Connect for authentication and authorization in the system. Configuration should be set in file "OpenIdConnectConfiguration.json"
---	OpenID should not be used at the same time as --localad
--role-access-mapping	Update the role to access right mapping that the system should use for authorization. Configuration should be set in file "RoleToAccessMapping.json"
--pdf-configuration	Update or inserts the pdf configuration settings. Configuration should be set in file "PdfConfiguration.json"
--department-id-mapping	Inserts or updates the Department ID mapping configuration which is used for OpenIdConnect with departments as single claim and rolepicker display values. Configuration should be set in file "DepartmentIdMapping.json"
--run-converter	Runs a specific converter. The converter name should be provided after this argument.

Examples

To re-run data conversions, or resume a conversion that was interrupted, the --run-converter option can be used. The name of the converter to run should be provided after the option.

.\Bliksund.EWA.MigrationTool.exe --run-converter CreateRecordConfMissionTypeTable

Interactive use

When using the tool interactively, the following menu will be displayed in a console window after startup:

Menu Item	Description
List	Enter menu to list pending, deployed and all migrations for the current version
Migrate	Migrate the database up to the current version
Seed	Seed data from the JSON files in Data folder to the database
Validate Data	Validates that the Data folder contains the required JSON files for seeding
System Configuration	Opens the system configuration menu
Help	Display help text
Exit	Exits the program

List menu

Menu Item	Description
Pending	List pending migrations
Deployed	List deployed migrations
All	List all migrations

System Configuration menu

Menu Item	Description
Authentication and Authorization	Configure which authentication and authorization method the system should use
Role to Access Rights Mapping	Insert or update the role to access rights mapping configuration that the system should use for authorization
Seed PDF configuration	Insert or update the PDF configuration object that the system should use when generating PDFs
Department ID Mapping	Inserts or updates the Department ID mapping configuration which is used for OpenIdConnect with departments as single claim and rolepicker display values

Configuration files

OpenIdConnectConfiguration.json

The OpenIdConnectConfiguration file consists of two objects with the same internal structure; InsightConfiguration and ClientConfiguration.

The InsightConfiguration object is used by the Insight component, while the ClientConfiguration object is used by the ClientAPI component.

Property	Type	IsRequired	Default value	Description
ClientId	string	Yes		The "client_id" part of the authentication flow
ClientSecret	string	Yes		The "client_secret" part of the authentication flow
Authority	string	Yes		Url to the Authority that should be used when making OpenIdConnect calls
SSNClaimType	string	Yes		Claim type of the claim that should be used for getting the "social security number" for the user. Can be any claim that will uniquely identify a user
NameClaimType	string	Yes		Claim type of the claim that should be used for getting the user's full name
UserIdClaimType	string	Yes		Claim type of the claim that should be used for getting the user's "UserId"
WorkplacesClaimType	string	Yes		Claim type of the claim(s) that should be used for getting the user's list of department level workplaces
OrganizationClaimType	string	Yes		Claim type of the claim(s) that should be used for getting the user's list of organizations. Ignored if "DepartmentsAsSingleClaim" = true
ValidAudiences	list<string>	Yes		List of valid audiences
AdditionalScopes	list<string>	No	[]	List of additional scopes to use
AppRoleClaimType	string	No	"roles"	Claim type of the claim(s) that should be used for getting the user's list of roles
ValidIssuers	list<string>	No		List of valid issuers. Uses authority as valid issuer if property is missing or value is null
DepartmentsAsSingleClaim	bool	No	false	Tells the system to treat the value in the WorkplacesClaimType claim as a semi-colon separated list, and to use configured DepartmentIdMapping to build the user's organization hierarchy tree
RolePickerEnabled	bool	No	false	Is only used in InsightConfiguration. Enables a role picker in Insight which requires the user's to pick Department and Role before being able to use the rest of Insight
DepartmentsClaimSeparator	string	No	";"	The separator used to separate department id values from the WorkplacesClaimType claim when DepartmentsAsSingleClaim is true

OpenIdConnectConfiguration.json - Example

{
  "InsightConfiguration": {
    "ClientId": "4a821d50-11a1-483f-8782-e865ab3033a1",
    "ClientSecret": "[REDACTED]",
    "Authority": "https://login.microsoftonline.com/73935988-7e75-46c2-8cc6-d2d91985f67b/v2.0",
    "SSNClaimType": "extn.ssn",
    "NameClaimType": "name",
    "UserIdClaimType": "preferred_username",
    "WorkplacesClaimType": "groups",
    "OrganizationClaimType": "extn.OrganizationIdentification",
    "ValidAudiences": [
      "4a821d50-11a1-483f-8782-e865ab3033a1"
    ],
    "RolePickerEnabled": true,
    "DepartmentsAsSingleClaim": false
  },
  "ClientConfiguration": {
    "ClientId": "4a821d50-11a1-483f-8782-e865ab3033a1",
    "ClientSecret": "[REDACTED]",
    "Authority": "https://login.microsoftonline.com/73935988-7e75-46c2-8cc6-d2d91985f67b/v2.0",
    "SSNClaimType": "extn.ssn",
    "NameClaimType": "name",
    "UserIdClaimType": "preferred_username",
    "WorkplacesClaimType": "groups",
    "OrganizationClaimType": "extn.OrganizationIdentification",
    "ValidAudiences": [
      "4a821d50-11a1-483f-8782-e865ab3033a1"
    ],
    "RolePickerEnabled": true,
    "DepartmentsAsSingleClaim": false
  }
}

RoleToAccessMapping.json

List of objects which tells the system which access rights are given by which roles.

Definition of available access rights can be found in Access Rights document.

Property	Type	IsRequired	Default value	Description
Role	string	Yes		Id/value of a role that the user's can have in their token after login
AccessRights	list<string>	Yes		List of access rights that should be given by the Role
DisplayName	string	No		The display name to use for the role in the role picker in Insight if it's enabled

RoleToAccessMapping - Example

[
    {
        "Role": "sys_role_journalregistration",
        "DisplayName": "Journalregistrering",
        "AccessRights": [
            "OrganizationClient",
            "UserJournalView",
            "UserJournalEdit",
            "UserJournalPrint",
            "UserJournalComplete"
        ]
    },
    {
        "Role": "sys_role_patient_complaint_handler",
        "DisplayName": "Klagesakshåndtering",
        "AccessRights": [
            "OrganizationJournalView",
            "OrganizationJournalPrint",
            "OrganizationJournalDelete",
            "BlacklistWhitelist",
            "OrganizationAuditLog",
            "OrganizationMainWithMedicalData"
        ]
    },
]

DepartmentIdMapping.json

List of objects which tells the system which organization id a department belongs to, and what the name of the department is.

This list is used by the access control middleware to construct the user's organization hierarchy when DepartmentsAsSingleClaim is enabled, and to display more user-friendly names for departments in the role picker.

Property	Type	IsRequired	Default value	Description
DepartmentId	string	Yes		Id of the department. Usually a RESH-ID in Norway
DepartmentName	string	Yes		Name of the department
OrganizationId	string	Yes		Id of the organization that the department belongs to

DepartmentIdMapping - Example

[
    {
        "DepartmentId": "9ccda3e6-320a-4504-9386-97b2117ec744",
        "DepartmentName": "Cardiology outpatient clinic",
        "OrganizationId": "100000001",
    },
    {
        "DepartmentId": "f45eaef5-1e97-4a15-95c3-6d77a689b9ac",
        "DepartmentName": "Grimstad emergency room",
        "OrganizationId": "100000001",
    }
]