Device Types Management at Group level¶

The APIs related to Device Types allow to set common properties or define actions for all the devices of a certain type in the Group.

This is an intermediate layer between the common properties defined for the Device Type at System level and the one defined at the level of the Access Device itself.

Group Device Type Tags¶

Retrieve list of Tags for a Device Type¶

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/tags/¶

Retrieve the list of Tags configured for a Device Type.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/tags/  HTTP/1.1
Host: example.com

Example response:

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

{
   "tags":
      [
         {
            "name": "%test_tag%",
            "value": "dummy value"
         },
         {
            "name": "%random_tag%",
            "value": ""
         }
      ]
}

Response JSON Object:

tags (array) – the list of tags for the requested Device Type. The objects have the same structure as for the GET instance.

Status Codes:

200 OK – no error
404 Not Found – the Device Type does not exist at system level

Add a Tag for a Device Type¶

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/tags/¶

Add a Tag to a Device Type.

Authorization rights: minimum Group Admin.

Example request:

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

{
   "name": "%test_tag%",
   "value": "dummy value"
}

Request JSON Object:

name (string) – The name of the Tag. It must start and end with a %. There can not be any other % in the name.
value (string) – (Optional) the value of the Tag

Example response:

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

{
   "name": "%test_tag%",
   "value": "dummy value"
}

Response JSON Object:

name (string) – The name of the Tag. It must start and end with a %. There can not be any other % in the name.
value (string) – The value of the Tag.

Status Codes:

200 OK – no error
404 Not Found – the Device Type does not exist at system level
400 Bad Request –
invalid request due to invalid parameters, with possible main sub error codes:
- 11 ALREADY_EXISTS, ‘Tag name already used for this device type.’
- 2 INVALID_PARAMETERS, ‘Invalid name, Name must start and end with %, with no other % allowed.’

Display a Tag of a Device Type¶

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/tags/(string: tag_name)/¶

Retrieve one Tag configured for a Device Type.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/tags/%test_tag%/  HTTP/1.1
Host: example.com

Example response:

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

{
   "name": "%test_tag%",
   "value": "dummy value"
}

Response JSON Object:

name (string) – The name of the Tag. It must start and end with a %. There can not be any other % in the name.
value (string) – The value of the Tag.

Status Codes:

200 OK – no error
404 Not Found – requested Tag does not exist for this Device Type

Modify a Tag of a Device Type¶

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/tags/(string: tag_name)/¶

Update an existing Tag configured for a Device Type.

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/tags/%test_tag%/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "value": "hello"
}

Request JSON Object:

value (string) – the new value of the Tag (empty string is allowed)

Example response:

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

{
   "name": "%test_tag%",
   "value": "hello"
}

Response JSON Object:

name (string) – The name of the Tag. It must start and end with a %. There can not be any other % in the name.
value (string) – The value of the Tag.

Status Codes:

200 OK – no error
404 Not Found – requested Tag does not exist for this Device Type

Delete a Tag of a Device Type¶

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/tags/(string: tag_name)/¶

Delete one Tag configured for a Device Type.

Authorization rights: minimum Group Admin.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/tags/%test_tag%/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

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

{}

Status Codes:

200 OK – no error (if the Tag does not exist it is also a 200)

Delete several Tags of a Device Type¶

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/tags/¶

Delete a list of Tags configured for a Device Type.

Authorization rights: minimum Group Admin.

Example request:

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

{
   "names": ["%test_tag%", "%random_tag%"]
}

Request JSON Object:

names (array) – The list of Tags names to be deleted

Example response:

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

{}

Status Codes:

200 OK – no error (if some of the Tags do not exist it is also a 200)

Group Device Type Properties¶

The Device Type’s Properties are the equivalent for the Device Types of the additional properties of an Access Device. It is an abstraction mechanism (with data types) on top of the real tags. It is based on properties defined in the Phone Type object of the APIO (not described in this guide).

Retrieve list of Phone Types¶

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/¶

Retrieve the list of Phone Types with some filtering.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/advanced_tags/  HTTP/1.1
Host: example.com

Request JSON Object:

withGroupPropsFiltering (boolean) – (Optional) If true, returns only the Phone Types with Group Properties defined in the APIO DB are returned. If not present, the default value defined in the settings is used (see below).
withAsFiltering (boolean) – (Optional) If true, returns only the Phone Types with alrerady some devices created at Group level are returned. If not present, the default value defined in the settings is used (see below).

Example response:

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

{
   "disableLedMissed": false,
   "disableLedVm": true
}

Response JSON Object:

phoneTypes (array) – A list of phone types. See Phone Type Attributes.

Status Codes:

200 OK – no error

Retrieve list of Properties for a Device Type¶

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/advanced_tags/¶

Retrieve the list of Properties currently configured for a Device Type. It must be noted that only the properties already configured (so with a matching tag defined) will be returned.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/advanced_tags/  HTTP/1.1
Host: example.com

