Avaya Experience Platform™Avaya Enterprise Cloud™

Users

This page talks about User Management in Avaya Experience Platform™.

Suggest Edits

Overview

The Users API provides access to User Management via a REST API interface.

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.

Overview

A contact center User assumes one of these personas:

  • Agent and Supervisor responsible for handling calls, chats, messages and emails.
  • Administrator responsible for contact center administration and operations.

Avaya Experience Platform™ simplifies User configuration through these methods:

  • Profiles - provides a pre-configured template for contact center features (chat, messaging, email), routing attributes, roles and group memberships.
    • Account Administrators can use out of the box Profiles or create new ones to provision users efficiently.

Profiles

A Profile can be used to provide a pre-configured template to apply common configuration, features, roles, and group memberships to Users.

  • For example, if an Account Administrator needed to provision 1000 Users all with the same set of features they could create a common Profile.
  • After creating the Profile, they could apply it to each User either during their creation or later via an update.

Once a Profile is applied to a User they will receive any updates that are applied to that Profile in real-time.

  • For example, if an Account Administrator created a Profile that only had voice enabled but later added chat.
  • The Users with that Profile applied would receive the chat feature.

Creating a Profile

To create a new Profile you should invoke Create Profile. You should provide basic details such as a profileName and description. It is recommended to have descriptive and meaningful names that convey the Profile's purpose. For example, Digital-Only-Agent-Profile, Omnichannel-Agent-Profile, etc.

  • Agent to Supervisor association is achieved through a Group.

    • When creating a Profile for an Agent, use the memberOf field to specify a group the agent should be automatically added to.
    • The ID of the Group can be queried from Avaya Experience Platform™ Group API.

  • Use the roles field to specify the role names that users with this Profile are associated with.

    • For example, a Profile for an agent type User must have the role Agent.
    • See the list of Available Roles.

  • Use the features field to enable and configure the contact center features and routing attributes.

    • The available features will depend on the Avaya Experience Platform™ subscription you have purchased.
    • Any changes to the features field will trigger asynchronous updates, the progress of which should be tracked by polling the List Profile Statuses.

POST /profiles

/v1/accounts/ABCDEF/profiles

Request Body:

