User Integrated Clients Services¶

Create Integrated Clients for a User¶

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/integrated_clients/¶

Create one or more integrated clients for an User.
The integrated client can be created by using a pre defined Service Pack or providing the information by using device_types, device_types and active_statuses.
Using Service Pack is the recommended way of working.
The fields device_types and extra_phone_ids are mutulally exclusive respect to Service Pack.
The Service Pack MUST be defined in the APIO database by the system administrators. See Configuration Information for the Service Pack Integrated Client.

This API will reuse the logic defined in Create an Additional Phone for a User.

Authorization Right:minimum Group Admin.

Example request with servicePack:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/integrated_clients/ HTTP/1.1
Host: example.com

{
   "servicePack": "test-service-pack"
}

Request JSON Object:

servicePack (string) – (required) the service pack to use to create the integrated clients.
phoneNumber (string) – (optional) the phone number for the integrated clients. If not present it will be read from the profile. It is mainly a performance improvement if the client already knows it.

Example response with servicePack:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "results": [
      {
         "deviceType": "Business Communicator - Mobile",
         "deviceName": "DP_foouserA04",
         "extra_phone_id": 4,
         "linePort": "LP_foouserA04@sip.netaxis.be",
         "status": "SUCCESS"
      },
      {
         "deviceType": "Business Communicator - PC",
         "deviceName": "DP_foouserA06",
         "extra_phone_id": 6,
         "linePort": "LP_foouserA06@sip.netaxis.be",
         "status": "SUCCESS"
      }
   ]
}

Response JSON Object:

results (array) – the list of integrated clients create results. See Integrated Client Create Attributes in List.

Example request with device_types and extra_phone_ids:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/integrated_clients/ HTTP/1.1
Host: example.com

{
   "device_types": ["Business Communicator - Mobile"],
   "extra_phone_ids": [5]
}

Request JSON Object:

device_types (array) – (required) the list of strings of the device type for the integrated clients.
extra_phone_ids (array) – (required) the list of integers of the extra phone ids for the integrated clients.
active_statuses (array) – (optional) the list of booleans of the active statuses for the integrated clients.
phoneNumber (string) – (optional) the phone number for the integrated clients. If not present it will be read from the profile. It is mainly a performance improvement if the client already knows it.

Example response device_types and extra_phone_ids:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "results": [{
      "deviceType": "Business Communicator - Mobile",
      "deviceName": "DP_foouserA05",
      "extra_phone_id": 5,
      "linePort": "LP_foouserA05@sip.netaxis.be",
      "status": "SUCCESS"
      }]
}

Response JSON Object:

results (array) – the list of integrated clients create results. See Integrated Client Create Attributes in List.

The status code and error messages are common to both usage of the API.

Status Codes:

201 Created – no error
400 Bad Request –
Unable to create the integrated client, with possible sub-error codes (other error codes could ceom from the AS):
- 18: INVALID_OPERATION, “No more free id available for an additional phone.”
- 18: INVALID_OPERATION, “No more free ports available on the target device”
- 18: INVALID_OPERATION, “The Service Pack is incorrectly configured.”
- 18: INVALID_OPERATION, “The Service Pack has no integrated client.”
- 9: MISSING_CONDITIONAL_PARAMETERS, “At least must provide ‘servicePack’ or ‘device_types’ and ‘extra_phone_ids’.”, “This device type requires ‘lineNumber’”
- 1: MISSING_MANDATORY_PARAMETERS, “deviceType”
- 43: IMPOSSIBLE_TO_GENERATE_ID, “Impossible to generate device name or line port”
- 2: INVALID_PARAMETERS, “The Service Pack is not assigned to the user.”

Note:

The extra_phone_id can be provided if the user wants to force that specific id or it can be omitted and in that case the APIO will try to find a free one and based on rules presented at the end of this page.

Delete Integrated Clients of an User¶

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/integrated_clients/¶

Delete the integrated clients of an User using a Service Pack.
This is the recommended way of working.
The Service Pack MUST be defined in the database by the system administrators. See Configuration Information for the Service Pack Integrated Client.
If an integrated client is linked to 2 Service Pack, removing one of them only will not trigger the delete of the integrated client.

Authorization Right:minimum Group Admin.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/integrated_clients/ HTTP/1.1
Host: example.com

{
   "servicePack": "test-service-pack"
}

