User Bulk API
Overview
The Bulk User API provides the capability to add, update, and delete users via bulk jobs.
Before you begin
Refer to How to Authenticate with Avaya Experience Platform™ APIs required to invoke User APIs.
User APIs require the Account Administrator role for access.
File Format Specification
- The first line of the file must be the header.
- All column values need to be provided.
- If no value, it should be left blank.
- Columns that accept arrays of values should be surrounded with square brackets
[ ]
- e.g.,
[Tenant Administrator,System Administrator]
- e.g.,
- Each user should be kept on its own row.
- Maximum file size is 2MB or 5,000 records, whichever comes first.
- Any whitespace around values will be trimmed.
- e.g.,
[ Agent , Administrator ]
will become[Agent,Administrator]
- e.g.,
Cleaning up Jobs
- It is the responsibility of the client to clean up jobs using Bulk Delete Jobs.
- Only jobs in the following states can be deleted:
COMPLETED
FAILED
ABORTED
- To clean up a running job you must first stop it with Stop Job.
- See Aborting Jobs for more details.
Aborting Jobs
- A running job can be stopped at any time with Stop Job.
- Once a client has requested a job be stopped it cannot be cancelled.
- The job will enter the
ABORT_IN_PROGRESS
status.
- The job will enter the
- When the job has been stopped it will have the status
ABORTED
. - Any processed users up to that point will remain as is, the changes are not rolled back.
- An
ABORTED
job cannot be restarted, any unprocessed users must be submitted as part of a new job.
Audit Records
To retrieve the audit-records
see the Audit Records on the User API.
Step-by-Step Guide
In this step-by-step guide we will cover how to Bulk Add Users however the same flow of steps can be applied to the Bulk Update Users, Bulk Delete Users, and Bulk Export Users.
At a high-level the steps are:
- Download the Bulk Template
- Not required for Bulk Export Users
- Submit the Users for Processing
- Not required for Bulk Export Users
- Monitor the status of the Job
- Optionally, monitor the status of the Users
- Check the final status of the Job
- Optionally, export the failed Users
- Optionally, resubmit the failed Users
Step 1: Download the Bulk Template
The first step is to download the bulk template which is provided in the file format .xlsx
. This can be downloaded straight from the Download Bulk Template API.
Note, the same template can be used for all of the bulk jobs; add, update, and delete.
GET /users-bulk-template
/v1/accounts/ABCDEF/users-bulk-template
HTTP 200 OK
File Download as .xlsx
You should fill in the template with the details of the users you wish to add and each user should appear on its own row.
The template will contain the following columns:
Column | Type | Example | Description |
---|---|---|---|
Login Id | String | [email protected] | Login Id for the user. |
Account Hierarchy | String | ABCDEF | Unique Id for Account or Node to assign the user. |
Last Name | String | Stevens | Last name of the user. |
First Name | String | Alex | First name of the user. |
Display Name | String | Stevens, Alex | Display name of the user. |
String | [email protected] | Email Id of the user. | |
Password | String | Aghtat2343$ | Login credentials of the user. |
Profile | String | FSADSJ | The unique 6 character internal id that represents the profile. |
Roles | Array of Strings (comma-separated) | [Agent,Business Analyst] | Roles assigned to user. |
Member Of | Array of Strings (comma-separated) | [04703a3a-3dfb-4606-ae79-fd0fe0be3e64,9437ccc3-fb71-4142-bc77-d3b5a23bd3d6] | List of the groups of which the user is member of. |
Owner Groups | Array of Strings (comma-separated) | [05603a3a-3dfb-4606-ae79-fd0fe0be2e52,f908ac1f-b7d1-41d9-a304-5f20f424832d] | List of the groups owned by the user. |
Step 1: Bulk Adding Users
Once you've completed adding users to the template the next step is to upload the .xlsx
file to the API.
Optionally, a unique jobName
can be provided at this stage. This will appear in the List Jobs API and can be used for filtering and ordering.
POST /users:bulkAdd
/v1/accounts/ABCDEF/users:bulkAdd?jobName=Bulk%20Job
Request Body:
File Upload .xlsx
If the contents of the file passes the initial validation checks then you'll receive a response containing the jobId
and url
.
HTTP 202 Accepted
{
"jobId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
"url": "https://example.avayacloud.com/api/admin/user/v1/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe"
}
Error Handling
In the event that the file fails the initial validation checks you'll receive one of the responses documented below. No job will be created in these cases.
If the file is missing any of the required fields then a HTTP 400 Bad Request will be returned:
{
"type": "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#constraint-violation",
"status": 400,
"violations": [
{
"field": "file",
"message": "One or more mandatory fields missing in request",
"code": 11020
}
],
"title": "Constraint Violation"
}
If the file contains any unknown fields then a HTTP 400 Bad Request will be returned:
{
"type": "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#constraint-violation",
"status": 400,
"violations": [
{
"field": "file",
"message": "Non supported header present in file",
"code": 11048
}
],
"title": "Constraint Violation"
}
Step 2: Checking the Job Status
During the execution of a job you should periodically check its status by polling the Get Job API.
GET /jobs/{jobId}
/v1/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe
In the response you will receive the current status of the job. This will contain details on the number of users that have been processed and the total number of users submitted for processing.
HTTP 200 OK
{
"status": "IN_PROGRESS",
"message": "Import in-progress",
"details": [
{
"count": 15,
"operation": "ADD"
}
],
"url": "https://example.avayacloud.com/api/admin/user/v1/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe/users",
"totalCount": 45,
"startTime": "2020-04-21T17:32:28z"
}
Explanation of Job Statuses
State | End Status | Description |
---|---|---|
IN_PROGRESS | No | The job is currently in progress. |
PENDING | No | The job will start after the previous profile update job has completed. |
COMPLETED | Yes | The job completed successfully. |
FAILED | Yes | The job failed, 1 or more users could not be processed. |
ABORT_IN_PROGRESS | No | The job is currently being aborted. |
ABORTED | Yes | The job was aborted by the client. |
Step 3: Checking the User Statuses
During the execution of a job you can periodically check the status of the users by polling the List Users API. This is a paginated API.
GET /jobs/{jobId}/users
/v1/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe/users?pageNumber=1&pageSize=3
In the response you will receive the current status of the users being processed.
Note, the order of the users in the response is not guaranteed to match their order in the input file. You can use the optional
orderBy
parameter to order the users in a more predictable manner.
HTTP 200 OK
{
"pagination": {
"pageNumber": 2,
"pageSize": 3,
"total": 45
},
"users": [
{
"loginId": "[email protected]",
"userId": "c8c2909d-75e9-484a-94c0-b7e8d30771ee",
"operation": "ADD",
"status": "COMPLETED",
"message": "User successfully added"
},
{
"loginId": "[email protected]",
"userId": "c7c2909d-75e9-484a-94c0-b7e8d30772dd",
"operation": "ADD",
"status": "IN_PROGRESS",
"message": "Operation is in progress"
},
{
"loginId": "[email protected]",
"userId": "b7c2909d-75e9-484a-94c0-b7e8d30771cc",
"operation": "ADD",
"status": "FAILED",
"message": "Invalid member of group provided"
}
],
"links": {
"prev": "https://example.avayacloud.com/api/admin/user/v1/accounts/ABCDEF/jobs/importUserList1/users?pageNumber=1&pageSize=3",
"next": "https://example.avayacloud.com/api/admin/user/v1/accounts/ABCDEF/jobs/importUserList1/users?pageNumber=3&pageSize=3"
}
}
Step 4: Job has Finished Processing
When a job has finished processing it will end in 1 of 3 statuses:
COMPLETED
- All the users were successfully processed.
FAILED
- One or more users could not be processed.
ABORTED
- The job was aborted by the client.
GET /jobs/{jobId}
/v1/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe
In our example the job has ended with the FAILED
status, in this case we will need to take a number of extra steps to resubmit the FAILED
users.
HTTP 200 OK
{
"operation": "ADD",
"status": "FAILED",
"message": "Import failed",
"details": [
{
"count": 40,
"status": "COMPLETED"
},
{
"count": 5,
"status": "FAILED"
},
],
"url": "https://example.avayacloud.com/api/admin/user/v1/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe/users",
"totalCount": 45,
"startTime": "2020-04-21T17:32:28z",
"endTime": "2020-04-21T17:40:28z"
}
Step 5a: Exporting the Failed Users
When a job ends with the status FAILED
you will need to export the list of all the users that could not be processed by the previous job.
This API will return the list of failed users in a .xlsx
file in a zip archive. You should edit this file directly and resubmit it as part of a new job, follow steps 2 - 4 again.
GET /jobs/{jobId}:exportFailedUsers
/v1/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe:exportFailedUsers
HTTP 200 OK
File Download .xlsx within .zip
Updated about 7 hours ago