Tenants topology

Deployment steps

Create central and institutional tenants

To perform multi tenancy consortia setup lets create 3 tenants with ids: consortium, university, college

We need to create new host with UI only for the central tenant.

Enable modules on tenants

We should follow the standard procedure of enabling tenants from install.json and enable all desired modules except one UI module folio_consortia-settings that should be enabled only in the consortium central tenant

Configure tenants

• Reference data & sample data should NOT be created on both central and institutional tenants.

• Reset password link, SMTP for sending emails should be configured on all tenants. Separate admin users in each tenant can be created to apply all this configuration.

Create admin user in the central tenant

For Consortia setup it is required to create admin user in the central consortium tenant. For other tenants shadow admin users with required set of permissions will be created automatically during Configure consortium tenants step.

This admin user should contain all existing permissions that admin users currently have for our common envs plus 2 additional:

• consortia.consortium.item.post
• consortia.tenants.item.post

Configure consortium tenants

Create consortium record

Validation requirements:

• Only 1 consortium record should exist across cluster. adding more is prohibited

Request to create consortium record:

POST /consortia HTTP/1.1
X-Okapi-Tenant: consortium
X-Okapi-Token: <JWT>
Content-Type: application/json

{
    "id": "a617d446-4c00-4f8f-bcd4-5beacbccef67",
    "name": "Mobius"
}

Create consortium tenants

Actions performed under the hood of invoiking POST /consortia/{consortiumId}/tenants:

• Store central tenant id in the consortia_settings table of the desired tenant
• Perform primary affiliation creating for all existing users asynchronously
• Invoke /user-tenant to store dummy user

Validation rules:

• Consortium record should be created before adding tenant
• Name and code fields should be unique
• Name min length - 2, max length - 150
• Code min length - 3, max length - 3, regex pattern - '^[a-zA-Z0-9]*$'
• Tenant should not be existed already
• Central tenant should be added firstly
• Adding tenant when some another tenant has setupStatus = "IN_PROGRESS" is forbidden

Add central tenant to the consortium

Request to create central consortium tenant:

POST /consortia/a617d446-4c00-4f8f-bcd4-5beacbccef67/tenants HTTP/1.1
X-Okapi-Tenant: consortium
X-Okapi-Token: <JWT>
Content-Type: application/json

{
    "id": "consortium",
    "name": "Central office",
    "code": "MCO",
    "isCentral": true
}

@startuml
!pragma teoz true

!theme cerulean

autonumber

actor "user" as user

participant "mod-consortia" as mc
database "mod-consortia DB" as mc_db
participant "mod-users" as mu
participant "mod-login" as ml

user -> mc: Add central tenant to consortium
activate mc
group  #F3F0E1 Central tenant schema
mc -> mc: Check consortium exists ot throw an error
mc -> mc: Check tenant not yet added or throw an error
mc -> mc: Check if don't have have a central tenant or throw an error
mc -> mc_db: Save central tenant in tenant table
mc -> ml: Login by system user and use his token for all subsequent requests
group System user makes all subsequent calls
note left
System user permissions:
consortia.consortia-configuration.item.post
users.collection.get
users.item.get
users.item.post
users.item.put
perms.users.item.put
perms.users.item.post
perms.users.item.delete
perms.users.assign.immutable
perms.users.assign.mutable
perms.users.get
user-tenants.item.post
end note
mc -> mc_db: Save central tenant id in consortia-configuration table

group  #eeeee4 Create primary affiliation for existed users(async)
  mc -> mu: Retrieve all existed users from central tenant
  loop users size count
    mc -> mc_db: Check if primary user affiliation already exists in user_tenant table
    alt #E8F3E1 User was not affiliatied yet
      mc -> mc_db: Save primary user affiliation in user_tenant table
      mc -> mu: Send CONSORTIUM_PRIMARY_AFFILIATION_CREATED event
    else #F3E1E2 User was already affiliatied previously
      mc -> mc: Skipping creating primary affiliation for this user
  end
end

end
mc --> user: Status: Created
@enduml

Add institutional tenants to the consortium

Request to create University tenant:

POST /consortia/a617d446-4c00-4f8f-bcd4-5beacbccef67/tenants?adminUserId=b20c4397-ad56-479f-891a-30a5a471f24b HTTP/1.1
X-Okapi-Tenant: consortium
X-Okapi-Token: <JWT>
Content-Type: application/json

{
    "id": "university",
    "name": "University",
    "code": "UNI",
    "isCentral": false
}

Request to create College tenant:

POST /consortia/a617d446-4c00-4f8f-bcd4-5beacbccef67/tenants?adminUserId=b20c4397-ad56-479f-891a-30a5a471f24b HTTP/1.1
X-Okapi-Tenant: consortium
X-Okapi-Token: <JWT>
Content-Type: application/json

{
    "id": "college",
    "name": "College",
    "code": "COL",
    "isCentral": false
}

@startuml

!pragma teoz true

!theme cerulean

autonumber


actor "user" as user

participant "mod-consortia" as mc
database "mod-consortia DB" as mc_db
participant "mod-users" as mu
participant "mod-login" as ml
participant "mod-permissions" as mp

user -> mc: Add member tenant to consortium
activate mc
group  #F3F0E1 Central tenant schema
mc -> mc: Check consortium exists ot throw an error
mc -> mc: Check tenant not yet added or throw an error
mc -> mc_db: Save member tenant in tenant table
group #E7BFF5 Create shadow admin user_tenant association in central tenant
  mc -> mc_db: Get central tenant id
  mc -> mu: Fetch admin user to prepare shadow user
  mc -> mc_db: Save shadow admin associatation in user_tenant table      
end
end

