Reference13r3:Concept App Service Devices

From innovaphone wiki
Jump to navigation Jump to search
There are also other versions of this article available: Reference13r1 | Reference13r2 | Reference13r3 (this version) | Reference14r1

The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation.

Applies To

  • innovaphone PBX from version 13r1


Devices App (innovaphone-devices)

This is the standard UI App for Devices.


to publish the com.innovaphone.devicesui-API, which can be used to link directly to devices (which is done e.g. inside the Events app)

Devices API (innovaphone-devices-api)

This is a hidden App, which provides the Devices API (com.innovaphone.devices). This API can be used to find and communicate with devices which are registered to the Devices App.


DevicesApi must be a hidden App
to get the URL of the Devices App itself which is used for provisioning

PBX Manager Plugins


With the Devices plugin App objects can be created, edited and deleted for Devices and the Devices API on the PBX.


All innovaphone hard phones and gateways starting from version 13r1 can establish a registration inside the Devices App and therefor administrative tasks can be performed through the App.


In a hosted environment, it might be needed to add multiple domains to the Devices App.
After the initial installation of Devices through Install, you have administrative rights and can add more domains.

Administrative rights

You have administrative rights if the configured PBX App object for Devices uses the password of the instance which is configured in the Manager App and the PBX uses the same domain as this instance.

Domain local rights

You have just rights to a certain domain if the configured PBX App object for Devices uses the domain password which can be configured in Devices for each domain and the PBX uses the same domain name as configured in Devices.

Assign rights to other domains

Domains can gain access to other domains by configuring these access rights in the Devices App.

Deploy passwords and access rights

During install, a domain is created inside the Devices App. There is a checkmark Deploy the domain password on all devices which is set by default and which is the same as the administrative password. If you change the domain password, all passwords on all administrative devices and app platforms which are connected to this domain will be also changed.
Since SR25: devices which are auto provisioned or provisioned through the Profile/Users Admin App will get a random password instead of the domain password. If you add a phone device manually to a domain inside the Devices App, this phone device will also get a random password. Other device types added manually or devices added with a provisioning code which has been created within the Devices App directly, will get the domain password instead.

This will also set the manager password and the SSH passwords of App Platforms.

The clear text random passwords can be requested and viewed in the settings of a device in the Devices App.

Attention: If you untick the Deploy administrative devices passwords checkmark, the password won't be deployed anymore, but also not reconfigured to the default password!
Attention: After each reconnect of a client, the password will be deployed again.
This means, if the checkmark is set and you set another password somewhere else (e.g. under General::Admin),
this password will be just valid until the next reboot or reconnect to the Devices App!
Create new random passwords

You can rollout new random passwords by unticking the Deploy administrative devices passwords checkmark and ticking it again.

Devices with multiple domains (Cloud)

In a hosted environment, you can use the Devices App with multiple domains. The corresponding instance of Devices has a configured domain and an instance password set inside the manager.

The hosting PBX has a domain inside Devices with a specific password.
If this domain name matches the instance domain of the Devices instance and the password matches either the instance password or the domain password, you will be logged in as admin and have access to all domains.

Each newly created domain has its own password inside Devices. If you create an App Object inside a PBX with this domain and the password of this domain (inside Devices), you will just have access to this single domain.

Devices also has the possibility to grant access to other domains for a specific domain.

Device connections

The Devices registration is done through a websocket connection to the webserver of the App Platform and the Devices instance (standard HTTP/s port).
The URL used can be configured manually under Devices Registration or through a new provisioning mechanism.

A binary protocol is used to transfer information between the device and the devices App. The MAC address is the unique key to identify a device.

If a device is added to a domain in Devices, the device gets a unique random password. Without such a password, a device shows up as unassigned in the Devices app. This is also the case after a long reset or when the device lost its configuration.

In such a case, the device has to be manually added again to a domain or it has to be provisioned again.

If a device is not assigned to a domain or provisioning category, it won't receive any configurations.

Devices Registrations

See Devices Registration

Second Devices Registration URL

The firmware has a second SYSCLIENT2 module, which can be configured to point to a different Devices instance and the AP Manager also has a second Devices Registration URL.

If you use this configuration option, you should take care and consider:

  • if the Devices domain from the second configuration provides a password for all devices, the password is ignored, as it would lead to inconsistend passwords otherwise (from 13r1 SR12 on)
  • the Devices domain from the second configuration should not provide Devices Configurations or Update Jobs as these might collide with configurations from the first Devices instance!

