User Main Phone

The User Phone Service API manages directly an Access Device such as it was a property of the User and not of the Groups such as in the Application Server. It means that it will create/delete/modify the Access Device at Group level when needed and manage its link to an End User.

These APIs require that the deviceType used is defined in APIO configuration, if not an error will be thrown.

This deviceType will define extra properties and constraints that are not present as such in the in the Application Server (see Phone Types)

Assign a Phone to a User

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/
This request will do the following actions:

  • Create the Access Device (except if it is adding a User to an existing DECT device) including Access Device credentials generation

  • Linking the Access Device to the User including a Line Port generation

  • Creating a record in the Redirect Server (if configured in the phone type)

  • Creating a record in the Phone Vendor Provisioning Server (if configured in the phone type)

  • Generate extra properties on the Access Device based on the extra parameters defined in the phone type.

In addition to this logic if the check logic is enabled (see at the end of the page) it will be checked if the deviceType is linked to the integrated client of a service pack in that case:

  • if the service pack is not assigned, the request will be rejected

  • if the integrated client of that service pack was created it will be deleted.

Authorization Right: minimum Group Admin.

Example request:

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

{
   "deviceType": "HDV230",
   "macAddress": "AABBCCDDEEFF00",
   "disableLedVm": false,
   "disableLedMissed": false
}

Example response:

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

{
   "deviceName": "DP_foouser@example.com",
   "deviceType": "HDV230",
   "macAddress": "AA:BB:CC:DD:EE:FF:00",
   "serialNumber": "",
   "linePort": "LP_foouser@example.com",
   "disableLedVm": false,
   "disableLedMissed": false
}
Request JSON Object:

  • deviceType (string) – the Type of Device to te added (it must be configured at APIO level)

  • deviceName (string) – (optional) the name for the device. The default logic is to let the APIO build it, it should only be provided when linking to an existing DECT device. Otherwise it will be generated by the APIO to match the naming conventions(explict customer request).

  • linePort (string) – (optional) the line port of the user on the device. The default logic is to let the APIO build it, but the API allows to set one. This is described more in details below

  • macAddress (string) – (conditional) the MAC address of the device. Conditionally based on the configuration of the device type (needMac parameter).

  • serialNumber (string) – (conditional) the serial number of the device. Conditionally based on the configuration of the device type (needSerialNumber parameter).

  • newDect (boolean) – (optional) the indication that it is a new DECT to be created (and not linking to an existing DECT). This field is mandatory when a new DECT is created. Conditionally based on the configuration of the device type (isDECT parameter).

  • portNumber (integer) – (conditional) the port for the phone. Conditionally based on the configuration of the device type (needPort parameter).

  • useCustomUserNamePassword (string) – (conditional) See useCustomUserNamePassword from Access Device attributes. Conditionally based on the configuration of the device type (needLogin parameter).

  • accessDeviceCredentials (string) – (conditional) See accessDeviceCredentials from Access Device attributes. Conditionally based on the configuration of the device type (needLogin parameter).

  • disableLedVm (boolean) – (optional, based on phone type configuration) disable the LED indication of an unread VM

  • disableLedMissed (boolean) – (optional, based on phone type configuration) disable the LED indication of a missed call

Response:

Similar to GET instance method response.Except that the following additional parameter can be present when relevant.

Response JSON Object:

  • deviceActivationCode (string) – If the device type supports the auto-configuration via a Device Activation Code it will be returned.

Status Codes:

  • 200 OK – no error

  • 400 Bad Request –

    Unable to create the Device. Among others the specific errors could occur:

    • 11: ALREADY_EXISTS, “The user has already a main device”

    • 11: ALREADY_EXISTS, “The user is already in a trunk group, he can not have a main device”

    • 2: INVALID_PARAMETERS, “Unknown deviceType”

Note

All the parameters after the accessDeviceCredentials are examples of what could be supported with the dynamic data model definition of the phone types and will therefore be only available if configured in that way (same properties could be defined for example with an other name). Other properties could be added. All with depend of the specific APIO deployment.