Example response:

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

{
   "disableLedMissed": false,
   "disableLedVm": true
}

Response:

The response is not defined at Product level as it will fully depend on what has been configured in the corresponding Phone Type object.

Status Codes:

200 OK – no error
400 Bad Request – with error code 18 (INVALID_OPERATION) it will means there is no Phone Type object corresponding to the device type requested in the url

Modify some Properties of a Device Type¶

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/advanced_tags/¶

Update some properties of a Device Type. If the property was already defined (the corresponding tags exists) it will be modified. If the property was not yet defined (the corresponding tags does not exist) it will be created.

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/advanced_tags/  HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "disableLedMissed": false
}

Example response:

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

{
   "disableLedMissed": false,
   "disableLedVm": true
}

Request JSON Object:

rebuild_files (boolean) – (Optional) Ask to rebuild, or not, the configuration files of all devices of this type if at least 1 tag is touched. If not present the behaviour will be defined by a global configuration parameter.
reboot_files (boolean) – (Optional) Ask to reboot, or not, all devices of this type if at least 1 tag is touched. If not present the behaviour will be defined by a global configuration parameter.

Request:

The rest of the content is not defined at Product level as it will fully depend on what has been configured in the corresponding Phone Type object. Note that properties not defined are ignored.

Response:

The response will contain all the properties currently defined. But its content is not defined at Product level as it will fully depend on what has been configured in the corresponding Phone Type object.

Status Codes:

200 OK – no error
400 Bad Request – with error code 18 (INVALID_OPERATION) it will means there is no Phone Type object corresponding to the device type requested in the url

Remove some Properties from a Device Type¶

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/advanced_tags/¶

Remove some properties from a Device Type. If the property was already defined (the corresponding tags exists) it will be removed. If the property was not yet defined (the corresponding tags does not exist) it will be ignored.

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/device_types/Generic_SIP_Phone/advanced_tags/  HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "properties": ["disableLedMissed"]
}

Request JSON Object:

properties (array) – the list of properties to be removed from the Device Type (the values are not defined by product team but depends on what has been configured)
rebuild_files (boolean) – (Optional) Ask to rebuild, or not, the configuration files of all devices of this type if at least 1 tag is touched. If not present the behaviour will be defined by a global configuration parameter.
reboot_files (boolean) – (Optional) Ask to reboot, or not, all devices of this type if at least 1 tag is touched. If not present the behaviour will be defined by a global configuration parameter.

Example response:

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

{
   "disableLedMissed": false,
   "disableLedVm": true
}

Response:

The response will contain all the properties currently defined (after the delete). But its content is not defined at Product level as it will fully depend on what has been configured in the corresponding Phone Type object.

Status Codes:

200 OK – no error
400 Bad Request – with error code 18 (INVALID_OPERATION) it will means there is no Phone Type object corresponding to the device type requested in the url

Configuration Information for the actions on all devices¶

For adding, removing, updating some of the properties, it will have an impact on Custom Tags. To be effective almost immediately, it could be needed to ask the AS to rebuild the configuration files and then to ask the phones to download it and reboot.

If this is nis not explicitly asked in the input date to do it or not then a default behavior will be applied.

This default behavior is defined by the following parameters:

"GROUP_DEVICE_TYPES_REBUILD_BY_DEFAULT": false,
"GROUP_DEVICE_TYPES_REBOOT_BY_DEFAULT": false,

Settings description:

GROUP_DEVICE_TYPES_REBUILD_BY_DEFAULT: By default rebuild configuration files or not. Default is false.
GROUP_DEVICE_TYPES_REBOOT_BY_DEFAULT: By default reboot the devices or not. Default is false.

Configuration Information for the list of phone types¶

When asking to get he plist of phone types at Group level, several filters can be applied. If this is nis not explicitly asked in the input date to do it or not then a default behavior will be applied.

This default behavior is defined by the following parameters:

"GROUP_DEVICE_TYPES_GROUP_PROPS_FILTER": true,
"GROUP_DEVICE_TYPES_AS_FILTER": false,

Settings description:

GROUP_DEVICE_TYPES_GROUP_PROPS_FILTER: Default value for the filter on Group Properties. Default is true.
GROUP_DEVICE_TYPES_AS_FILTER: Default value for the filter on with existing devices. Default is false.

Actions on all device of a Device Type¶

Reboot all access devices of a device type¶

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/reboot_phone/¶

This API will ask all the phones of a certain device type to reboot (via the Application Server).

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/device_types/foodevice/reboot_phone/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

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

{}

Status Codes:

200 OK – no error

Rebuild config files of all access devices of a device type¶

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/device_types/(string: device_type_name)/rebuild_files/¶

This API will ask to rebuild the config files of all the phones of a certain device type (via the Application Server).

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/device_types/foodevice/rebuild_files/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

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

{}

Status Codes:

200 OK – no error