Generally, only one of the two Devices App instances connected to the device must apply changes to the device.

We strongly discourage the usage of this second configuration option due to unexpected behaviour if incorrectly used!
Never use the second URL if you use software or hardware rental!

Device information

The following data is transferred:

  • MAC address
  • device type (e.g. IPVA, AppPlatform, IP112)
  • IP addresses (IPv4, IPv6)
  • version (not searchable)

You can also search for this data inside the devices tab in the App.


Devices can be added by provisioning (both phones and gateways). The standard online provisioning looks like this:

  • a user or administrator creates a provisioning code in the Devices or Users App (this stores the Devices URL on the provisioning server side)
  • a device with 13r1 or newer is connected to the network after a long reset
  • the provisioning code has to be entered within one hour (after one hour, the Update URL isn't polled anymore)
  • the device sends this code to and retrieves the Devices URL
  • the device connects to the Devices URL and is added to the domain where the code has been created

There is also an offline provisioning mode.
There is also an automatic provisioning mode.

Note: provisioning is cancelled if the device already belongs to another domain in the same Devices instance! This prevents the unauthorized move of a device between different domains.

Devices Registration URL

The Devices Registration URL which is set through the provisioning process, always starts with wss. This is not dependent anymore on the App URL which is configured inside the PBX Devices App object.


The Devices App can be used to rollout updates.

JSON files

The update files have to be acccessible on a webserver without authentication and two json files are used to describe the used firmware and apps.
You can either use the standard innovaphone App Store for these files or your own local webserver.

Update jobs

You can configure several update jobs with different categories to organize your updates.
Update jobs are always sequentially processed and inside one update job, just 20 devices are updated at the same time.

Device update check after the update job has been already executed

If a device goes online, the newest suitable update job is searched for this device (depending on the categories).
If an update job is found, the update is just performed, if there has been no successfull update for this device in this job before and the version does not match (simply string compare).

Update errors

If an update fails, the Devices App shows an error. You may have to enable further tracing on the updated device itself to find out the reason of the failure.

  • on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0 module and take a look at the events which may already tell you the reason
  • on an App Platform, enable the App and HTTP Client trace flag on the manager
An update job is retried two times if updates inside this job failed. The retry is done ten minutes after the update job finished previously.

innovaphone myApps

The path to the App Store and the used innovaphone myApps version is updated to the version of the gateway on gateways with an enabled PBX after a successfull update.
This configuration can be found here

Inside the configuration on an update job, the flag "Do not update myApps launcher software" disables the update of the innovaphone myApps version inside PBXes.


The Devices App can be used to backup the configuration and data of Apps and devices.

Webserver requirements

Backups are stored on a webserver with or without Digest/Basic authentication and with the webdav PUT method.

Backup jobs

Backup jobs are executed sequentially. Inside one backup job, just 20 backups are performed at the same time.

Phones or gateways

The configuration file is stored. Therefor the Devices App tells the device to store the configuration with a !mod cmd UP0 /sync prot URL.

Apps on an App Platform

The databases of all existing instances and the manager are stored.
Each installed App Service can have multiple instances and each App instance has its own database.
A database contains both configuration and data of an App instance!
The manager database contains the webserver certificate and further manager related configuration settings.

The Devices App establishes a websocket connection to the manager and tells the manager where to store the backups.
The manager on the backuped App Platform itself performs the HTTP requests to store the files.

Backup errors

If a backup fails, the Devices App shows an error. You may have to enable further tracing on the backuped device itself to find out the reason of the failure.

  • on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0
  • on an App Platform, enable the App and HTTP Client trace flag on the manager


Phones or gateways

Just as always under Upload Config.


The App Service itself has to be installed on the App Platform prior restoring of a single instance.
The restoring is done in the Manager App on the App Platform itself.
The intance settings, the configuration and data are restored in a single process.

Device Configurations

You can define several device configurations. These configurations are either applied to all devices inside this domain or to selected categories.
Configurations are applied on creation and on every reconnect of a matching device.

Transfer checkmarks

Some configuration options have a specific checkmark to enable the transfer of the option.

  • Checkmark disabled:
    • configuration option field(s) are disabled
    • option values are not transferred at all
  • Checkmark enabled:
    • configuration option field(s) are enabled
    • option values are transferred, even if field values are empty

Expert configuration

The expert configuration can be used to configure different settings which are not available inside the other device configurations.
You can use the standard syntax of an update server script (see Concept Update Server for a general overview and the section on Hints for writing your update snippets (note that the remainder of this article relates to the now deprecated old mechanism, so please disregard the rest)).

Some hints:

  • the expert configuration is just executed once after a device restarted and on change of the expert configuration itself
  • the expert configuration is executed after all other device configuration types, so that you can override changes
  • to make configuration changes effective, you may also need to issue a final config write, config activate and iresetn command (see the check command for details)
  • some commands shouldn't be used inside the script:
    • times: since the expert configuration is executed only once after a reboot of the device and when changes are made, it does not make sense to use the times command
    • prot|boot: use an update job instead
    • scfg: use a backup job instead
    • vars create: this cmd will always raise the reset needed condition and the aforementioned iresetn command would always execute therefore. As a result, the devices would enter a boot loop. Be sure to avoid this using an appropriate check command and update its <serial> properly whenever the expert configuration is changed

Software rental

Regarding the Software Rental program and the Payment Method, please refer to:

Software rental can be done for innovaphone Cloud installations or for software, which operates on the customer premisis. This could eventually be customer owned hardware or a privat virtual machine, managed by the customer.

Hardware licenses

Hardware licenses have to be bound on the specific device in my.innovaphone itself and currently can't be handled within the Devices App itself. So you also need to download the licenses from my.innovaphone and upload them on the device with the already known methods.

Hardware licenses with software rental

If your device has software rental licenses, you can bind hardware licenses within my.innovaphone in the software rental project itself.

Hardware licenses without software rental

If your device does not have software rental licenses, you should bind hardware licenses in a separate non rental project in my.innovaphone.

innovaphone Cloud

Inside the innovaphone Cloud, you just have to upload your activation keys with iSCs to add licenses to one or more gateways.

Email expiry notifications

You will receive an email notification if the rental of a project expires. This notification will be sent seven weeks before the expiry and then once a week until the rental expires.
You can configure one or more email recipients in the domain settings.
If no email address is configured, the email address of the logged in user account is used.


You can download the history in the Devices App. You'll get a CSV file (semicolon separated). The date and number format depends on the selected language in the UI.
There is also an API available for automated downloas, which is described here .

Own installation

Inside your own installation, you have to register a new my.innovaphone account or you can use an existing account inside the Devices App.
One domain inside Devices belongs to one project inside your my.innovaphone company, so you can handle multiple domains with one my.innovaphone account.

Technical aspects

A new rental expiration date is calculated on each license or balance change in the domain.
So after each change new licenses with a new date are transfered to the gateways and also stored in the Devices App itself.
If the rental expires, the gateway reboots and the licenses are not available anymore.
The licenses are also transfered after each reconnect of a gateway to the Devices App.

For license and balance changes, the Devices App must be online and have access to!


You have to add (use the + symbol) a PBX and select all licenses you want to rent.
Use the apply button to really bind these licenses. Without usage of the apply button, you can just see a precalculation of the iSCs/month and the rental end date, but nothing is really charged from your balance.

Change of IP address/DNS name in PBX object

If the IP address or DNS name inside the PBX object of the Devices App changes, all currently connected clients get a new Devices Registration URL and also all clients, which connect afterwards with the old host name.


Sample firmware.json


 "devices": [
   { "id": "IP0010", "versions": [ "13r1" ] },
   { "id": "IP0011", "versions": [ "13r1" ] },
   { "id": "IP101", "versions": [ "13r1" ] },
   { "id": "IP102", "versions": [ "13r1" ] },
   { "id": "IP1060", "versions": [ "13r1" ] },
   { "id": "IP110", "versions": [ "13r1" ] },
   { "id": "IP110A", "versions": [ "13r1" ] },
   { "id": "IP111", "versions": [ "13r1" ] },
   { "id": "IP112", "versions": [ "13r1" ] },
   { "id": "IP1130", "versions": [ "13r1" ] },
   { "id": "IP1260", "versions": [ "13r1" ] },
   { "id": "IP150", "versions": [ "13r1" ] },
   { "id": "IP2000", "versions": [ "13r1" ] },
   { "id": "IP200A", "versions": [ "13r1" ] },
   { "id": "IP22", "versions": [ "13r1" ] },
   { "id": "IP222", "versions": [ "13r1" ] },
   { "id": "IP230", "versions": [ "13r1" ] },
   { "id": "IP232", "versions": [ "13r1" ] },
   { "id": "IP24", "versions": [ "13r1" ] },
   { "id": "IP240", "versions": [ "13r1" ] },
   { "id": "IP241", "versions": [ "13r1" ] },
   { "id": "IP29", "versions": [ "13r1" ] },
   { "id": "IP3010", "versions": [ "13r1" ] },
   { "id": "IP3011", "versions": [ "13r1" ] },
   { "id": "IP302", "versions": [ "13r1" ] },
   { "id": "IP305", "versions": [ "13r1" ] },
   { "id": "IP311", "versions": [ "13r1" ] },
   { "id": "IP411", "versions": [ "13r1" ] },
   { "id": "IP6000", "versions": [ "13r1" ] },
   { "id": "IP6010", "versions": [ "13r1" ] },
   { "id": "IP800", "versions": [ "13r1" ] },
   { "id": "IP810", "versions": [ "13r1" ] },
   { "id": "IP811", "versions": [ "13r1" ] },
   { "id": "IPVA", "versions": [ "13r1" ] }
 "versions": [
   { "id": "13r1", "build": "131705", "text": "13r1 dvl [131705]", "wiki": "" }


Sample apps.json


   "apps": [
           "id": "apidemo",
           "folder": "apidemo",
           "binary": "apidemo",
           "versions": [
               { "id": "13r1", "build": "131705", "label": "dvl" }
           "manufacturer": "innovaphone",
           "title": "Apidemo",
           "description": "The Apidemo"
           "id": "appstore",
           "folder": "appstore",
           "binary": "appstore",
           "versions": [
               { "id": "13r1", "build": "131705", "label": "dvl" }
           "manufacturer": "innovaphone",
           "title": "AppStore",
           "description": "AppStore"


Sample software.json


   "software": [
           "id": "myappsandroid",
           "folder": "myappsandroid",
           "binary": "myapps.apk",
           "versions": [
               { "id": "13r1", "build": "131705", "label": "dvl" }
           "manufacturer": "innovaphone",
           "title": "myApps Android",
           "description": "myApps for Android"
           "id": "myappswindows",
           "folder": "myappswindows",
           "binary": "myAppsSetup.msi",
           "versions": [
               { "id": "13r1", "build": "131705", "label": "dvl" }
           "manufacturer": "innovaphone",
           "title": "myApps Windows",
           "description": "myApps for Windows"


API to download rental history

You can download the history as a UTF-8 CSV file with simple HTTP GET requests with digest authentication.
The CSV file uses the semicolon as delimiter.

The URL to download the history is e.g.:

You can find this path by editing the instance in the AP manager.
In the listed paths, you'll find something which ends with csvapi

In the innovaphone Cloud environment, the URL can be retrieved by taking a look at the Devices App object inside the cloud PBX and replacing the ending innovaphone-devices with csvapi inside the App URL, so it looks e.g. like this:

CSV columns

Most columns should be self explaining, but the column invoice reference refers to a value which you can configure manually in the domain settings in the Devices App!

Digest authentication

You can login with two different username/password combinations, while the domain is the digest username:

  • If you use the domain and password of your Devices App instance inside the AP Manager, you have automatically access to all domains.
  • If you use the domain name of any domain as digest username and the configured domain password, you'll have access to this domain and all domains to which this domain has access to

Query parameters

The following query parameters can be used (don't forget to URL encode the parameter values, if neccessary!):

  • all: if 1 or true, the history is queried for all domains where the digest user has access to
  • domain: required, if all is not set
  • lang: the output language of the CSV file, which also controls date and number formats, e.g. en, de, ...
  • tz: the timezone for dates, e.g. Europe/Berlin
  • type: two types are available:
    • history: history which contains changes
    • overview: a monthly overview with the iSC costs at the first of the last months
  • from: unix timestamp (UTC) in milliseconds, ignored for type=overview
  • to: unix timestamp (UTC) in milliseconds, ignored for type=overview

Example requests

Known issues


The Devices App is not meant to be used with the windows SoftwarePhone standalone installation.

Related Articles