Update the parameters of one service for multiple users

Introduction

This feature allows to update in one shot the parameters of one service (such as Do Not Disturb) for a set of Users (Service Users and End Users).

Two modes are supported:

  • providing the new common parameters for the requested service.

  • giving the user id of a reference User and his settings, for the requested service, will be replicated to the others Users.

The API can be called in synchronous mode or asynchronous mode (pulling). The default mode is configured in the settings of the APIO, and it can be overridden with an input parameter. In case of synchronous call, all the logic is applied and then the final result is sent in the answer. In case of asynchronous call, all the checks are done, then a synchronous answer is sent with the job id and then the rest of the logic (the updates) is executed. It is then possible to pull the status of the job to get the final result.

The answer will provide the status for each requested users, except if a global error occur.

At least the following global error cases could occur:

  • the requested service is currently not supported by this bulk API

  • the reference User does not exist or is not accessible by the logged user.

  • the reference User has not the requested service assigned

  • both a reference User and common parameters have been provided

  • none of the reference User or common parameters have been provided

  • no list of target users provided

  • the common parameters do not match the json schema of the requested service

At the level of the individual results, at least the following errors could occur:

  • the target User does not have the requested service assigned

  • the target User does not exist or is not accessible by the logged user.

API definition

PUT /api/v1/tenants/(string: tenant_id)/bulks/bulk_update_users/(string: serviceName)/

Update one service for a group of Users.

The name of the service to be updated is in the url and correspond to the service name in the url of the associated end point at End User level

Authorization rights: minimum Tenant Admin.

Example request with service data:

PUT /api/v1/tenants/foo/bulks/bulk_update_users/dnd/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
      "userIds": [
          "fooUser1@foo.com",
          "fooUser2@foo.com",
          "fooUser7@foo.com"
      ],
      "serviceData" : {
          "active": true
      }
}
Request JSON Object:

  • userIds (array) – a list of userIds (string)

  • serviceData (object) – the parameters to be applied for each users. Check the individual API for more details

  • asynch (boolean) – Indicate if the bulk job has to be played in asynchronous (otherwise in synchronous mode). If not provided, the default is valeu is defined by the settings BULK_USER_SRV_ASYNCH with default value False.

Example request with reference user:

PUT /api/v1/tenants/foo/bulks/bulk_update_users/dnd/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
      "userIds": [
          "fooUser1@foo.com",
          "fooUser2@foo.com",
          "fooUser7@foo.com"
      ],
      "referenceUserId" : "fooMasterUser@foo.com"
}
Request JSON Object:

  • userIds (array) – a list of userIds (string)

  • referenceUserId (string) – the user Id of the user that will have his service parameters replicated to all users

  • asynch (boolean) – Indicate if the bulk job has to be played in asynchronous (otherwise in synchronous mode). If not provided, the default is valeu is defined by the settings BULK_USER_SRV_ASYNCH with default value False.

Example synchronous response:

HTTP/1.1 207 Multi-Status
Content-Type: "application/json"

{
   "result": [
      {"userId": "fooUser1@foo.com", "status": "updated"},
      {"userId": "fooUser2@foo.com", "status": "failed", "code": 8, "message": "User not found"},
      {"userId": "fooUser7@foo.com", "status": "failed", "code": 23, "message": "Service is not assigned to this subscriber."},
   ]
}
Response JSON Object:

  • result (array) – a list of objects containing the user Id and the status of the update (‘updated’, ‘failed’). See User’s Service Update Result items for the definition of the objects in the array.

Status Codes:

  • 200 OK – request was fully processed in success

  • 207 Multi Status – partial success (some users are updated, others not)

  • 400 Bad Request – it failed for all users or at global level

Example asynchronous response:

HTTP/1.1 207 Multi-Status
Content-Type: "application/json"

{
   "asynchJobId": "9fdcde94-0311-4754-b348-4503904f7a7b"
}
Response JSON Object:

  • asynchJobId (string) – the id (UUID) of the job. It will be used to retrieve its status.

Status Codes:

  • 200 OK – request was fully processed in success

  • 400 Bad Request –

    it failed at global level

    Concerning the global level, the following error cases are the most common:

    • 2 (INVALID_PARAMETERS) : “This service is not, yet, supported by the bulk updates”

    • 2 (INVALID_PARAMETERS) : “Must provide one, and only one, of ‘referenceUserId’ or ‘serviceData’.”

    • 2 (INVALID_PARAMETERS) : “Must provide one, and only one, of ‘referenceUserId’ or ‘serviceData’.”

    • 3 (JSON_SCHEMA_VALIDATION_ERROR): either at global level or for the serviceData.

    • 8 (NOT_FOUND_AT_NE): the referenceUserId is not found

    • 23 (SERVICE_NOT_ASSIGNED): the referenceUserId does not have the requested service assigned

    Concerning the user level, the following error cases are the most common:

    • 8 (NOT_FOUND_AT_NE): the target user is not found

    • 23 (SERVICE_NOT_ASSIGNED): the target user does not have the requested service assigned

    • 2 (INVALID_PARAMETERS) : if the request is rejected due to some bas data that could not have been checked at json schema level (for example enabling CFA without providing a destination number will succeed for the target users who had already an destination number configured in their cfa and fail for the others)

    • any specific error linked to one of the service itself.

Supported services

The following services are currently supported:

Objects definition

User’s Service Update Result items

Name

Type

Methods

Description

PUT

userId

String

A

The User ID.

status

String

A

The resulting status of the operation: ‘updated’ or ‘failed’

code

String

O

An error code if the operation has failed. See Error codes.

message

String

O

An optional message providing more information about the error.