No description, website, or topics provided.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
descriptors
docker
ramls
src
.editorconfig
.gitignore
.gitmodules
CONTRIBUTING.md
Dockerfile
Jenkinsfile
LICENSE
NEWS.md
README.md
pom.xml

README.md

mod-user-import

Copyright (C) 2017-2018 The Open Library Foundation

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

  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"
  }
  1. 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}
  1. 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": "somebody012",
    "externalSystemId": "somebody012",
    "barcode": "1657463",
    "active": true,
    "patronGroup": "faculty",
    "personal": {
      "lastName": "Somebody",
      "firstName": "Test",
      "middleName": "",
      "email": "test@email.com",
      "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"
  }],
  "totalRecords": 1,
  "deactivateMissingUsers": false,
  "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. 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.

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.

Additional information

Issue tracker

See project MODUIMP at the FOLIO issue tracker.

Other documentation

Other modules are described, with further FOLIO Developer documentation at dev.folio.org