{
  "profileName": "Advanced",
  "description": "A profile with all the features",
  "uxProfileId": "6f482dcd-54a9-445f-ba6d-8ca5ebd5261a",
  "roles": [
    "Agent"
  ],
  "memberOfGroups": [
    "c8c2909d-75e9-484a-94c0-b7e8d29771fe"
  ],
  "features": {
    "matching": {
      "attributes": [
        "Language.English",
        "Language.French"
      ],
      "queues": [
        {
          "queueId": "620bbb28-7112-433a-af59-17ee0f15a247",
          "proficiency": 10
        }
      ]
    },
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

After the Profile has been created you will receive a profileId in the response that you should use in all subsequent requests related to that Profile.

HTTP 202 Accepted

{
  "profileId": "TELHGZ",
  "profileName": "Advanced",
  "description": "A profile with all the features",
  "uxProfileId": "6f482dcd-54a9-445f-ba6d-8ca5ebd5261a",
  "roles": [
    "Agent"
  ],
  "memberOfGroups": [
    "c8c2909d-75e9-484a-94c0-b7e8d29771fe"
  ],
  "features": {
    "matching": {
      "attributes": [
        "Language.English",
        "Language.French"
      ],
      "queues": [
        {
          "queueId": "620bbb28-7112-433a-af59-17ee0f15a247",
          "proficiency": 10
        }
      ]
    },
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

Status Changes

The status on the List Profile Statuses for this Profile would go through the following changes:

1. Add In-Progress

[
  {
    "action": "ADD",
    "status": "IN_PROGRESS",
    "message": "Operation is in progress",
    "profileId": "TELHGZ",
    "features": {
      "voice": {
        "action": "ADD",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Add Completed

[
  {
    "action": "ADD",
    "status": "COMPLETED",
    "message": "Completed successfully",
    "profileId": "TELHGZ",
    "features": {
      "voice": {
        "action": "ADD",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below.

  • A client should re-attempt any failed features using the Update Profile.

Add Failed

[
  {
    "action": "ADD",
    "status": "FAILED",
    "message": "Operation failed",
    "profileId": "TELHGZ",
    "features": {
      "voice": {
        "action": "ADD",
        "status": "FAILED",
        "message": "The feature could not be added"
      }
    }
  }
]

Updating a Profile

  • Any changes to the features field will trigger asynchronous updates, the progress of which should be tracked by polling the List Profile Statuses.

Adding a new Feature

To add a new feature, e.g. chat, to an existing Profile you should invoke Update Profile and include all the details of the Profile plus the new feature.

The same basic principle applies to any updates made to a Profile. It is treated as a complete replacement.

PUT /profiles/{profileId}

/v1/accounts/ABCDEF/profiles/TELHGZ

Request Body:

{
  "profileName": "Advanced",
  "description": "A profile with all the features",
  "uxProfileId": "6f482dcd-54a9-445f-ba6d-8ca5ebd5261a",
  "roles": [
    "Agent"
  ],
  "memberOfGroups": [
    "c8c2909d-75e9-484a-94c0-b7e8d29771fe"
  ],
  "features": {
    "matching": {
      "attributes": [
        "Language.English",
        "Language.French"
      ],
      "queues": [
        {
          "queueId": "620bbb28-7112-433a-af59-17ee0f15a247",
          "proficiency": 10
        }
      ]
    },
    "chat": {
      "autoAnswer": false,
      "multiplicity": 5,
      "afterContactWork": false
    },
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

After the update you will see the new chat feature added to the features section.

HTTP 202 Accepted

{
  "profileId": "TELHGZ",
  "profileName": "Advanced",
  "description": "A profile with all the features",
  "uxProfileId": "6f482dcd-54a9-445f-ba6d-8ca5ebd5261a",
  "roles": [
    "Agent"
  ],
  "memberOfGroups": [
    "c8c2909d-75e9-484a-94c0-b7e8d29771fe"
  ],
  "features": {
    "matching": {
      "attributes": [
        "Language.English",
        "Language.French"
      ],
      "queues": [
        {
          "queueId": "620bbb28-7112-433a-af59-17ee0f15a247",
          "proficiency": 10
        }
      ]
    },
    "chat": {
      "autoAnswer": false,
      "multiplicity": 5,
      "afterContactWork": false
    },
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

Status Changes

The status on the List Profile Statuses for this Profile would go through the following changes:

1. Add In-Progress

[
  {
    "action": "ADD",
    "status": "IN_PROGRESS",
    "message": "Operation is in progress",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "ADD",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Add Completed

[
  {
    "action": "ADD",
    "status": "COMPLETED",
    "message": "Completed successfully",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "ADD",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below.

  • A client should re-attempt any failed features using the Update Profile.

Add Failed

[
  {
    "action": "ADD",
    "status": "FAILED",
    "message": "Operation failed",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "ADD",
        "status": "FAILED",
        "message": "The feature could not be added"
      }
    }
  }
]

Removing an existing Feature

To remove an existing feature, e.g. chat, from a Profile you should invoke Update Profile and include all the details of the Profile minus the feature you wish to remove.

The same basic principle applies to any updates made to a Profile. It is treated as a complete replacement.

PUT /profiles/{profileId}

/v1/accounts/ABCDEF/profiles/TELHGZ

Request Body:

{
  "profileName": "Advanced",
  "description": "A profile with all the features",
  "uxProfileId": "6f482dcd-54a9-445f-ba6d-8ca5ebd5261a",
  "roles": [
    "Agent"
  ],
  "memberOfGroups": [
    "c8c2909d-75e9-484a-94c0-b7e8d29771fe"
  ],
  "features": {
    "matching": {
      "attributes": [
        "Language.English",
        "Language.French"
      ],
      "queues": [
        {
          "queueId": "620bbb28-7112-433a-af59-17ee0f15a247",
          "proficiency": 10
        }
      ]
    },
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

After the update you will see the chat feature has been removed from the features section.

HTTP 202 Accepted

{
  "profileId": "TELHGZ",
  "profileName": "Advanced",
  "description": "A profile with all the features",
  "uxProfileId": "6f482dcd-54a9-445f-ba6d-8ca5ebd5261a",
  "roles": [
    "Agent"
  ],
  "memberOfGroups": [
    "c8c2909d-75e9-484a-94c0-b7e8d29771fe"
  ],
  "features": {
    "matching": {
      "attributes": [
        "Language.English",
        "Language.French"
      ],
      "queues": [
        {
          "queueId": "620bbb28-7112-433a-af59-17ee0f15a247",
          "proficiency": 10
        }
      ]
    },
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

Status Changes

The status on the List Profile Statuses for this Profile would go through the following changes:

1. Delete In-Progress

[
  {
    "action": "DELETE",
    "status": "IN_PROGRESS",
    "message": "Operation is in progress",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "DELETE",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Delete Completed

[
  {
    "action": "DELETE",
    "status": "COMPLETED",
    "message": "Completed successfully",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "DELETE",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below.

  • A client should re-attempt any failed features using the Update Profile.

Delete Failed

[
  {
    "action": "DELETE",
    "status": "FAILED",
    "message": "Operation failed",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "DELETE",
        "status": "FAILED",
        "message": "The feature could not be delete"
      }
    }
  }
]

Deleting a Profile

To delete a Profile you should invoke Delete Profile. No response body is returned from this request.

DELETE /profiles/{profileId}

/v1/accounts/ABCDEF/profiles/TELHGZ

HTTP 204 No Content

After a Profile has been deleted Get Profile will return HTTP 404 Not Found. The status of the Profile will no longer be available via List Profile Statuses as it no longer exists.

Status Changes

The status on the List Profile Statuses for this Profile would go through the following changes:

1. Delete In-Progress

[
  {
    "action": "DELETE",
    "status": "IN_PROGRESS",
    "message": "Operation is in progress",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "DELETE",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Delete Completed

[
  {
    "action": "DELETE",
    "status": "COMPLETED",
    "message": "Completed successfully",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "DELETE",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below. If there is a failure a delete can be re-attempted.

Delete Failed

[
  {
    "action": "DELETE",
    "status": "FAILED",
    "message": "Operation failed",
    "profileId": "TELHGZ",
    "features": {
      "chat": {
        "action": "DELETE",
        "status": "FAILED",
        "message": "The feature could not be delete"
      }
    }
  }
]


Users

Represents a User in the organization. A User can be an Agent, Supervisor or an Administrator.

  1. Agent
    1. An Agent represents the person who handles incoming or outgoing customer engagements with the business.
    2. This is by far the most common User type that you will create.
  2. Supervisor
    1. A Supervisor can get involved in customer engagements through monitoring, reporting or escalation.
  3. Administrator
    1. Responsible for contact center administration and operations.

Types of User

For all User types you should remember:

  • To provide basic User details such as loginId, firstName, lastName.
  • When using Enterprise IDP for authentication the password field should be left empty.
  • To provide the accountId as the organizationNodeId that this User should be added to.

Agent

An Agent represents the person who handles incoming or outgoing customer engagements with the business. The Agent creation process is greatly simplified by using a Profile to setup the contact center features and memberships.

When creating an Agent you should remember:

  • An Agent must have the role Agent assigned.
  • Optionally, provide a profileId to assign features and roles through a Profile.
  • Optionally, customize the features field to assign any additional features.

Supervisor

A Supervisor can get involved in customer engagements through monitoring, reporting or escalation. The Supervisor creation process can be simplified by assigning a Profile with the Supervisor role.

When creating a Supervisor you should remember:

  • A Supervisor must have the role Supervisor assigned.
  • Optionally, provide a profileId to assign features and roles through a Profile.
  • Optionally, customize the features field to assign any additional features.
  • Use the ownedGroups field to assign a group of Agents to a Supervisor. The IDs of the groups containing Agents can be queried from Avaya Experience Platform™ Group API.

Administrator

Unlike Agents and Supervisors, Administrators do not require contact center features.

When creating a Administrator you should remember:

  • Administrators have different personas.
    • Select roles like Administrator, Reporting_Administrator, Workspaces Admin Widgets Administrator, etc. to associate an Administrator with one or more personas.

Creating a User

To create a new User you should invoke Create User. The fields that you supply will depend on the type of User you wish to create.

  • Any changes to the roles or features field will trigger asynchronous updates, the progress of which should be tracked by polling the List User Statuses.
  • Changes to roles are atomic. For example:
    • Given ["Agent", "Business Analyst]"
    • If for the Agent role cannot be assigned then neither will the Business Analyst role.
    • In these cases the status for role on the List User Statuses will appear as FAILED and the message will continue the specific reason for the failure.

The most basic User can be created using:

  • organizationNodeId
  • loginId
  • password
    • This is a write-only field and will not appear in any responses.
  • lastName
  • firstName

POST /users

/v1/accounts/ABCDEF/users

Request Body:

{
  "organizationNodeId": "EXMPLE",
  "loginId": "[email protected]",
  "password": "ucP69e3sCw9%",
  "lastName": "Stevens",
  "firstName": "Alex",
  "roles": [
    "Agent",
    "Business Analyst"
  ],
  "features": {
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

After the User has been created you will receive a userId in the response that you should use in all subsequent requests related to that User.

HTTP 202 Accepted

{
  "userId": "c8c2909d-75e9-484a-94c0-b7e8d29771fe",
  "organizationNodeId": "EXMPLE",
  "loginId": "[email protected]",
  "lastName": "Stevens",
  "firstName": "Alex",
  "roles": [
    "Agent",
    "Business Analyst"
  ],
  "features": {
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false,
      "userExtension": "10021",
      "emergencyLocationIdentificationNumber": "7798098090",
      "providers": [
        {
          "providerAgentId": "0585aad8-decd-402c-b13f-bc05bd989fca",
          "channelProviderId": "a8b6d39c-53c5-4d94-a640-c28bee987ed7"
        }
      ]
    }
  }
}

Status Changes

The status on the List User Statuses for this User would go through the following changes:

1. Add In-Progress

[
  {
    "action": "ADD",
    "status": "IN_PROGRESS",
    "message": "Operation is in progress",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "role": {
      "action": "ADD",
      "status": "IN_PROGRESS",
      "message": "Operation is in progress"
    },
    "features": {
      "voice": {
        "action": "ADD",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Add Completed

[
  {
    "action": "ADD",
    "status": "COMPLETED",
    "message": "Completed successfully",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "role": {
      "action": "ADD",
      "status": "COMPLETED",
      "message": "Added successfully"
    },
    "features": {
      "voice": {
        "action": "ADD",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below.

  • A client should re-attempt any failed roles or features using the Update User.

Add Failed

[
  {
    "action": "ADD",
    "status": "FAILED",
    "message": "Operation failed",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "role": {
      "action": "ADD",
      "status": "FAILED",
      "message": "The requested roles could not be added"
    },
    "features": {
      "voice": {
        "action": "ADD",
        "status": "Failed",
        "message": "The feature could not be added"
      }
    }
  }
]

Applying a Profile to a User

A Profile can be applied to a User either during the initial create or later via an update.

To apply a Profile to a User via an update you should invoke Update User and supply the profileId that you wish to apply. You should include all the details of the User.

It is important to remember the fields specified in the User request have a higher priority and will override any from the Profile.

  • For example, if the User and Profile both contain settings for features, the User features will be chosen.
    • The same applies to any other fields they have in common.

PUT /users/{userId}

/v1/accounts/ABCDEF/users/c8c2909d-75e9-484a-94c0-b7e8d29771fe

Request Body:

{
  "organizationNodeId": "EXMPLE",
  "loginId": "[email protected]",
  "lastName": "Stevens",
  "firstName": "Alex",
  "profileId": "ASDFGH"
}

Once applied the fields present in the Profile will be returned as part of the User. Now every time the Profile is updated the User will receive those updates automatically.

HTTP 202 Accepted

{
  "userId": "c8c2909d-75e9-484a-94c0-b7e8d29771fe",
  "organizationNodeId": "EXMPLE",
  "loginId": "[email protected]",
  "lastName": "Stevens",
  "firstName": "Alex",
  "profileId": "ASDFGH",
  "uxProfileId": "6f482dcd-54a9-445f-ba6d-8ca5ebd5261a",
  "roles": [
    "Agent"
  ],
  "memberOfGroups": [
    "c8c2909d-75e9-484a-94c0-b7e8d29771fe"
  ],
  "features": {
    "matching": {
      "attributes": [
        "Language.English",
        "Language.French"
      ],
      "queues": [
        {
          "queueId": "620bbb28-7112-433a-af59-17ee0f15a247",
          "proficiency": 10
        }
      ]
    },
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false,
      "userExtension": "10021",
      "emergencyLocationIdentificationNumber": "7798098090",
      "providers": [
        {
          "providerAgentId": "0585aad8-decd-402c-b13f-bc05bd989fca",
          "channelProviderId": "a8b6d39c-53c5-4d94-a640-c28bee987ed7"
        }
      ]
    }
  }
}

Status Changes

The status on the List User Statuses for this User would go through the following changes:

1. Add In-Progress

[
  {
    "action": "ADD",
    "status": "IN_PROGRESS",
    "message": "Operation is in progress",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "role": {
      "action": "ADD",
      "status": "IN_PROGRESS",
      "message": "Operation is in progress"
    },
    "features": {
      "matching": {
        "action": "ADD",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      },
      "voice": {
        "action": "ADD",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Add Completed

[
  {
    "action": "ADD",
    "status": "COMPLETED",
    "message": "Completed successfully",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "role": {
      "action": "ADD",
      "status": "COMPLETED",
      "message": "Added successfully"
    },
    "features": {
      "matching": {
        "action": "ADD",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      },
      "voice": {
        "action": "ADD",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below.

  • A client should re-attempt any failed roles or features using the Update User.

Add Failed

[
  {
    "action": "ADD",
    "status": "FAILED",
    "message": "Operation failed",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "role": {
      "action": "ADD",
      "status": "FAILED",
      "message": "The requested roles could not be added"
    },
    "features": {
      "matching": {
        "action": "ADD",
        "status": "FAILED",
        "message": "The feature could not be added"
      },
      "voice": {
        "action": "ADD",
        "status": "FAILED",
        "message": "The feature could not be added"
      }
    }
  }
]

Updating a User

To update a User you should invoke Update User. You should include all the details of the User. As with Profiles, fields that are omitted from the update that were previously present will be removed.

The same basic principle applies to any updates made to a User. It is treated as a complete replacement.

PUT /users/{userId}

/v1/accounts/ABCDEF/users/c8c2909d-75e9-484a-94c0-b7e8d29771fe

Request Body:

{
  "organizationNodeId": "EXMPLE",
  "loginId": "[email protected]",
  "lastName": "Stevens",
  "firstName": "Alex",
  "features": {
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false
    }
  }
}

HTTP 202 Accepted

{
  "userId": "c8c2909d-75e9-484a-94c0-b7e8d29771fe",
  "organizationNodeId": "EXMPLE",
  "loginId": "[email protected]",
  "lastName": "Stevens",
  "firstName": "Alex",
  "features": {
    "voice": {
      "autoAnswer": false,
      "afterContactWork": false,
      "userExtension": "10021",
      "emergencyLocationIdentificationNumber": "7798098090",
      "providers": [
        {
          "providerAgentId": "0585aad8-decd-402c-b13f-bc05bd989fca",
          "channelProviderId": "a8b6d39c-53c5-4d94-a640-c28bee987ed7"
        }
      ]
    }
  }
}

Status Changes

The status on the List User Statuses for this User would go through the following changes:

1. Add In-Progress

[
  {
    "action": "ADD",
    "status": "IN_PROGRESS",
    "message": "Operation is in progress",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "features": {
      "voice": {
        "action": "ADD",
        "status": "IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Add Completed

[
  {
    "action": "ADD",
    "status": "COMPLETED",
    "message": "Completed successfully",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "features": {
      "voice": {
        "action": "ADD",
        "status": "COMPLETED",
        "message": "Feature added successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below.

  • A client should re-attempt any failed roles or features using the Update User.

Add Failed

[
  {
    "action": "ADD",
    "status": "FAILED",
    "message": "Operation failed",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "features": {
      "voice": {
        "action": "ADD",
        "status": "FAILED",
        "message": "The feature could not be added"
      }
    }
  }
]

Deleting a User

To delete a User you should invoke Delete User. No response body is returned from this request.

DELETE /users/{userId}

/v1/accounts/ABCDEF/users/c8c2909d-75e9-484a-94c0-b7e8d29771fe

HTTP 204 No Content

After a User has been deleted Get User will return HTTP 404 Not Found. The status of the User will no longer be available via List User Statuses as it no longer exists.

Status Changes

The status on the List User Statuses for this User would go through the following changes:

1. Delete In-Progress

[
  {
    "action": "DELETE",
    "status": "DELETE_IN_PROGRESS",
    "message": "Operation is in progress",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "features": {
      "voice": {
        "action": "DELETE",
        "status": "DELETE_IN_PROGRESS",
        "message": "Operation is in progress"
      }
    }
  }
]

2. Delete Completed

[
  {
    "action": "DELETE",
    "status": "DELETED",
    "message": "Completed successfully",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "features": {
      "voice": {
        "action": "DELETE",
        "status": "DELETED",
        "message": "Feature deleted successfully"
      }
    }
  }
]

In the event of a failure the status would appear similar to the below. If there is a failure a delete can be re-attempted.

Add Failed

[
  {
    "action": "DELETE",
    "status": "FAILED",
    "message": "Operation failed",
    "userId": "c8c2909d-75e9-484a-94c0-b7e8d30771fe",
    "features": {
      "voice": {
        "action": "DELETE",
        "status": "FAILED",
        "message": "The feature could not be deleted"
      }
    }
  }
]


Bulk User and Bulk Job

The Bulk User API provides the capability to add, update, and delete users via bulk jobs.

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.

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.

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

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

ColumnTypeExampleDescription
Login IdString[email protected]Login Id for the user.
Account HierarchyStringABCDEFUnique Id for Account or Node to assign the user.
Last NameStringStevensLast name of the user.
First NameStringAlexFirst name of the user.
Display NameStringStevens, AlexDisplay name of the user.
EmailString[email protected]Email Id of the user.
PasswordStringAghtat2343$Login credentials of the user.
ProfileStringFSADSJThe unique 6 character internal id that represents the profile.
RolesArray of Strings (comma-separated)[Agent,Business Analyst]Roles assigned to user.
Member OfArray 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 GroupsArray of Strings (comma-separated)[05603a3a-3dfb-4606-ae79-fd0fe0be2e52,f908ac1f-b7d1-41d9-a304-5f20f424832d]List of the groups owned by the user.

Step 2: 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 3: 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

StateEnd StatusDescription
IN_PROGRESSNoThe job is currently in progress.
PENDINGNoThe job will start after the previous profile update job has completed.
COMPLETEDYesThe job completed successfully.
FAILEDYesThe job failed, 1 or more users could not be processed.
ABORT_IN_PROGRESSNoThe job is currently being aborted.
ABORTEDYesThe job was aborted by the client.

Step 4: 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 5: 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}

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


Available Roles

  • Administrator
  • Agent
  • Business Analyst
  • Historical Reporting_Advanced
  • Historical Reporting_Basic
  • Historical Reporting_Consumer
  • Reporting
  • Reporting_Administrator
  • Reporting_Supervisor
  • Supervisor
  • Workspaces Admin Widgets Administrator

Updated 3 days ago