User import (v1)

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

Table of contents

mod-user-import API

This documents the API calls that can be made to import users into the system

/user-import

POST /user-import

Create or update a list of users

POST /user-import
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",
        "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": "An ID that corresponds to an external authority",
            "type": "string"
          },
          "barcode": {
            "description": "The library barcode for this user",
            "type": "string"
          },
          "active": {
            "description": "A flag to determine if a user can log in, take out loans, etc.",
            "type": "boolean"
          },
          "type": {
            "description": "The class of user",
            "type": "string"
          },
          "patronGroup": {
            "description": "A name of the corresponding group the user belongs to",
            "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": {
              "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": "A name of the corresponding address type",
                      "type": "string"
                    },
                    "primaryAddress": {
                      "description": "Is this the user's primary address?",
                      "type": "boolean"
                    }
                  },
                  "additionalProperties": false
                }
              },
              "preferredContactTypeId": {
                "description": "Name of user's preferred contact type",
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "lastName"
            ]
          },
          "enrollmentDate": {
            "description": "The date when the user joined the organization",
            "type": "string",
            "format": "date-time"
          },
          "expirationDate": {
            "description": "The date 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": {
            "description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "title": "Metadata Schema",
            "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"
            ]
          },
          "customFields": {
            "description": "Object that contains custom field",
            "type": "object",
            "additionalProperties": true
          },
          "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#",
                "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#",
                "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#",
                "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#",
                "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"
            ]
          },
          "departments": {
            "description": "Names of departments the user belongs to",
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string"
            }
          }
        },
        "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",
      "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#",
                "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#",
                "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"
                ]
              },
              "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#",
                "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"
}

Response 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"
  ]
}

Response 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"
  ]
}