group  #DBE1F1 Member tenant schema
  mc -> ml: Login by system user in member tenant and use his token for all subsequent requests
  group System user makes all subsequent calls
    note left
      System user permissions:
      consortia.consortia-configuration.item.post
      users.collection.get
      users.item.get
      users.item.post
      users.item.put
      perms.users.item.put
      perms.users.item.post
      perms.users.item.delete
      perms.users.assign.immutable
      perms.users.assign.mutable
      perms.users.get
      user-tenants.item.post
    end note

    mc -> mc_db: Save central tenant id in consortia-configuration table
    mc -> mu: Create dummy user_tenant record    

    group #E7BFF5 Create shadow admin user with permissions in member tenant
      mc -> mu: Create shadow admin user
      mc -> mp: Add predefined set of permissions to shadow admin user
      note left
        Shadow admin user permissions:
        ui-users.editperms
      end note
    end

    group  #eeeee4 Create primary affiliation for existed users(async)
    mc -> mu: Retrieve all existed users from this member tenant
    loop users size count
      mc -> mc_db: Check if primary user affiliation already exists in user_tenant table
      alt #E8F3E1 User was not affiliatied yet
        mc -> mc_db: Save primary user affiliation in user_tenant table
        mc -> mu: Send CONSORTIUM_PRIMARY_AFFILIATION_CREATED event
      else #F3E1E2 User was already affiliatied previously
        mc -> mc: Skipping creating primary affiliation for this user
    end
  end
end
mc --> user: Status: Created
end




@enduml

Order to add tenants to the consortium

Sequential order to add tenants to the consortium should be used, because under the hood we are making operations to create users in other tenants and simultaneously have an async operation to migrate existing users in current tenant.

Firstly, an automation job should create a central tenant and after this - all member tenants.

To control the tenant setup state we have a field 'setupStatus' in tenant response body with allowed values: "IN_PROGRESS", "COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED".

Automation deployment job should make polling of GET /consortia/{{consortiumId}}/tenants/{{tenantId}} endpoint until COMPLETED or COMPLETED_WITH_ERRORS  status.

Poll interval can be chosen as 10 sec for example.

mod-consortia prevents adding new tenant when some tenant in DB has setupStatus with "IN_PROGRESS" value.

Here is description of all possible statuses:

User type is required in ECS mode

On some of the customers it is possible to have more than 1.3 million of patron users, ECS does not need to process all of them through a consortium pipeline, because patron users can not and should not login to consortia.

 So 'type' field for user is required now in ECS mode, for non ECS it is optional.

This change brings 2 benefits:

• General performance of ECS increases because ECS logic will work with thousands of staff/system users instead of millions of patron users
• A clear way to distinguish user types in Folio appears

Possible user types:

How to deal with existing users

What is going on during this process of migrating existing users?

When adding a tenant to the consortium, the process of migrating existing users through the consortia pipeline begins within the scope of each:

• Primary affiliation, and Affiliation in the central tenant (if the user is from a member tenant), with shadow users created.
• The 'user-tenants' table in 'mod-users' is populated in the central tenant, which enables existing users to log in to ECS.

In conclusion, users processed by the consortia pipeline can log in, and affiliations will be manageable in ECS mode.

When to migrate existing users, before or after enabling ECS mode?

Before enabling ECS mode

The process of migrating existing users has been added to handle certain system or admin users through the ECS pipeline. This process is also triggered when ECS mode is enabled on a tenant that already has users with a populated 'type' field.

The query used to fetch existing users, as used by 'mod-consortia,' is as follows: (cql.allRecords=1 NOT type="patron" NOT type="dcb" NOT type="shadow"). With this query, all users without a populated 'type' field or with a 'type' that does not equal 'patron' or 'dcb' will be migrated.

One important point to consider is that if, for example, 1.5 million patron users were created without populating the 'type' field as 'patron' when ECS was not enabled, all 1.5 million users will be migrated. This behavior is not desired because the validation of the 'type' as a required field is only enabled when ECS mode is enabled, and ECS should skip processing these users in the pipeline.

After enabling ECS mode

If we have a choice, it's preferable to enable ECS mode for the tenant and then begin creating/migrating users. These users will be processed by 'mod-consortia' via Kafka domain events sent by 'mod-users.'

In this scenario, users cannot be created without populating the 'type' field because validation is enabled in ECS mode. For some customers, we may have more than 1.5 million patron users and only a couple of thousand staff users. In this case, we can ensure that 'mod-consortia' will process only these thousands of staff users and exclude the millions of patrons.

In conclusion, it's better to migrate existing users after enabling ECS mode for the tenant.

Do we need to adjust our existing admin users to populate type='staff'

Let's begin with system users. All repositories have been updated to create new system users with the type 'system,' and a migration script has been written in 'mod-users' to add 'type='system'' for all existing system users.

So, for system users, no further actions are required.

For admin users, it's advisable but not mandatory. We recommend adding 'type='staff'' to avoid confusion regarding users that existed without a populated 'type' field in ECS mode, where this type field is required.

Additionally, some new features, such as filtering by user type in the Users App, will not consider users without a 'type' value.

However, even if 'type' is not populated for admin users, 'mod-consortia' will still select such users and process them through the ECS pipeline during the 'migrate existing users' process when adding the tenant to the consortium. This process includes users without a 'type' populated.

In conclusion, no action is needed for 'system' users, but for common admin users, it's advisable to add 'type='staff''.

Changes for config values

In consortium mode we have only 1 UI available for a central tenant, so properties that are stored in mod-configuration like FOLIO_HOST  should be pointed to this single host for every tenant.

BE Modules modified for supporting consortia functionality

Thunderjet team

Firebird team

Folijet team

Spitfire team

Volaris team

Issues found during consortia env setup