Display the Phone of a User

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/
Retrieve the Access Device linked to the User.
It is possible to retrieve optionally the available ports of the device.

Authorization Right: minimum End User.

Example request:

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

Example response:

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

{
   "deviceName": "DP_foouser@example.com",
   "deviceType": "HDV230",
   "macAddress": "AA:BB:CC:DD:EE:FF:00",
   "linePort": "LP_foouser@example.com"
   "disableLedVm": false,
   "disableLedMissed": false
}

Example request with include_available_ports:

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

{
   "include_available_ports": true
}
Request JSON Object:

  • include_available_ports (boolean) – to include or not the list of available ports of the access device.

Example response with include_available_ports:

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

{
   "deviceName": "DP_foouser@example.com",
   "deviceType": "HDV230",
   "macAddress": "AA:BB:CC:DD:EE:FF:00",
   "serialNumber": "",
   "linePort": "LP_foouser@example.com"
   "disableLedVm": false,
   "disableLedMissed": false,
   "availablePorts": [1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15, 16]
}
Response JSON Object:

  • deviceType (string) – See create API

  • macAddress (string) – (conditional) See create API

  • serialNumber (string) – (conditional) See create API

  • portNumber (integer) – (conditional) See create API. O means unknown (usually the case when dynamic port ordering is used.

  • deviceName (string) – See create API

  • availablePorts (object) – (conditional) the list of the available port numbers of the user device. Never returned for devices that do not support port assignment.

  • linePort (string) – (conditional) See create API

  • useCustomUserNamePassword (string) – (conditional) See useCustomUserNamePassword from Access Device attributes.

  • userName (string) – (conditional) See userName from Access Device attributes.

  • disableLedVm (boolean) – (optional, based on phone type configuration) See create API and its note

  • disableLedMissed (boolean) – (optional, based on phone type configuration) See create API and its note

Note:

More information could be reported dynamically based on the Phone Type configuration. But as it is based on configuration, it can not be documented at Product level.

Status Codes:

Note

All the parameters after the linePort are examples of what could be supported with the dynamic data model definition of the phone types and will therefore be only available if configured in that way (same properties could be defined for example with an other name). Other properties could be added. All with depend of the specific APIO deployment.

Update the Phone of a User

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/

Modify the properties of the phone linked to a User.

This request will do the following actions:

  • If the Phone Type is updated, the old Access Device will be deleted and a new one will be created.

  • If the User was linked to a DECT and this link is removed (change of DECT or of phone type) and the User was the only one connected to that DECT then the DECT is deleted. Else it remains.

  • If the phone type is changed or if the MAC Address is changed:

    • Generation new Access Device credentials if needed

    • Creating a record in the Redirect Server (if configured in the phone type)

    • Creating a record in the Phone Vendor Provisioning Server (if configured in the phone type)

  • Generate extra properties on the Access Device based on the extra parameters defined in the phone type.

In addition to this logic if the check logic is enabled (see at the end of the page) it will be checked if the old and new deviceType (in case it is changed) is linked to the integrated client of a service pack. if at least one of them is linked to a service pack:

  • if the service pack linked to the new device type (if any) is not assigned, the request will be rejected

  • if the integrated client of the service pack linked to the new device type (if any) was created it will be deleted.

  • for the service pack linked to the old device type (if any), the related integrated client will be created.

Authorization Right: minimum End User.

Example request:

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

{
   "deviceType": "HDV230",
   "macAddress" : "AABBCCDDEEFF11",
   "disableLedVm": false,
   "disableLedMissed": true
}
Request JSON Object:

  • deviceType (string) – the Type of Device to te added (it must be configured at APIO level)

  • linePort (string) – (optional) the line port of the user on the device. The default logic is to let the APIO build it, but the API allows to set one. This is described more in details below

  • macAddress (string) – (conditional) the MAC address of the device. Conditionally based on the configuration of the device type (needMac parameter).

  • deviceName (string) – (conditional) the name for the device. The default logic is to let the APIO build it, it should only be provided when linking to an existing DECT device. Otherwise it will be generated by the APIO to match the naming conventions(explict customer request).

  • newDect (boolean) – (optional) the indication that it is a new DECT to be created (and not linking to an existing DECT). This field is mandatory when a new DECT is created. Conditionally based on the configuration of the device type (isDECT parameter).

  • portNumber (integer) – (conditional) the port for the phone. Conditionally based on the configuration of the device type (needPort parameter).

  • useCustomUserNamePassword (string) – (conditional) See useCustomUserNamePassword from Access Device attributes. Conditionally based on the configuration of the device type (needLogin parameter).

  • accessDeviceCredentials (string) – (conditional) See accessDeviceCredentials from Access Device attributes. Conditionally based on the configuration of the device type (needLogin parameter).

  • disableLedVm (boolean) – (optional, based on phone type configuration) disable the LED indication of an unread VM

  • disableLedMissed (boolean) – (optional, based on phone type configuration) disable the LED indication of a missed call

Example response:

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

{
   "deviceName": "DP_foouser@example.com",
   "deviceType": "HDV230",
   "macAddress": "AA:BB:CC:DD:EE:FF:11",
   "serialNumber": "",
   "linePort": "LP_foouser@example.com"
   "disableLedVm": false,
   "disableLedMissed": true
}
Response:

Similar to GET instance method response.Except that the following additional parameter can be present when relevant.

Response JSON Object:

  • deviceActivationCode (string) – If the device type supports the auto-configuration via a Device Activation Code and the Mac Address is changed it will be returned.

Status Codes:

Note

All the parameters after the accessDeviceCredentials are examples of what could be supported with the dynamic data model definition of the phone types and will therefore be only available if configured in that way (same properties could be defined for example with an other name). Other properties could be added. All with depend of the specific APIO deployment.

Delete the Phone of a User

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/
Remove the phone linked to a User.
This request will do the following actions:
* Unlink the phone from the User.
* If the User was the only primary user of the phone, it will be deleted.
* If the User was not the only primary user of the phone, but is considered as owner of the phone it will be deleted.
* If the phone has to be deleted, all users connected to this phone as secondary phone or as primary phone will be unlinked from it.
In addition to this logic if the check logic is enabled (see at the end of the page) it will be checked if the deviceType is linked to the integrated client of a service pack in that case:

  • the integrated client of that service pack will be created.

Authorization Right: minimum Group Admin.

Example request:

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

{ }

Example response:

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

{ }
Response JSON Object:

  • detached_additional_users (array) – list of objects. In case other users have been unlinked from the phone, a reference will be present in this list. Each object containsa field userId and a field linePort. This will allow in IMS network to know that PUID have to be deleted.

Status Codes:

Reset the Credentials of the Phone of a User

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/reset_security/
Regenerate the provisioning security properties of the phone. In order that a factory reset can be done on the phone
This request will do the following actions:
* Generation new Access Device credentials
* Reset the SIP password
* Creating a record in the Redirect Server
* Updating a record in the Phone Vendor Provisioning Server

Authorization Right: minimum Group Admin.

Example request:

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

{ }

Example response:

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

{ }
Status Codes:

Reboot the Phone of a User

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/access_device/reset_phone/
This API will ask the phone to reboot (via Broadsoft) after having re-generated some parameters.
This request will do the following actions:
* Reset the SIP password
* Rebuild the configuration file: Broadsoft will then inform the phone to reload its configuration

Authorization Right: minimum Group Admin.

Example request:

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

{ }

Example response:

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

{ }
Status Codes:

Configuration Information for User Phone

In the POST and PUT APIs a line port can be specified.

The APIO behaviour is controlled by the following settings:

"USER_LINE_PORT_ALLOW_INPUT" : false
"APIO_OBJECT_CREATION": {
    "GENERATED_ID_DATA": true
},
"AUTOMATIC_ID_RULES": {
    "LINE_PORT_USER_MAIN_DEVICE": "{{phone_number_e164}}@{{domain}}",
    "FALLBACK_LINE_PORT_USER_MAIN_DEVICE": "{{user_id}}@{{domain}}"
    "LINE_PORT_USER_MAIN_DEVICE": "DEV{{userd_id}}@{{domain}}",
    "USER_MAIN_DEVICE_NAME_OVERWRITE": true,
    "GENERIC_DEVICE_NAME_RULE": "DP_{{RND_36}}"
},
"DEVICE_NAME_MAX_LENGTH" :40,
"MAIN_ACCESS_DEVICE_STATIC_CONTACT_LIST": [ "<static contact 1>", "<static contact 2>", ... ],
"CHECK_INTEGRATED_CLIENT_MAIN_DEVICE" : true
By default the line_port of a User is of the format LP_test_user@sip.netxais.be where test_user is the user part of the user_id. If an other format is needed the Automatic Id mechanism can be used.
It must be enabled using the GENERATED_ID_DATA with value True and by specifying a LINE_PORT_USER_MAIN_DEVICE formatting rule and optionally a FALLBACK_LINE_PORT_USER_MAIN_DEVICE formatting rule.
Explanation for the parameters:
  • AUTOMATIC_ID_RULES:

    • USER_MAIN_DEVICE_NAME: the formatting rule for the name of the main own device of the user.

    • FALLBACK_USER_MAIN_DEVICE_NAME: the fallback formatting rule if the main one has failed .

    • LINE_PORT_USER_MAIN_DEVICE: the formatting rule for the line port

    • FALLBACK_LINE_PORT_USER_MAIN_DEVICE: the fallback formatting rule if the main one has failed (for example based on a phone number but the user has no phone number). Recommended to be based on the user id as this one will always be present

    • DECT_DEVICE_NAME: the formatting rule for the name of the DECT device if created via this API.

    • FALLBACK_DECT_DEVICE_NAME: the fallback formatting rule if the main one has failed

    • USER_MAIN_DEVICE_NAME_OVERWRITE: if that name was already existing in APIO DB, it is replaced by this one (new in APIO 1.6.1). Default in True. Should not be enabled if the names are using random parameters.

  • USER_LINE_PORT_ALLOW_INPUT: If set to True and a line port is provided in the API it will be used, in all other cases the APIO will generate one.

  • APIO_OBJECT_CREATION:

    • GENERATED_ID_DATA: APIO will enable the auto-generation of ids. It must be True if the id rules are used.

  • DEVICE_NAME_MAX_LENGTH: when the device name of a user main device is autogenerated, the length is fixed at maximum this value: default 40.

  • GENERIC_DEVICE_NAME_RULE: a generic fallback auto-generation rule. This rule is used only when the device name excedes DEVICE_NAME_MAX_LENGTH

  • MAIN_ACCESS_DEVICE_STATIC_CONTACT_LIST: static contacts list for user’s main device.

  • CHECK_INTEGRATED_CLIENT_MAIN_DEVICE: if enabled the APIO will check the Main Device Type and will apply the logic described in the different APIs. Default is true. Logic introduced in 1.8.3.

Note

In order to have the the check device type related to integrated client logic working correctly a standard basic setup is needed:

  • only one integrated client device_type by service pack

  • only a device_type is present as integrated client in maximum one service pack

  • the mandatory specific services needed by an integrated client device_type are only present in the related service packs not in other generic service packs.

If these conditions are not met, the related check logics can lead to unpredictable results and it therefore recommended to disable them and manage the checks at api client side by several api calls to the related end points (service packs definition, user main device, …)

In these rules the following variables can be used:

  • phone_number_e164: The phone number in E164 format

  • country_code: The country code of the phone number

  • national_no_0: The national number, without trailing 0, of the phone number

  • domain: the domain

  • tenant_id: the Tenant Id

  • group_id: the Group Id

  • user_id: the user part (aka left part) of the user id