Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/folio-org/mod-user-import

Import new or already existing users
https://github.com/folio-org/mod-user-import

Last synced: 11 months ago
JSON representation

Import new or already existing users

Awesome Lists containing this project

README 

          
# mod-user-import



Copyright (C) 2017-2025 The Open Library Foundation



This software is distributed under the terms of the Apache License,

Version 2.0. See the file "[LICENSE](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



1. 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"

  }




2. 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}




3. 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](https://issues.folio.org/browse/MODUIMP)

at the [FOLIO issue tracker](https://dev.folio.org/guidelines/issue-tracker).



### Other documentation



Other [modules](https://dev.folio.org/source-code/#server-side) are described,

with further FOLIO Developer documentation at [dev.folio.org](https://dev.folio.org/)