Request JSON Object:

servicePack (string) – (required) the service pack to use to delete the integrated clients.

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "results": [
      {
         "deviceType": "Business Communicator - Mobile",
         "extra_phone_id": 4,
         "status": "SUCCESS"
      },
      {
         "deviceType": "Business Communicator - PC",
         "extra_phone_id": 6,
         "status": "STILL_USED",
         "reason": "The deviceType Business Communicator - PC is still needed by an other Service Pack"
      }
   ]
}

Response JSON Object:

results (array) – the list of integrated clients delete results.

Status Codes:

200 OK – no error

Statusocde 400:

Unable to delete the device.

Delete an Integrated Client of a User¶

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/integrated_clients/(string: instance_name)/¶

Delete an integrated client of an User.
This is not the recommended way of working.
This API is intended to be used ONLY in case of manual cleaning of mismatching data as otherwise the Service Packs assigned and the integrated clients created would mismatch.

Authorization Right:minimum Group Admin.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/access_device/integrated_clients/DP_foouserA05/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "deviceType": "Business Communicator - Mobile",
   "extra_phone_id": 5,
   "status": "SUCCESS"
}

Response JSON Object:

deviceType (string) – the device type of the integrated client.
status (string) – the status of the operation. See Integrated Client Delete Status.
reason (string) – (Conditional) the reason of the error. See Integrated Client Delete Error Reason.

Status Codes:

200 OK – no error

Statusocde 404:

integrated client not found.

Statusocde 400:

error during the removal.

Local objects definition¶

Integrated Client Create Attributes in List¶

Name	Type	Method	Description
Name	Type	POST	Description
deviceType	String	A	The device type of the integrated client.
deviceName	String	A	The device name of the integrated client.
extra_phone_id	Integer	A	The extra phone id of the integrated client. In case of error, if the integrated client was configured to get automatically the first free extra_phone_id will return null instead.
linePort	String	A	The line port of the integrated client.
status	String	A	The status of the operation. See Integrated Client Create Status.
reason	String	C	The reason of the error. See Integrated Client Create Error Reason.

Integrated Client Create Status¶

The status for a create operation can be one of:

SUCCESS
FAILED
ALREADY_EXISTS
CONFLICT
STILL_USED

Integrated Client Create Error Reason¶

The reason field is returned only in case of error. The reason for a create operation can be due to:

ALREADY_EXISTS: “The device already exists with the requested properties”.
CONFLICT: generic error message from low level API.
CONFLICT: “A standalone device already exists with same name and deviceType”.
CONFLICT: “A standalone device already exists with same name and but different deviceType”.
FAILED: “Ids already in use”.
FAILED: generic error message from low level API.

Integrated Client Delete Attributes in List¶

Name	Type	Method	Description
Name	Type	DELETE	Description
deviceType	String	A	The device type of the integrated client.
extra_phone_id	Integer	A	The extra phone id of the integrated client.
status	String	A	The status of the operation. See Integrated Client Delete Status.
reason	String	C	The reason of the error. See Integrated Client Delete Error Reason.

Integrated Client Delete Status¶

The status for a delete operation can be one of:

SUCCESS
FAILED
STILL_USED

Integrated Client Delete Error Reason¶

The reason field is returned only in case of error. The reason for a delete operation can be due to:

FAILED: generic error message from low level API.
STILL_USED: “The deviceType … is still needed by an other Service Pack”. In this error message the … will be replaced by the deviceType name.

Configuration Information for the Service Pack Integrated Client¶

Example of integrated client configuration for “test-service-pack”:

{
   "integrated_client": {
      "device_types": ["Business Communicator - Mobile", "Business Communicator - PC"],
      "extra_phone_ids": [4, 6],
      "active_statuses": [true, false],
      "with_credentials": [true, true],
   }
}

The full configuration of the Service Pack can be found in Display services pack instance.

The parameters mentioned in the example upper are the ones used by the logic of the APIs defined in this page.

The Integrated Client API relies on the APIs User Additional Phones Services. and therefore also for the configuration settings.

In addition the following settings is used:

"INTEGRATED_APPS_PWD_WITH_SPECIAL": true

Explanation of the parameters:

INTEGRATED_APPS_PWD_WITH_SPECIAL: If a password has to be generated for the integrated client, then this settings define if it will contains special chars. Default is True