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]
• 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]

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.
• 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:

1. Download the Bulk Template
   1. Not required for Bulk Export Users
2. Submit the Users for Processing
   1. Not required for Bulk Export Users
3. Monitor the status of the Job
   1. Optionally, monitor the status of the Users
4. Check the final status of the Job
   1. Optionally, export the failed Users
   2. 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

/v1beta/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:

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

/v1beta/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/v1beta/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}

/v1beta/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/v1beta/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe/users",
  "totalCount": 45,
  "startTime": "2020-04-21T17:32:28z"
}

Explanation of Job Statuses

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

/v1beta/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/v1beta/accounts/ABCDEF/jobs/importUserList1/users?pageNumber=1&pageSize=3",
    "next": "https://example.avayacloud.com/api/admin/user/v1beta/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:

1. COMPLETED
   • All the users were successfully processed.
2. FAILED
   • One or more users could not be processed.
3. ABORTED
   • The job was aborted by the client.

GET /jobs/{jobId}

/v1beta/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/v1beta/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

/v1beta/accounts/ABCDEF/jobs/c8c2909d-75e9-484a-94c0-b7e8d30771fe:exportFailedUsers

HTTP 200 OK

File Download .xlsx within .zip