{"id":23122585,"url":"https://github.com/folio-org/mod-user-import","last_synced_at":"2025-07-11T01:33:49.744Z","repository":{"id":23710901,"uuid":"99659887","full_name":"folio-org/mod-user-import","owner":"folio-org","description":"Import new or already existing users","archived":false,"fork":false,"pushed_at":"2024-11-01T19:23:38.000Z","size":459,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-12-05T03:15:16.841Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/folio-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-08T06:47:38.000Z","updated_at":"2024-11-01T19:23:09.000Z","dependencies_parsed_at":"2023-01-13T23:44:28.408Z","dependency_job_id":null,"html_url":"https://github.com/folio-org/mod-user-import","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-user-import","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-user-import/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-user-import/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-user-import/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/folio-org","download_url":"https://codeload.github.com/folio-org/mod-user-import/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230080717,"owners_count":18169608,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T07:28:18.162Z","updated_at":"2025-07-11T01:33:49.727Z","avatar_url":"https://github.com/folio-org.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mod-user-import\n\nCopyright (C) 2017-2025 The Open Library Foundation\n\nThis software is distributed under the terms of the Apache License,\nVersion 2.0. See the file \"[LICENSE](LICENSE)\" for more information.\n\n## Introduction\n\nThis module is responsible for importing new or already existing users into FOLIO.\n\nCurrently the module contains one endpoint:\nPOST /user-import\n\n## How to use\n\n1. Login with a user who has permission for importing users (permission name: \u003ccode\u003eUser import\u003c/code\u003e, permission code: \u003ccode\u003euser-import.all\u003c/code\u003e). This can be done by sending the following request to FOLIO:\n\u003cpre\u003eURL: \u003ccode\u003e{okapiUrl}/authn/login\u003c/code\u003e\nHeaders:\n\u003ccode\u003e\n  x-okapi-tenant: {tenantName}\n  Content-Type: application/json\n\u003c/code\u003e\nBody:\n\u003ccode\u003e\n  {\n    \"username\": \"username\",\n    \"password\": \"password\"\n  }\n\u003c/code\u003e\u003c/pre\u003e\n\n2. 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 \u003ccode\u003ex-okapi-token\u003c/code\u003e header (use as \u003ccode\u003eokapiToken\u003c/code\u003e). The user import request can be sent in the following format:\n\u003cpre\u003eURL: \u003ccode\u003e{okapiUrl}/user-import\u003c/code\u003e\nHeaders:\n\u003ccode\u003e\n  x-okapi-tenant: {tenantName}\n  Content-Type: application/json\n  x-okapi-token: {okapiToken}\n\u003c/code\u003e\nBody:\n\u003ccode\u003e{exampleImport}\u003c/code\u003e\n\u003c/pre\u003e\n\n3. The response of the import will be:\n\u003cpre\u003e\u003ccode\u003e{\n    \"message\": {message stating that the import was successful or failed or the users were deactivated (in case of successful import and deactivateMissingUsers=true)},\n    \"createdRecords\": {number of newly created users},\n    \"updatedRecords\": {number of updated users},\n    \"failedRecords\": {number of users failed to create/update},\n    \"failedExternalSystemIds\": [{a list of users that were failed to create/update}],\n    \"totalRecords\": {number of total records processed by the user import}\n}\u003c/code\u003e\u003c/pre\u003e\n\nThe default \u003ccode\u003eokapiUrl\u003c/code\u003e is \u003ccode\u003ehttp://localhost:9130\u003c/code\u003e. The default \u003ccode\u003etenantName\u003c/code\u003e is \u003ccode\u003ediku\u003c/code\u003e. An \u003ccode\u003eexampleImport\u003c/code\u003e can be found in the next section.\n\n## Example import request\n\u003cpre\u003e\u003ccode\u003e{\n  \"users\": [\n    {\n      \"username\": \"jhandey\",\n      \"externalSystemId\": \"111_112\",\n      \"barcode\": \"1234567\",\n      \"active\": true,\n      \"patronGroup\": \"staff\",\n      \"personal\": {\n        \"lastName\": \"Handey\",\n        \"firstName\": \"Jack\",\n        \"middleName\": \"Michael\",\n        \"preferredFirstName\": \"Jackie\",\n        \"phone\": \"+36 55 230 348\",\n        \"mobilePhone\": \"+36 55 379 130\",\n        \"dateOfBirth\": \"1995-10-10\",\n        \"addresses\": [\n          {\n            \"countryId\": \"HU\",\n            \"addressLine1\": \"Andrássy Street 1.\",\n            \"addressLine2\": \"\",\n            \"city\": \"Budapest\",\n            \"region\": \"Pest\",\n            \"postalCode\": \"1061\",\n            \"addressTypeId\": \"Home\",\n            \"primaryAddress\": true\n          }\n        ],\n        \"preferredContactTypeId\": \"mail\"\n      },\n      \"enrollmentDate\": \"2017-01-01\",\n      \"expirationDate\": \"2019-01-01\",\n      \"customFields\": {\n        \"scope\": \"Design\",\n        \"specialization\": [\n          \"Business\",\n          \"Jurisprudence\"\n        ]\n      },\n      \"requestPreference\": {\n        \"holdShelf\": true,\n        \"delivery\": true,\n        \"defaultServicePointId\": \"00000000-0000-1000-a000-000000000000\",\n        \"defaultDeliveryAddressTypeId\": \"Home\",\n        \"fulfillment\": \"Hold Shelf\"\n      },\n      \"departments\": [\n        \"Accounting\",\n        \"Finance\",\n        \"Chemistry\"\n      ]\n    }\n  ],\n  \"included\": {\n    \"departments\": [\n      {\n        \"name\": \"Accounting\",\n        \"code\": \"ACC\"\n      },\n      {\n        \"name\": \"Finance\"\n      }\n    ],\n    \"customFields\":[\n      {\n        \"refId\": \"specialization\",\n        \"selectField\": {\n          \"options\": {\n            \"values\": [\n              {\n                \"value\": \"Business\"\n              },\n              {\n                \"value\": \"Jurisprudence\"\n              }\n            ]\n          }\n        }\n      }\n    ]\n  },\n  \"totalRecords\": 1,\n  \"deactivateMissingUsers\": true,\n  \"updateOnlyPresentFields\": false,\n  \"sourceType\": \"test\"\n}\u003c/code\u003e\u003c/pre\u003e\n\n### patronGroup\nThe value can be the name of an existing patron group in the system, e.g. \u003ccode\u003efaculty\u003c/code\u003e, \u003ccode\u003estaff\u003c/code\u003e,\n\u003ccode\u003eundergrad\u003c/code\u003e, \u003ccode\u003egraduate\u003c/code\u003e. The import module will match the patron group names and replace with\nthe patron group ids. If the patron group with the specified name does not exist in the system, then the error will be thrown.\nThe currently available patron groups can be listed using a \u003ccode\u003eGET\u003c/code\u003e request for\n\u003ccode\u003e{okapiUrl}/groups\u003c/code\u003e. The \u003ccode\u003ex-okapi-token\u003c/code\u003e and \u003ccode\u003ex-okapi-tenant\u003c/code\u003e headers are required.\nThe authenticated user needs to have a permission for retrieving patron groups (permission name: \u003ccode\u003eusers all\u003c/code\u003e,\npermission code: \u003ccode\u003eusers.all\u003c/code\u003e).\n\n### addressTypeId\nThe value can be the name of an existing address type in the system, e.g. \u003ccode\u003eHome\u003c/code\u003e, \u003ccode\u003eClaim\u003c/code\u003e, \u003ccode\u003eOrder\u003c/code\u003e. 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 \u003ccode\u003eGET\u003c/code\u003e request to \u003ccode\u003e{okapiUrl}/addresstypes\u003c/code\u003e. The \u003ccode\u003ex-okapi-token\u003c/code\u003e and \u003ccode\u003ex-okapi-tenant\u003c/code\u003e headers are required. The authenticated user needs to have a permission for retrieving address types (permission name: \u003ccode\u003eusers all\u003c/code\u003e, permission code: \u003ccode\u003eusers.all\u003c/code\u003e).\n\n### preferredContactTypeId\nThe value can be one of the following: \u003ccode\u003email\u003c/code\u003e, \u003ccode\u003eemail\u003c/code\u003e, \u003ccode\u003etext\u003c/code\u003e, \u003ccode\u003ephone\u003c/code\u003e, \u003ccode\u003emobile\u003c/code\u003e.\n\n### deactivateMissingUsers\nThis should be true if the users missing from the current import batch should be deactivated in FOLIO.\n\n### updateOnlyPresentFields\nThis 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.\n\nCurrently this only works for addresses. Please more embedded fields need this feature open a story a https://issues.folio.org/projects/MODUIMP/issues\n\n### sourceType\nA prefix for the \u003ccode\u003eexternalSystemId\u003c/code\u003e 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 \u003ccode\u003eexternalSystemId\u003c/code\u003e with an underscore, e.g. if the user's \u003ccode\u003eexternalSystemId\u003c/code\u003e in the import is somebody012 and the \u003ccode\u003esourceType\u003c/code\u003e is test, the user's \u003ccode\u003eexternalSystemId\u003c/code\u003e will be test_somebody012.\n\n### requestPreference\nUse this attribute to populate the user Request preference. The Request Preference contains following properties:\n\n\u003ccode\u003eholdShelf\u003c/code\u003e - required field, should always be true;\n\u003ccode\u003edelivery\u003c/code\u003e - required field, could be \u003ccode\u003etrue\u003c/code\u003e or \u003ccode\u003efalse\u003c/code\u003e;\n\u003ccode\u003edefaultServicePointId\u003c/code\u003e - optional, the id of user's default service point\nif \u003ccode\u003edelivery\u003c/code\u003e is \u003ccode\u003etrue\u003c/code\u003e then next properties can be used\n\u003ccode\u003efulfillment\u003c/code\u003e - required field, can only have \u003ccode\u003eHold shelf\u003c/code\u003e or \u003ccode\u003eDelivery\u003c/code\u003e value;\n\u003ccode\u003edefaultDeliveryAddressTypeId\u003c/code\u003e - optional, the name of user's address type\n* If the requestPreference exists in payload and exists in the system - the system will update existing user preference.\n* If the requestPreference exists in payload and doesn't exist in the system - the system will create a new one.\n* If the requestPreference does not exist in payload but exists in the system - the system will delete existing preference.\n* If value provided for defaultServicePointId or defaultDeliveryAddressTypeId does not exist in the system - the system will return an error\n\n### departments\nNames of departments the user belongs to. To manage departments creation use attribute \u003ccode\u003edepartments\u003c/code\u003e in \u003ccode\u003eincluded\u003c/code\u003e.\n* If the department doesn't exist in included and exists in the system - assign the department to user\n* 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\n* 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\n* If the department doesn't exist in included and not exist in the system - error\n\n### customFields\nCan be populated with pairs:\n\u003ccode\u003erefId: value\u003c/code\u003e,\nwhere \u003ccode\u003erefId\u003c/code\u003e - refId of an existing custom field,\n\u003ccode\u003evalue\u003c/code\u003e - one value or set of values.\n\n**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.\n\n**Note 2:** To manage custom fields updating use attribute \u003ccode\u003edepartments\u003c/code\u003e in \u003ccode\u003eincluded\u003c/code\u003e. 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.\n## Additional information\n\n### Issue tracker\n\nSee project [MODUIMP](https://issues.folio.org/browse/MODUIMP)\nat the [FOLIO issue tracker](https://dev.folio.org/guidelines/issue-tracker).\n\n### Other documentation\n\nOther [modules](https://dev.folio.org/source-code/#server-side) are described,\nwith further FOLIO Developer documentation at [dev.folio.org](https://dev.folio.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-user-import","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffolio-org%2Fmod-user-import","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-user-import/lists"}