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 should be created on both central and institutional tenants, sample data - only on central consortium tenant. 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 tenant to the consortium the process of migrating existing users through consortia pipeline started in scope of each:

• primary affiliation and affiliation in central tenant(if user is from member tenant) with shadow users created
• user-tenants table in mod-users populated in central tenant that allows existing users to login in ECS

Conclusion: users processed by consortia pipeline can login and affiliations will be manageable in ECS mode

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

Before enabling ECS mode

Process of migration of existing users is added to process some system or admin users by ECS pipeline or in case when ECS mode is enabled on an already existing tenant that already has users with populated 'type' field.

Query used to fetch existing users used by mod-consortia: (cql.allRecords=1 NOT type =\"patron\" NOT type = \"dcb\" ).   So with this query all users without 'type' field populated or if 'type' not equals to 'patron' or 'dcb' will be migrated.

One important note to take in mind - that if for example 1.5 mil of patron users were created without populating 'type'='patron' when ECS still not enabled - all 1.5 mil will be migrated that is not desired behavior, 

because validation that 'type' is required field enabled only when ECS mode enabled and ECS needs to skip processing users in the pipeline.

After enabling ECS mode

If we have a choice - better to enable ECS mode for tenant and after start creating/migrating users that would be processed by mod-consortia via kafka domain events sent by mod-users.

In this case nobody can create users without populating the 'type' field because validation is enabled in ECS mode. For some customer we can have more than 1.5 mil of patron user and only couple thousands of staff users,

so in this case we can guarantee that mod-consortia will process only these thousands of staff users and exclude millions of patrons.

Conclusion: better to migrate existing users after enabling ECS mode for tenant

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

Let's start from system users, all repositories were updated to create new system users with type='system' and also migration script is written in mod-users to add type='system' for all existing system users.

So for system users no actions required.

For admin users it is better to do but not required. We suggest adding type='staff' to not confuse why some users existed without 'type' populated in ECS mode where this type field is required.

Also some new features like filtering by user type in Users App will not take in consideration such users.

But even without populating 'type' for admin users - mod-consortia will pick up such users and process by ECS pipeline during migrate existing users process when adding tenant to the consortium,

because this process takes users even without 'type' populated.

Conclusion: for 'system' no action needed, for common admin users - better to add type='staff'

BE Modules modified for supporting consortia functionality

Thunderjet team

Firebird team

Folijet team

Spitfire team

Volaris team

Issues found during consortia env setup