Enhanced Consortia Support Data FAQ

Owned by Olamide Kolawole
Last updated: Oct 25, 2023

This document highlight frequently asked questions about loading data into an ECS environment. Some keywords are documented here: ECS Glossary.

Authentication

How to log into an ECS environment and obtain a token?

With a username, password & tenant id in hand, login is the same as a non-ECS environment.

Example via mod-login
POST /authn/login HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
Content-Type: application/json

{
    "username": "<<username>>",
    "password": "<<password>>"
}

What headers should be set to target a tenant in the consortium?

The standard headers, X-Okapi-Tenant & X-Okapi-Token, is used to target a tenant.

Example
GET /users HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<targetTenantId>>
X-Okapi-Token: <<token>>


When X-Okapi-Tenant is not passed, the tenant ID embedded in the token will be used instead. This means that X-Okapi-Tenant is not required in ECS mode, just like in non-ECS mode.


Are there any modifications to the Users schema?

The type field is now required when creating a user in a tenant with ECS enabled. Appropriate known values for the type field include: patron, staff, system, dcb. Users with type=patron are not processed by the ECS pipeline, this means Shadow Users are never created for patrons.

If a user was created prior to enabling ECS in a tenant, it is possible to set the type field via API or UI before enabling ECS.

Consortium Configuration

How do i find my central tenant & consortium identifiers?

The response of a similar API call below will return consortium details including the central tenant identifier and the consortium tenant identifier.

Example Request
GET /user-tenants?limit=1 HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<anyAccessibleTenantId>>
X-Okapi-Token: <<token>>
Sample Response
{
    "userTenants": [
        {
            "id": "44b2ab3b-41d6-4a32-b336-a7ed300a548d",
            "userId": "8c261d46-9385-4bcb-a036-6389a557d020",
            "username": "data-export-system-user",
            "tenantId": "consortium",
            "centralTenantId": "consortium",
            "consortiumId": "b579d613-cb3b-4a28-9ca9-f8189ac6e3c5"
        }
    ],
    "totalRecords": 353
}

The endpoint above will only be populated if ECS is enabled in a FOLIO tenant.

How do i find members of a consortium?

The response of a similar API call below will return the members of a consortium.

GET /consortia/<<consortiumId>>/tenants HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
X-Okapi-Token: <<token>>

How to create a Shadow User in a member tenant?

Shadow users are created by assigning an non-primary affiliation to a member tenant. Suppose a user already exists in a member tenant(home tenant) and needs access to another member tenant(other tenant) in the consortium, an affiliation for the other member tenant is assigned to the user that lives in the home tenant. When the assignment is successful, a Shadow User is created by the system in the other tenant.

POST /consortia/<<consortiumId>>/user-tenants HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
X-Okapi-Token: <<token>>
Content-Type: application/json

{
    "userId": "<<user_id>>",
    "tenantId": "other_tenant"
}

Users

Which attributes of the User is required to be unique across the consortium?

Only username is required to be unique.

Inventory

How to create a Shared Instance?

An Instance is "Shared" when it is present in the central tenant. Standard instance creation endpoints should be used to perform this action.

How to create a Shadow Instance?

Shadow Instances are copies of a Shared Instance that lives in member tenant. Shadow Instances are created when some other FOLIO object needs to relate to them e.g. Holdings. Here are the current avenues, at the time of writing, to have a Shadow Instance created.

  • Holdings batch sync API: Holdings records in a batch sync api call will have the corresponding Shadow Instance created if it does not exist. The Shared Instance must exist in the central tenant.
  • "Create Holding" API: When an holding is to be created in a member tenant, with its instance identifier set to a Shared Instance(in the central tenant), a Shadow Instance is created before creating the holding.
  • "Create Order" API: When an order is to be created in a member tenant, with its linked instance set to a Shared Instance(in the central tenant), a Shadow Instance is created while creating the order by the system.

Independent Shadow Instance Creation

It is possible to create a shadow instance without the preceding actions above. This is discouraged because creating a Shadow Instance results in an additional object that must be maintained in sync with the Shared Instance. This can have ripple effects on other subsystems of FOLIO, such as search and OAI-PMH harvesting, while providing minimal value (as it does not include holdings or related orders).

POST /consortia/<<consortiumId>>/sharing/instances HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
X-Okapi-Token: <<token>>
Content-Type: application/json

{
    "instanceIdentifier": "<<instanceId>>",
    "sourceTenantId": "<<sourceTenantId>>",
    "targetTenantId": "<<targetTenantId>>"
}

The response of the call above will include an id field. The status of the sharing action can be retrieved with this identifier.

GET /consortia/<<consortiumId>>/sharing/instances/<<sharingActionId>> HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
X-Okapi-Token: <<token>>

At the time of writing, the sharing of an instance with a target tenant (thereby creating a Shadow Instance in the target tenant) will be considered complete when the call to initiate the sharing action returns. So there should be no need to check the status of the sharing action.

Search

Can I see local Instances belonging to other member tenants in the central tenant?

Reference Data

How to create a Shared Setting?

In the sharing of settings, system user context is used. After performing a sharing action, each setting with the type 'consortium' appears in all tenants belonging to the consortium.

Under the hood, this setting's UUID is checked to determine if it is shared or not in each tenant. This is done via a separate internal 'sharing_setting' table in order to create or update these settings.

POST /consortia/<<consortiumId>>/settings HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
X-Okapi-Token: <<token>>
Content-Type: application/json  

{
    "settingId": "<UUID>",
    "url": "<<FOLIO_URL>>",
    "payload": <<object>>
}

From the response, there are two IDs from two different Publish Coordinator requests: one for creating and another for updating settings in tenants. These IDs can be polled separately to determine when the creation or updating of settings has been completed.

Sample Response
{
    "createSettingsPcId": "<UUID>",
    "updateSettingsPcId": "<UUID>"
}

How to delete a Shared Setting?

The system user context is used to delete shared settings from all tenants. If a setting is in use within a tenant and cannot be deleted, the source changes from 'consortium' to 'local' for that setting.

DELETE /consortia/<<consortiumId>>/settings/<<settingId>> HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
X-Okapi-Token: <<token>>
Content-Type: application/json  

{
    "settingId": "<<UUID>>",
    "url": "<<FOLIO_URL>>",
    "payload": <<object>>
}

In the response, there is an ID of the related Publish Coordinator request that can be used to monitor when the deletion of the shared setting is completed.

Sample Response
{
    "pcId": "<UUID>"
}

How to check the status of a publication?

The Publish Coordinator(PC) is used to publish the same request to many tenants in a consortium. When sharing/un-sharing settings, the response will include publication identifiers that can be used to check the status of the publications.

GET /consortia/<<consortiumId>>/publications/<<publicationId>> HTTP/1.1
Host: folio-testing-sprint-okapi.ci.folio.org
X-Okapi-Tenant: <<centralTenantId>>
X-Okapi-Token: <<token>>