http://github.com/org/folio/mod-users
This documents the API calls that can be made to query and manage staging users of the system
Collection of staging-user items.
Return a list of staging-users
GET /staging-users
A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
email=abc@testEmail.com sortBy contactInfo.email
Order by field: field A, field B
Order
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
none
Skip over a number of elements by specifying an offset value for the query
Example:
0
Limit the number of elements returned in the response
Example:
10
Returns a list of staging-user items
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Collection of staging users",
"properties": {
"staging_users": {
"description": "List of userdata items",
"type": "array",
"id": "stagingUsersData",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Staging User Information Schema",
"description": "A staging user",
"javaName": "StagingUser",
"properties": {
"id": {
"description": "A globally unique (UUID) identifier for the user",
"type": "string"
},
"isEmailVerified": {
"description": "A flag to determine if a patron is activated.",
"type": "boolean"
},
"minor": {
"description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
"type": "boolean"
},
"status": {
"type": "string",
"description": "whether tier-1 or tier-2",
"enum": [
"TIER-1",
"TIER-2"
]
},
"externalSystemId": {
"description": "A unique ID (UUID) that corresponds to an external authority",
"type": "string"
},
"generalInfo": {
"type": "object",
"description": "General info of staging user",
"properties": {
"firstName": {
"type": "string",
"description": "The staging user's given name"
},
"preferredFirstName": {
"type": "string",
"description": "The user's preferred name"
},
"middleName": {
"type": "string",
"description": "The staging user's middle name (if any)"
},
"lastName": {
"type": "string",
"description": "The staging user's surname"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
},
"addressInfo": {
"type": "object",
"description": "Primary address info of staging user",
"properties": {
"addressLine0": {
"type": "string",
"description": "Address, Line 0"
},
"addressLine1": {
"type": "string",
"description": "Address, Line 1"
},
"city": {
"type": "string",
"description": "City name"
},
"province": {
"type": "string",
"description": "Province"
},
"zip": {
"type": "string",
"description": "Zip Code"
},
"country": {
"type": "string",
"description": "Country"
}
},
"additionalProperties": false
},
"contactInfo": {
"type": "object",
"description": "Contact info of staging user",
"properties": {
"phone": {
"type": "string",
"description": "The user's primary phone number"
},
"mobilePhone": {
"type": "string",
"description": "The user's mobile phone number"
},
"email": {
"type": "string",
"description": "The user's email address",
"format": "email"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"preferredEmailCommunication": {
"type": "array",
"description": "Email communication info of staging user",
"items": {
"type": "string",
"enum": [
"Support",
"Programs",
"Services"
]
},
"maxItems": 3,
"uniqueItems": true
},
"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"
]
}
},
"required": [
"generalInfo",
"contactInfo"
],
"additionalProperties": false
}
},
"totalRecords": {
"type": "integer",
"description": "Estimated or exact total number of records, see https://github.com/folio-org/raml-module-builder#estimated-totalrecords for details"
},
"resultInfo": {
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "resultInfo.schema",
"description": "Faceting of result sets",
"type": "object",
"properties": {
"totalRecords": {
"type": "integer",
"description": "Estimated or exact total number of records"
},
"totalRecordsEstimated": {
"type": "boolean",
"description": "True if totalRecords is an estimation, false if it is the exact number"
},
"totalRecordsRounded": {
"type": "integer",
"description": "The rounded value of totalRecords if totalRecords is an estimation"
},
"responseTime": {
"type": "number",
"description": "Response time"
},
"facets": {
"type": "array",
"description": "Array of facets",
"items": {
"type": "object",
"description": "A facet",
"properties": {
"facetValues": {
"type": "array",
"description": "Array of facet values",
"items": {
"type": "object",
"description": "A facet value",
"properties": {
"count": {
"type": "integer",
"description": "Count of facet values"
},
"value": {
"description": "Value Object"
}
}
},
"additionalProperties": false
},
"type": {
"type": "string",
"description": "Type of facet"
}
},
"additionalProperties": false
}
},
"diagnostics": {
"type": "array",
"description": "Array of diagnostic information",
"items": {
"type": "object",
"description": "Diagnostic information",
"properties": {
"source": {
"type": "string",
"description": "Source reporting the diagnostic information"
},
"code": {
"type": "string",
"description": "Diagnostic Code"
},
"message": {
"type": "string",
"description": "Diagnostic Message"
},
"module": {
"type": "string",
"description": "Module reporting diagnostic information"
},
"recordCount": {
"type": "integer",
"description": "Record Count for diagnostics"
},
"query": {
"type": "string",
"description": "CQL Query associated with results"
}
}
}
}
},
"additionalProperties": false
}
},
"required": [
"users",
"totalRecords"
]
}
Example:
{
"staging_users": [
{
"id": "362399c3-dad4-49c5-880a-a65823312065",
"isEmailVerified": false,
"status": "TIER-1",
"externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
"generalInfo": {
"firstName": "test1",
"preferredFirstName": "New Record",
"middleName": "www",
"lastName": "new-record-1"
},
"addressInfo": {
"addressLine0": "123 Main St",
"addressLine1": "Apt 4B",
"city": "Metropolis",
"province": "NY",
"zip": "12345",
"country": "USA"
},
"contactInfo": {
"phone": "555-123456",
"mobilePhone": "555-5678",
"email": "new-record-kapil.1.2@test.com"
},
"preferredEmailCommunication": [
"Support",
"Programs",
"Services"
],
"metadata": {
"createdDate": "2024-10-14T09:40:50.311+00:00",
"createdByUserId": "21457ab5-4635-4e56-906a-908f05e12345",
"updatedDate": "2024-10-14T09:41:50.653+00:00",
"updatedByUserId": "21457ab5-4635-4e56-906a-908f05e12345"
}
}
],
"totalRecords": 1
}
Bad request
Media type: text/plain
Type: any
Example:
Bad request
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list staging-users -- unauthorized
Access denied
Media type: text/plain
Type: any
Example:
Access denied
Internal server error
Media type: text/plain
Type: any
Example:
Internal server error
Create a user
POST /staging-users
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Staging User Information Schema",
"description": "A staging user",
"javaName": "StagingUser",
"type": "object",
"properties": {
"id": {
"description": "A globally unique (UUID) identifier for the user",
"type": "string"
},
"isEmailVerified": {
"description": "A flag to determine if a patron is activated.",
"type": "boolean"
},
"minor": {
"description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
"type": "boolean"
},
"status": {
"type": "string",
"description": "whether tier-1 or tier-2",
"enum": [
"TIER-1",
"TIER-2"
]
},
"externalSystemId": {
"description": "A unique ID (UUID) that corresponds to an external authority",
"type": "string"
},
"generalInfo": {
"type": "object",
"description": "General info of staging user",
"properties": {
"firstName": {
"type": "string",
"description": "The staging user's given name"
},
"preferredFirstName": {
"type": "string",
"description": "The user's preferred name"
},
"middleName": {
"type": "string",
"description": "The staging user's middle name (if any)"
},
"lastName": {
"type": "string",
"description": "The staging user's surname"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
},
"addressInfo": {
"type": "object",
"description": "Primary address info of staging user",
"properties": {
"addressLine0": {
"type": "string",
"description": "Address, Line 0"
},
"addressLine1": {
"type": "string",
"description": "Address, Line 1"
},
"city": {
"type": "string",
"description": "City name"
},
"province": {
"type": "string",
"description": "Province"
},
"zip": {
"type": "string",
"description": "Zip Code"
},
"country": {
"type": "string",
"description": "Country"
}
},
"additionalProperties": false
},
"contactInfo": {
"type": "object",
"description": "Contact info of staging user",
"properties": {
"phone": {
"type": "string",
"description": "The user's primary phone number"
},
"mobilePhone": {
"type": "string",
"description": "The user's mobile phone number"
},
"email": {
"type": "string",
"description": "The user's email address",
"format": "email"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"preferredEmailCommunication": {
"type": "array",
"description": "Email communication info of staging user",
"items": {
"type": "string",
"enum": [
"Support",
"Programs",
"Services"
]
},
"maxItems": 3,
"uniqueItems": true
},
"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"
]
}
},
"required": [
"generalInfo",
"contactInfo"
],
"additionalProperties": false
}
Example:
{
"isEmailVerified": false,
"status": "TIER-1",
"externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
"generalInfo": {
"firstName": "test1",
"middleName": "www",
"lastName": "new-record-1"
},
"addressInfo": {
"addressLine0": "123 Main St",
"addressLine1": "Apt 4B",
"city": "Metropolis",
"province": "NY",
"zip": "12345",
"country": "USA"
},
"contactInfo": {
"phone": "555-123456",
"mobilePhone": "555-5678",
"email": "new-record-kapil_new1@test.com"
},
"preferredEmailCommunication": [
"Programs",
"Support",
"Services"
]
}
when new staging user record is created
URI to the created staging-user item
Media type: application/json
Type: any
Example:
{
"isEmailVerified": false,
"status": "TIER-1",
"externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
"generalInfo": {
"firstName": "test1",
"middleName": "www",
"lastName": "new-record-1"
},
"addressInfo": {
"addressLine0": "123 Main St",
"addressLine1": "Apt 4B",
"city": "Metropolis",
"province": "NY",
"zip": "12345",
"country": "USA"
},
"contactInfo": {
"phone": "555-123456",
"mobilePhone": "555-5678",
"email": "new-record-kapil_new1@test.com"
},
"preferredEmailCommunication": [
"Programs",
"Support",
"Services"
]
}
Bad request
Media type: application/json
Type: any
Media type: text/plain
Type: any
Example:
"unable to add staging-user -- malformed JSON at 13:3"
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to create staging-users -- unauthorized
Validation error
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Update an existing user based on externalSystemId
PUT /staging-users/{externalSystemId}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Staging User Information Schema",
"description": "A staging user",
"javaName": "StagingUser",
"type": "object",
"properties": {
"id": {
"description": "A globally unique (UUID) identifier for the user",
"type": "string"
},
"isEmailVerified": {
"description": "A flag to determine if a patron is activated.",
"type": "boolean"
},
"minor": {
"description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
"type": "boolean"
},
"status": {
"type": "string",
"description": "whether tier-1 or tier-2",
"enum": [
"TIER-1",
"TIER-2"
]
},
"externalSystemId": {
"description": "A unique ID (UUID) that corresponds to an external authority",
"type": "string"
},
"generalInfo": {
"type": "object",
"description": "General info of staging user",
"properties": {
"firstName": {
"type": "string",
"description": "The staging user's given name"
},
"preferredFirstName": {
"type": "string",
"description": "The user's preferred name"
},
"middleName": {
"type": "string",
"description": "The staging user's middle name (if any)"
},
"lastName": {
"type": "string",
"description": "The staging user's surname"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
},
"addressInfo": {
"type": "object",
"description": "Primary address info of staging user",
"properties": {
"addressLine0": {
"type": "string",
"description": "Address, Line 0"
},
"addressLine1": {
"type": "string",
"description": "Address, Line 1"
},
"city": {
"type": "string",
"description": "City name"
},
"province": {
"type": "string",
"description": "Province"
},
"zip": {
"type": "string",
"description": "Zip Code"
},
"country": {
"type": "string",
"description": "Country"
}
},
"additionalProperties": false
},
"contactInfo": {
"type": "object",
"description": "Contact info of staging user",
"properties": {
"phone": {
"type": "string",
"description": "The user's primary phone number"
},
"mobilePhone": {
"type": "string",
"description": "The user's mobile phone number"
},
"email": {
"type": "string",
"description": "The user's email address",
"format": "email"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"preferredEmailCommunication": {
"type": "array",
"description": "Email communication info of staging user",
"items": {
"type": "string",
"enum": [
"Support",
"Programs",
"Services"
]
},
"maxItems": 3,
"uniqueItems": true
},
"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"
]
}
},
"required": [
"generalInfo",
"contactInfo"
],
"additionalProperties": false
}
when staging user record is updated
Media type: application/json
Type: any
Bad request
Media type: application/json
Type: any
Staging user with a given externalSystemID not found
Media type: text/plain
Type: any
Example:
Staging user not found
Internal server error, e.g. due to missing externalSystemId in the parameter
Media type: text/plain
Type: any
Example:
the request's HTTP method is not supported by the server or the resource
Validation error
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
create a new user or update a existing user with staging user details
PUT /staging-users/{id}/mergeOrCreateUser
User ID
New user merged/created from staging user successfully
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "stagingUser response after merge",
"javaName": "StagingUserMergeResponse",
"type": "object",
"properties": {
"userId": {
"description": "The UUID of the newly merged/created user",
"type": "string"
}
},
"additionalProperties": false
}
Example:
{
"userId": "7261ecaae3a74dc68b468e12a70b1aec"
}
Not found
Media type: text/plain
Type: any
Internal error
Media type: text/plain
Type: any