Access Device Advanced Management

The Advanced Management of an Access Device allows to manage also, in addition of the main Application Server:

  • the check of the provided properties against APIO internal definition of the supported phone types. This allow to enforce rules such as “mac address is mandatory for this phone type” that can bot be expressed in the AS itself.

  • the optional insertion of the Access Device in the internal Redirect Server if the phone type requests it

  • the optional insertion of the Access Device in the Phone Vendor Provisioning Server if the phone type requests it

  • the support of additional parameters defined in the phone type

  • the possibility to auto-generate the device name

These APIs require that the deviceType used is defined in APIO configuration, if not an error will be trowed (except the GET List).

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

Retrieve Access Devices list

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/advanced_access_devices/
Retrieve the access device list. It is the same signature as the basic Access Device API.
It’s possible to filter the list on a single device and request the availa&ble ports for the mathcing devices by using available_ports_for.
It’s also possible to request the list of the available ports of all device by using include_available_ports. Be carefull that this option could significantly increase the API repsonse tiome
The parameter available_ports_for has priority on include_available_ports: in case both are requested, only the first will be applied.
Note:

careful with include_available_ports usage because this operation could take very long time, based on the amount of the devices.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/ HTTP/1.1
Host: example.com

Example response:

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

{
   "access_devices":
   [
      {
         "status": "Online",
         "deviceName": "APIO Test Device",
         "version": "",
         "macAddress": "221100CCBBAA",
         "netAddress": "",
         "freePorts": 15,
         "deviceType": "Generic SIP Phone"
      },
      {
         "status": "Online",
         "deviceName": "DP_ApioUserTest",
         "version": "pjsip python",
         "macAddress": "",
         "netAddress": "",
         "freePorts": 7,
         "deviceType": "Generic SIP Video Phone"
      }
   ]
}

Example request with available_ports_for:

GET /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/ HTTP/1.1
Host: example.com

{
   "available_ports_for": "Generic SIP Phone"
}
<json string available_ports_for:

the name of the device to be filtered.

Example response with available_ports_for:

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

{
   "access_devices":
   [
      {
         "status": "Online",
         "deviceName": "APIO Test Device",
         "version": "",
         "macAddress": "221100CCBBAA",
         "netAddress": "",
         "freePorts": 15,
         "deviceType": "Generic SIP Phone",
         "availablePorts": [1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15, 16]
      }
   ]
}

Example request with include_available_ports:

GET /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/ HTTP/1.1
Host: example.com

{
   "include_available_ports": true
}
<json boolean include_available_ports:

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"

{
   "access_devices":
   [
      {
         "status": "Online",
         "deviceName": "APIO Test Device",
         "version": "",
         "macAddress": "221100CCBBAA",
         "netAddress": "",
         "freePorts": 15,
         "deviceType": "Generic SIP Phone",
         "availablePorts": [1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15, 16]
      },
      {
         "status": "Online",
         "deviceName": "DP_ApioUserTest",
         "version": "pjsip python",
         "macAddress": "",
         "netAddress": "",
         "freePorts": 7,
         "deviceType": "Generic SIP Video Phone",
         "availablePorts": [1, 2, 3, 4, 6, 7, 8]
      }
   ]
}
>json array access_devices:

a list of access devices. See Access Device list item.

statuscode 200:

no error

Retrieve Access Device details

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/advanced_access_devices/(string: instance_name)/

Retrieve the access device details. It is the same input signature as the basic Access Device API

Example request:

GET /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/APIO%20Test%20Device%20New/ HTTP/1.1
Host: example.com

Example response:

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

{
   "configurationFileName": "",
   "macAddress": "332211CCBBAA",
   "useCustomUserNamePassword": false,
   "protocol": "SIP 2.0",
   "stunServerNetAddress": "",
   "numberOfAssignedPorts": 0,
   "netAddress": "",
   "version": "",
   "deviceType": "Generic SIP Phone",
   "outboundProxyServerNetAddress": "",
   "status": "Online",
   "numberOfPorts": -1,
   "description": "APIO Test Device New",
   "userName": "",
   "physicalLocation": "",
   "transportProtocol": "Unspecified",
   "serialNumber": ""
}

Example request with include_available_ports:

GET /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/APIO%20Test%20Device%20New/ 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:

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

{
   "configurationFileName": "",
   "macAddress": "332211CCBBAA",
   "useCustomUserNamePassword": false,
   "protocol": "SIP 2.0",
   "stunServerNetAddress": "",
   "numberOfAssignedPorts": 1,
   "netAddress": "",
   "version": "",
   "deviceType": "Generic SIP Phone",
   "outboundProxyServerNetAddress": "",
   "status": "Online",
   "numberOfPorts": 16,
   "description": "APIO Test Device New",
   "userName": "",
   "physicalLocation": "",
   "transportProtocol": "Unspecified",
   "serialNumber": "",
   "availablePorts": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
}
Response JSON Object:
Status Codes:

Note

Other properties could be added with the dynamic data model definition of the phone types and will therefore be only available if configured in that way. All with depend of the specific APIO deployment.

Create an access device

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/advanced_access_devices/

Create an access device. It is the same signature as the basic Access Device API. If the phone type is configured in APIO DB, APIO will insert the access device in the redirect server and/or the vendor server depending on the configuration. If the insertion fails in one of the systems, the creation of the access device will be rollbacked in all nodes already provisioned.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "deviceName": "APIO Test Device",
   "deviceType": "Generic SIP Phone",
   "protocol": "SIP 2.0",
   "macAddress": "221100CCBBAA",
   "description": "APIO Test Device",
   "transportProtocol": "Unspecified",
   "useCustomUserNamePassword": false
}
Request JSON Object:

