User import version v1
http://localhost:8081
mod-user-import API
This documents the API calls that can be made to import users into the system
/user-import
post
Create or update a list of users
post /user-import
Create or update a list of users
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "User Data Import Collection Schema",
"description": "The user data import collection",
"additionalProperties": false,
"type": "object",
"properties": {
"users": {
"id": "usersData",
"type": "array",
"description": "List of users' data to import",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "User Schema",
"description": "A user; the same as used for /users API but with \"requestPreference\" property and \"require\" restriction added, and \"patronGroups\", \"departments\", \"addressTypeId\" and \"preferredContactTypeId\" are names and not UUIDs.",
"properties": {
"username": {
"description": "A unique name belonging to a user. Typically used for login",
"type": "string"
},
"id": {
"description": "A globally unique (UUID) identifier for the user",
"type": "string"
},
"externalSystemId": {
"description": "A unique ID that corresponds to an external authority",
"type": "string"
},
"barcode": {
"description": "The unique library barcode for this user",
"type": "string"
},
"active": {
"description": "A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block",
"type": "boolean"
},
"type": {
"description": "The class of user like staff or patron; this is different from patronGroup; it can store shadow, system user and dcb types also",
"type": "string"
},
"patronGroup": {
"description": "The name of the patron group the user belongs to; this is different from the patronGroup property of the /users API that is a UUID.",
"type": "string"
},
"departments": {
"description": "List of names of the departments the user belongs to; this is different from the departments property of the /users API this is a UUID.",
"type": "array",
"uniqueItems": true,
"items": {
"type": "string"
}
},
"meta": {
"description": "Deprecated",
"type": "object"
},
"proxyFor": {
"description": "Deprecated",
"type": "array",
"items": {
"type": "string"
}
},
"personal": {
"description": "Personal information about the user",
"type": "object",
"properties": {
"pronouns": {
"description": "The user's pronouns",
"type": "string",
"maxLength": 300
},
"lastName": {
"description": "The user's surname",
"type": "string"
},
"firstName": {
"description": "The user's given name",
"type": "string"
},
"middleName": {
"description": "The user's middle name (if any)",
"type": "string"
},
"preferredFirstName": {
"description": "The user's preferred name",
"type": "string"
},
"email": {
"description": "The user's email address",
"type": "string"
},
"phone": {
"description": "The user's primary phone number",
"type": "string"
},
"mobilePhone": {
"description": "The user's mobile phone number",
"type": "string"
},
"dateOfBirth": {
"type": "string",
"description": "The user's birth date",
"format": "date-time"
},
"addresses": {
"description": "Physical addresses associated with the user",
"type": "array",
"minItems": 0,
"items": {
"type": "object",
"properties": {
"id": {
"description": "A unique id for this address",
"type": "string"
},
"countryId": {
"description": "The country code for this address",
"type": "string"
},
"addressLine1": {
"description": "Address, Line 1",
"type": "string"
},
"addressLine2": {
"description": "Address, Line 2",
"type": "string"
},
"city": {
"description": "City name",
"type": "string"
},
"region": {
"description": "Region",
"type": "string"
},
"postalCode": {
"description": "Postal Code",
"type": "string"
},
"addressTypeId": {
"description": "The name of an address type object at the /addresstypes API; this is different from the addressTypeId property of the /users API that is a UUID.",
"type": "string"
},
"primaryAddress": {
"description": "Is this the user's primary address?",
"type": "boolean"
}
},
"additionalProperties": false
}
},
"preferredContactTypeId": {
"description": "Name of user's preferred contact type. One of mail, email, text, phone, mobile. This is different from the preferredContactTypeId property of the /users API that is a UUID.",
"type": "string"
},
"profilePictureLink": {
"description": "Link to the profile picture, or only the id of the /users/profile-picture entry",
"type": "string",
"format": "uri"
}
},
"additionalProperties": false,
"required": [
"lastName"
]
},
"enrollmentDate": {
"description": "The date in which the user joined the organization",
"type": "string",
"format": "date-time"
},
"expirationDate": {
"description": "The date for when the user becomes inactive",
"type": "string",
"format": "date-time"
},
"createdDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"updatedDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
},
"tags": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "tags.schema",
"title": "tags",
"description": "List of simple tags that can be added to an object",
"properties": {
"tagList": {
"description": "List of tags",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"customFields": {
"description": "Object that contains custom field",
"type": "object",
"additionalProperties": true
},
"preferredEmailCommunication": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Support",
"Programs",
"Services"
]
},
"maxItems": 3,
"uniqueItems": true,
"description": "Preferred email communication types"
},
"requestPreference": {
"description": "User request preferences",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"id": {
"description": "Unique request preference ID",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "uuid.schema",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
},
"userId": {
"description": "UUID of user associated with this request preference",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "uuid.schema",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
},
"holdShelf": {
"description": "Whether 'Hold Shelf' option is available to the user.",
"type": "boolean",
"enum": [
true
],
"example": true
},
"delivery": {
"description": "Whether 'Delivery' option is available to the user.",
"type": "boolean",
"default": false,
"example": false
},
"defaultServicePointId": {
"description": "UUID of default service point for 'Hold Shelf' option",
"type": "string",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "uuid.schema",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
},
"defaultDeliveryAddressTypeId": {
"description": "Name of user's address type",
"type": "string"
},
"fulfillment": {
"description": "Preferred fulfillment type. Possible values are 'Delivery', 'Hold Shelf'",
"type": "string",
"enum": [
"Delivery",
"Hold Shelf"
],
"example": "Delivery"
},
"metadata": {
"description": "Metadata about creation and changes to request preference",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"type": "object",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"holdShelf",
"delivery"
]
}
},
"additionalProperties": false,
"required": [
"username",
"externalSystemId"
]
}
},
"totalRecords": {
"description": "Total number of users' data to import",
"type": "integer"
},
"deactivateMissingUsers": {
"description": "Indicates whether to deactivate users that missing in current users' data collection",
"type": "boolean"
},
"updateOnlyPresentFields": {
"description": "Indicates whether to update only present fields in user's data. Currently this only works for addresses.",
"type": "boolean"
},
"sourceType": {
"description": "A prefix for the externalSystemId",
"type": "string"
},
"included": {
"description": "Entities that should be imported with users",
"javaType": "org.folio.rest.jaxrs.model.IncludedObjects",
"additionalProperties": false,
"type": "object",
"properties": {
"departments": {
"description": "Departments entities that should be imported with users",
"type": "array",
"uniqueItems": true,
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Department",
"description": "Department object schema",
"javaType": "org.folio.rest.jaxrs.model.Department",
"additionalProperties": true,
"properties": {
"id": {
"description": "A UUID identifying this department",
"example": "f973c3b6-85fc-4d35-bda8-f31b568957bf",
"readonly": true,
"excludedFromEqualsAndHashCode": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "uuid.schema",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
},
"name": {
"description": "The unique name of this department",
"type": "string",
"example": "Accounting"
},
"code": {
"description": "The unique code of this department",
"type": "string",
"example": "ACC"
}
},
"required": [
"name"
]
}
},
"customFields": {
"description": "Custom fields entities that should be updated with users",
"type": "array",
"uniqueItems": true,
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Custom Field",
"description": "Custom field item schema",
"javaType": "org.folio.rest.jaxrs.model.CustomField",
"additionalProperties": false,
"properties": {
"id": {
"description": "A UUID identifying this custom field",
"example": "f973c3b6-85fc-4d35-bda8-f31b568957bf",
"readonly": true,
"excludedFromEqualsAndHashCode": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "uuid.schema",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
},
"name": {
"type": "string",
"description": "The name of the custom field",
"example": "Department"
},
"refId": {
"type": "string",
"description": "The reference id of the custom field. Read only, autogenerated field",
"example": "department"
},
"type": {
"type": "string",
"description": "The type of the custom field",
"example": "RADIO_BUTTON",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Custom Field Types Schema",
"additionalProperties": false,
"enum": [
"RADIO_BUTTON",
"SINGLE_CHECKBOX",
"SINGLE_SELECT_DROPDOWN",
"MULTI_SELECT_DROPDOWN",
"TEXTBOX_SHORT",
"TEXTBOX_LONG",
"DATE_PICKER"
]
},
"entityType": {
"type": "string",
"description": "The entity type, the custom field is assigned to",
"example": "package"
},
"visible": {
"type": "boolean",
"description": "Defines visibility of the custom field",
"example": true
},
"required": {
"type": "boolean",
"description": "Defines if the custom field is required",
"example": true
},
"isRepeatable": {
"type": "boolean",
"description": "Defines if the custom field is repeatable",
"example": true
},
"order": {
"type": "integer",
"description": "The order of the custom field to be displayed",
"example": 1,
"readonly": true
},
"helpText": {
"type": "string",
"description": "The description of the custom field",
"example": "Provide a department"
},
"checkboxField": {
"type": "object",
"description": "Checkbox field properties",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Checkbox Field Schema",
"javaType": "org.folio.rest.jaxrs.model.CheckboxField",
"additionalProperties": false,
"properties": {
"default": {
"type": "boolean",
"description": "Defines if the custom field is default",
"example": false
}
}
},
"selectField": {
"type": "object",
"description": "Select field properties",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Select Field Schema",
"javaType": "org.folio.rest.jaxrs.model.SelectField",
"additionalProperties": false,
"properties": {
"multiSelect": {
"type": "boolean",
"description": "Defines if the custom field is a multi select",
"example": false,
"readonly": true
},
"options": {
"type": "object",
"description": "Defines the options for the custom field",
"$schema": "http://json-schema.org/draft-04/schema#",
"additionalProperties": false,
"javaType": "org.folio.rest.jaxrs.model.SelectFieldOptions",
"properties": {
"values": {
"type": "array",
"description": "Defines the possible values for the custom field",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Select Field Option",
"description": "Select Field Option Schema",
"additionalProperties": false,
"javaType": "org.folio.rest.jaxrs.model.SelectFieldOption",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the option",
"pattern": "opt_\\d{1,5}",
"example": "opt_1"
},
"value": {
"type": "string",
"description": "Possible value of the custom field",
"example": "Engineering"
},
"default": {
"type": "boolean",
"description": "Indicates that this value is default",
"default": false,
"example": false
}
},
"required": [
"value"
]
}
},
"sortingOrder": {
"type": "string",
"enum": [
"ASC",
"DESC",
"CUSTOM"
],
"description": "Defines sorting order for the custom field",
"example": "ASC"
}
},
"required": [
"values"
]
}
},
"required": [
"options"
]
},
"textField": {
"type": "object",
"description": "Text field properties",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Textbox Field Schema",
"javaType": "org.folio.rest.jaxrs.model.TextField",
"additionalProperties": false,
"properties": {
"fieldFormat": {
"type": "string",
"description": "Defines custom field format option",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"enum": [
"TEXT",
"EMAIL",
"URL",
"NUMBER"
],
"example": "EMAIL",
"default": "TEXT"
}
},
"required": [
"fieldFormat"
]
},
"metadata": {
"description": "User metadata information",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"type": "object",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"refId"
]
}
}
}
}
},
"required": [
"users",
"totalRecords"
]
}Example:
{
"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"
}
HTTP status code 200
Return OK
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Import Response Schema",
"description": "The response of the import",
"type": "object",
"properties": {
"message": {
"description": "Message stating that the import was successful or failed or the users were deactivated",
"type": "string"
},
"error": {
"description": "Error message stating why the import was failed",
"type": "string"
},
"createdRecords": {
"description": "Number of newly created users",
"type": "integer"
},
"updatedRecords": {
"description": "Number of updated users",
"type": "integer"
},
"failedRecords": {
"description": "Number of users failed to create/update",
"type": "integer"
},
"failedUsers": {
"description": "A list of users that were failed to create/update",
"type": "array",
"id": "failedUsers",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Failed User Schema",
"description": "Details of user that was failed on import",
"properties": {
"username": {
"description": "Username of failed user",
"type": "string"
},
"externalSystemId": {
"description": "External system ID of failed user",
"type": "string"
},
"errorMessage": {
"description": "Error message stating why the import was failed",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"username",
"externalSystemId"
]
}
},
"totalRecords": {
"description": "Number of total records processed by the user import",
"type": "integer"
}
},
"additionalProperties": false,
"required": [
"message",
"totalRecords"
]
}HTTP status code 500
Internal server error
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Import Response Schema",
"description": "The response of the import",
"type": "object",
"properties": {
"message": {
"description": "Message stating that the import was successful or failed or the users were deactivated",
"type": "string"
},
"error": {
"description": "Error message stating why the import was failed",
"type": "string"
},
"createdRecords": {
"description": "Number of newly created users",
"type": "integer"
},
"updatedRecords": {
"description": "Number of updated users",
"type": "integer"
},
"failedRecords": {
"description": "Number of users failed to create/update",
"type": "integer"
},
"failedUsers": {
"description": "A list of users that were failed to create/update",
"type": "array",
"id": "failedUsers",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Failed User Schema",
"description": "Details of user that was failed on import",
"properties": {
"username": {
"description": "Username of failed user",
"type": "string"
},
"externalSystemId": {
"description": "External system ID of failed user",
"type": "string"
},
"errorMessage": {
"description": "Error message stating why the import was failed",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"username",
"externalSystemId"
]
}
},
"totalRecords": {
"description": "Number of total records processed by the user import",
"type": "integer"
}
},
"additionalProperties": false,
"required": [
"message",
"totalRecords"
]
}