mod-user-import

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.

Introduction

This module is responsible for importing new or already existing users into FOLIO.

Currently the module contains one endpoint: POST /user-import

How to use

Login with a user who has permission for importing users (permission name: User import, permission code: user-import.all). This can be done by sending the following request to FOLIO:

URL: {okapiUrl}/authn/login
Headers:

  x-okapi-tenant: {tenantName}
  Content-Type: application/json

Body:

  {
    "username": "username",
    "password": "password"
  }

The login request will return a header in the response which needs to be used for authentication in the following request. The authentication token is returned in the x-okapi-token header (use as okapiToken). The user import request can be sent in the following format:

URL: {okapiUrl}/user-import
Headers:

  x-okapi-tenant: {tenantName}
  Content-Type: application/json
  x-okapi-token: {okapiToken}

Body:
{exampleImport}

The response of the import will be:

{
    "message": {message stating that the import was successful or failed or the users were deactivated (in case of successful import and deactivateMissingUsers=true)},
    "createdRecords": {number of newly created users},
    "updatedRecords": {number of updated users},
    "failedRecords": {number of users failed to create/update},
    "failedExternalSystemIds": [{a list of users that were failed to create/update}],
    "totalRecords": {number of total records processed by the user import}
}

The default okapiUrl is http://localhost:9130. The default tenantName is diku. An exampleImport can be found in the next section.

Example import request

{
  "users": [
    {
      "username": "jhandey",
      "externalSystemId": "111_112",
      "barcode": "1234567",
      "active": true,
      "patronGroup": "staff",
      "personal": {
        "lastName": "Handey",
        "firstName": "Jack",
        "middleName": "Michael",
        "preferredFirstName": "Jackie",
        "phone": "+36 55 230 348",
        "mobilePhone": "+36 55 379 130",
        "dateOfBirth": "1995-10-10",
        "addresses": [
          {
            "countryId": "HU",
            "addressLine1": "Andrássy Street 1.",
            "addressLine2": "",
            "city": "Budapest",
            "region": "Pest",
            "postalCode": "1061",
            "addressTypeId": "Home",
            "primaryAddress": true
          }
        ],
        "preferredContactTypeId": "mail"
      },
      "enrollmentDate": "2017-01-01",
      "expirationDate": "2019-01-01",
      "customFields": {
        "scope": "Design",
        "specialization": [
          "Business",
          "Jurisprudence"
        ]
      },
      "requestPreference": {
        "holdShelf": true,
        "delivery": true,
        "defaultServicePointId": "00000000-0000-1000-a000-000000000000",
        "defaultDeliveryAddressTypeId": "Home",
        "fulfillment": "Hold Shelf"
      },
      "departments": [
        "Accounting",
        "Finance",
        "Chemistry"
      ]
    }
  ],
  "included": {
    "departments": [
      {
        "name": "Accounting",
        "code": "ACC"
      },
      {
        "name": "Finance"
      }
    ],
    "customFields":[
      {
        "refId": "specialization",
        "selectField": {
          "options": {
            "values": [
              {
                "value": "Business"
              },
              {
                "value": "Jurisprudence"
              }
            ]
          }
        }
      }
    ]
  },
  "totalRecords": 1,
  "deactivateMissingUsers": true,
  "updateOnlyPresentFields": false,
  "sourceType": "test"
}

patronGroup

The value can be the name of an existing patron group in the system, e.g. faculty, staff, undergrad, graduate. The import module will match the patron group names and replace with the patron group ids. If the patron group with the specified name does not exist in the system, then the error will be thrown. The currently available patron groups can be listed using a GET request for {okapiUrl}/groups. The x-okapi-token and x-okapi-tenant headers are required. The authenticated user needs to have a permission for retrieving patron groups (permission name: users all, permission code: users.all).

addressTypeId

The value can be the name of an existing address type in the system, e.g. Home, Claim, Order. The import module will match the address type names for the address type ids. It is important to note that two addresses for a user cannot have the same address type. The available address types can be queried with a GET request to {okapiUrl}/addresstypes. The x-okapi-token and x-okapi-tenant headers are required. The authenticated user needs to have a permission for retrieving address types (permission name: users all, permission code: users.all).

preferredContactTypeId

The value can be one of the following: mail, email, text, phone, mobile.

deactivateMissingUsers

This should be true if the users missing from the current import batch should be deactivated in FOLIO.

updateOnlyPresentFields

This should be true if only the fields present in the import should be updated, e.g. if a user address was added in FOLIO but that type of address is not present in the imported data then the address will be preserved.

Currently this only works for addresses. Please more embedded fields need this feature open a story a https://issues.folio.org/projects/MODUIMP/issues

sourceType

A prefix for the externalSystemId to be stored in the system. This field is useful for those organizations that has multiple sources of users. With this field the multiple sources can be separated. The source type is appended to the beginning of the externalSystemId with an underscore, e.g. if the user's externalSystemId in the import is somebody012 and the sourceType is test, the user's externalSystemId will be test_somebody012.

requestPreference

Use this attribute to populate the user Request preference. The Request Preference contains following properties:

holdShelf - required field, should always be true; delivery - required field, could be true or false; defaultServicePointId - optional, the id of user's default service point if delivery is true then next properties can be used fulfillment - required field, can only have Hold shelf or Delivery value; defaultDeliveryAddressTypeId - optional, the name of user's address type

If the requestPreference exists in payload and exists in the system - the system will update existing user preference.
If the requestPreference exists in payload and doesn't exist in the system - the system will create a new one.
If the requestPreference does not exist in payload but exists in the system - the system will delete existing preference.
If value provided for defaultServicePointId or defaultDeliveryAddressTypeId does not exist in the system - the system will return an error

departments

Names of departments the user belongs to. To manage departments creation use attribute departments in included.

If the department doesn't exist in included and exists in the system - assign the department to user
If the department exists in included and doesn't exist in the system - create the department (with code generation if missing) and assign the department to user
If the department with code exists in included and with the same code exists in the system - update department's name and assign the department to user
If the department doesn't exist in included and not exist in the system - error

customFields

Can be populated with pairs: refId: value, where refId - refId of an existing custom field, value - one value or set of values.

Note 1: In case of setting values to one of RADIO_BUTTON, SINGLE_SELECT_DROPDOWN, MULTI_SELECT_DROPDOWN type of custom field - use option names. If one or more option names are not existed in related by refId custom field definition than the system will return an error.

Note 2: To manage custom fields updating use attribute departments in included. Specifying in this section custom field's refId with one or more another fields will update custom fields definition. To update the selectable field's options it is required to specify ALL options.

Additional information

Issue tracker

See project MODUIMP at the FOLIO issue tracker.

folio-org/mod-user-import