Example response:

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

{
   "deviceName": "APIO Test Device",
   "configurationFileName": "",
   "macAddress": "332211CCBBAA",
   "useCustomUserNamePassword": false,
   "protocol": "SIP 2.0",
   "stunServerNetAddress": "",
   "numberOfAssignedPorts": 0,
   "netAddress": "",
   "version": "",
   "deviceType": "Generic SIP Phone",
   "outboundProxyServerNetAddress": "",
   "status": "Online",
   "numberOfPorts": -1,
   "description": "APIO Test Device New",
   "userName": "",
   "physicalLocation": "",
   "transportProtocol": "Unspecified",
   "serialNumber": ""
}
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:

Example error response:

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

{
   "errors": [
      {
          "code": 31,
          "message": "Phone Provisioning Server reply with an error: Illegal MAC address format",
          "sub_code": 4001,
          "details": {}
      }
   ]
}
Status Codes:

See Sub Error Codes for Phone Vendor for the possible values for the sub_code when the code is 31 (Phone Vendor error)

Note

Other properties could be added with the dynamic data model definition of the phone types and will therefore be only available if configured in that way. All with depend of the specific APIO deployment.

Update an access device

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/advanced_access_devices/(string: instance_name)/

If the phone type is configured in APIO DB and if the Mac Address is modified, APIO will insert the access device in the redirect server and/or the vendor server depending on the configuration. If the insertion fails in one of the systems, the update of the access device will be rollbacked in all nodes already provisioned

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/APIO%20Test%20Device%20New/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "macAddress": "110022BBAACC",
   "description": "APIO Test Device Modified"
}
Request JSON Object:

Example response:

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

Other properties could be added with the dynamic data model definition of the phone types and will therefore be only available if configured in that way. All with depend of the specific APIO deployment.

Delete an access device

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/advanced_access_devices/(string: instance_name)/

Delete an access device from the group and from the Phone Vendor and Redirect Server (if configured for that Phone Type). If one of these answers “not found”, it is not considered as an error as the expected final result is reached.

In addition it can unlink the device from all connected users if requested. Otherwhise the delete will fail if the device is still used by an user.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/advanced_access_devices/APIO%20Test%20Device%20New/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Request JSON Object:

  • delete_secondary_users (boolean) – if set to true, APIO will identify all users using this device as secondary/extra phone and will unlink them. Default is false.

  • delete_primary_users (boolean) – if set to true, APIO will identify all users using this device as primary phone and will unlink them. Default is false.

Response JSON Object:

  • detached_users (array) – list of objects. In case users have been unlinked, a reference will be present in this list. Each object contains a field userId and a field linePort.

Status Codes:

Configuration Information for the Device Name

In the POST the deviceName can be omitted and then it will be auto-generated using the configured rule if such rule is defined (none by default)

The APIO behaviour is controlled by the following settings:

"AUTOMATIC_ID_RULES": {
    "GROUP_DEVICE_NAME_RULE": "{{group_id}}_{{RND_4}}",
    "GENERIC_DEVICE_NAME_RULE": "DP_{{RND_36}}"
}
"DEVICE_NAME_MAX_LENGTH": 40,
Explanation fo the parameters:

  • GROUP_DEVICE_NAME_RULE: the formatting rule for the deviceName. None is defined by default, making the deviceName mandatory by default

  • DEVICE_NAME_MAX_LENGTH: the maximum length for the deviceName. The default value is 40 and if set to 0 no length check is performed

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

In these rules the following variables can be used:

  • tenant_id: the Tenant Id

  • group_id: the Group Id

Configuration Information for the Device Credentials

In some cases the APIO will be in charge of generating “hidden” credentials for a Device. These credentials are mainly used to authenticate when retrieving the configuration file. It is called “hidden” because the admins/end users will not know them.

The main use cases are for the Webex clients (as main device or as integrated client).

The generation of the password is controlled by following parameters:

"NEW_PASSWORD_RESET_GEN": true,
"MINIMUM_PASSWORD_RULES": {
     "DEVICE" : {
         "PASSWORD_MIN_SPECIAL_CHARACTERS": 0,
         "PASSWORD_MIN_UPPERCASE_LETTERS": 1,
         "PASSWORD_MIN_LOWERCASE_LETTERS": 1,
         "PASSWORD_MIN_DIGITS": 1,
         "PASSWORD_MIN_LENGTH": 8
     }
},
Settings description:

  • NEW_PASSWORD_RESET_GEN: If true the new logic based on rules will be used for the random passwords generation. Else the legacy hardcoded config will be used (and the minimum rules ignored). Default is true. Note that this is a global parameter.

  • MINIMUM_PASSWORD_RULES.**DEVICE**: (from 1.11.0) minium password rules for Admins (same for Group, Tenant, System). Default are the ones in the example.

It must be noted that in the AS it is also a specific of set of password rules for the devices.

The generation of the username will depend on the use case: * the integrated clients have their own hardcoded rule in order to have the client id in the name * the main device will be a random prefix follwed by the user part of the device name.

From 1.11.0 the prefix is only digits and letters and its length is defined by:

"DEVICE_CREDENTIAL_PREFIX_LEN": 8

With a max length allowed value of 8 and the possibility to put 0.

It must be noted that these rules are valid for this page but also for integrated clients and for end user’s main device.