Reference13r1:Concept App Service Yealink

From innovaphone wiki
Jump to navigation Jump to search

The Provisioning App for Yealink is an App Service which can be installed on an innovaphone App Platform and is used to easily provision Yealink SIP devices with myApps. This enables the user to easily set up a Yealink SIP device via his profile. The administrator also has the possibility to set up a Yealink SIP device for a user via UsersAdmin. When a Yealink phone is provisioned on Profile or UsersAdmin, the Yealink App connects to the Yealink Redirect To Provisioning Server (RPS) and redirects the phone to the Yealink App on the customer App Platform, where the config files will be requested afterwards. These config files are generated on the Yealink App with user data received from Users and device configuration data received from Devices.

Applies To

  • innovaphone PBX from version 13r1sr18

Requirements

  • innovaphone PBX
  • innovaphone Application Platform
  • Firmware V13r1xx
  • Devices App
  • Profile App
  • Users Admin App
  • MAC address of the Yealink Device (usually on the back of the device)

Apps

Yealink App (innovaphone-yealink)

Yealink-App.png This is an App, where the administrator can check the communication between the RPS and the Provisioning App.

Also some config items can be edited on the hamburguer menu:

  • RPS account (usually standard if you don't have an own RPS account)
  • Interval for phone updates
  • Timeserver and timezone
  • SIP protocol (TCP or TLS)

Parameters:

Websocket
to get the URL of the app, so the phones can be redirected
Admin
to be able to edit the device on the User object
Services
needed to use the Devices API (com.innovaphone.devices), so the phone configuration can be received
Devices-API
gives access to the Devices App, which is needed for the provisioning of phones

Parameters for Profile App Object:

Yealink
gives access to the Provisioning App, which is needed for the provisioning of phones

PBX Manager Plugins

Yealink

With the Yealink plugin App Objects can be created, edited and deleted on the PBX.

Configuration

  • Download the Provisioning App for Yealink via App Store.
  • Install the App on the App Platform Manager.
  • Create a instance for the Provisioning App for Yealink on the App Platform Manager.
  • Create a new PBX Object with the PBX Manager Plugin.
  • Assign App to authorized (admin) users, which will be allowed to open the Admin UI of the Provisioning App.
  • Set access in the Profile App Object in the advanced UI to the Provisioning App for Yealink. This gives access to the Provisioning App for Yealink, which is needed for the provisioning of phones.

Do not forget to check the default configuration on the hamburguer menu of the Provisioning App. There it is possible to set:

  • Your own RPS account
  • The interval when the phone must ask for updates
  • The default device configuration parameters (only updated when then phone requests the configuration)
    • NTP server
    • Timezone
    • Location
    • Media Relay (Set Media Relay Flag on the HW-ID of the PBX user object and disable ICE on the phone, DO NOT set media relay for the whole pbx!!!)
    • TLS (To use SIP/TLS for registration, you have to put the root certificate (Yealink Equipment Issuing CA or Yealink Root CA) for devices from Yealink in the trust list of the Reverse Proxy and PBX. Please ask Yealink for this Yealink Equipment Issuing CA certificate or Yealink Root CA.)
    • HTTPS (This defines if the Provisioning URL configured on the Phone must be HTTP or HTTPS)

Also refer to this illustrated configuration document on how to deploy Yealink devices.

Provisioning workflow

Provisioning App Workflow

First of all, when the App starts running it publishes a Provisioning API (com.innovaphone.provisioning), so that the Profile App and Users Admin App will be able to find it as provider. For this Profile and Users Admin must be able to access the Provisioning App, which can be configured on each App Object on the PBX. This is also automatically configured on the PBX Manager when adding or editing a Provisioning App Object. The Provisioning App also registers its URL with a server name (which is usually the 24 first characters of the domain name) on the Yealink RPS everytime the app service starts, which will be used to redirect the devices afterwards.

On Profile (or Users Admin) the provisioning of a new phone is started and it looks for the Provisioning APIs that have been published. The user must select which one is the right one for the given phone (in this case Yealink) because there could be more than one manufacturer. Afterwards, the provisioning categories and the provisioning code are requested to Devices and saved on the Users Service. Then the MAC address must be entered on Profile. This with the provisioning code (and also other user-related data like username) is sent from Users to the Provisioning App.

Next the Provisioning App opens a Sysclient connection and when it is set Devices sends the configuration for the phone through the Sysclient connection. This connection remains opened and it is used to receive configuration updates.

Finally the phone is redirected on the Yealink RPS, which will redirect the phone to the Provisioning App when it requests for the configuration. This can be triggered it by doing a Factory Reset. The phone requests the configuration by sending a GET request to the app, which will be answered with the configuration file. If an update timeout has been defined on the Yealink App, the phone will keep requesting for a new configuration file periodically to the Provisioning App. After the configuration file has been sent, the device on the user object is edited to update the Media Relay, TLS only and Reverse Proxy flags.

How to provision a device

Yealink devices can be added by provisioning a new phone but selecting Yealink instead of innovaphone as the manufacturer. From a user point of view this should work as follows:

  • Open myApps/Profile/My phones and select "+ Phone" to add a new device
  • Then choose the manufacturer of the phone, in this case Yealink
  • A drop down is displayed to select a category
  • Enter the MAC address of the Yealink device (must be entered without ":" or "-")
  • Enter a name for this device, which will be the name of the app displayed on the home screen afterwards
  • Unpacks the phone and connects it to the network (or do a factory reset on the device)
  • The phone looks for the configuration and when it has finished the user should be able to make calls

At the end:

  • A new app must have been added to the home screen
  • A new device must have been added to the user object (this can be checked on Users Admin or on the PBX)
  • A new entry for the given device must have been added on the Devices tab of the Provisioning App
  • The device must have been added to the Devices App

User interface

RPS history tab
Devices tab

In the user interface of the administrator app there are 2 tabs: RPS history and Devices.

On the RPS history tab, the history of the comunication between the app and the Yealink RPS can be seen. Here the commands sent from the app to the Yealink RPS with their answers are displayed. To be considered:

  • Everytime the app starts, an ADD SERVER command is sent to register the URL of the app to the server name. After the first start of the app, this command will be always answered with Error: The server name has been used because the URL was already registered the first time.
  • Every time a phone is provisioned, first a DEREGISTER DEVICE command is sent to remove it from the RPS if the phone has already been provisioned before. Then a REDIRECT DEVICE command is sent to redirect the config requests from the phone to the app. If the phone has not already been provisioned before, the first command will be answered with Error: Invalid MAC(s).

On the Devices tab, the list of all the devices provisioned by the app and their status are displayed. To be considered:

  • If a phone is not on the list, the device data has not been received by the app.
  • If the value of the Device Config column is not Config Received, then the sysclient Connection between Devices App and the Provisioning App has not been set or the configuration has not been received.
  • If the value of the Phone Requests column is not Provisioned, that means that the phone has still not requested the config file to the app. In this case, a Factory Reset should be done on the phone.
  • On the Last Config Request column, the timestamp of the last config request done by the phone is displayed.

Known issues

Trusted Certificates

It the phone configuration has been received but after a factory reset no phone requests have been received, you may need to disable the security certificates in the Yealink phone web interface under Security>Trusted Certificates:

  • Only Accept Trusted Certificates -> Disabled
  • Common Name Validation -> Disabled
  • CA Certificates -> All Certificates

Related Articles

  • SDK Integration (if the content is available)