Course13:IT Connect - 13 Design of the Application Platform

From innovaphone-wiki

Jump to: navigation, search

Design of the Application Platform

Contents

Overview

Be warned, this is somewhat more in-depth technical stuff wink
For the course, you don't need to read it at all. But if you're a bit curious, this is your place.

myApps

As you have seen in the course, the myApps client allows you to www.png organize Apps conveniently.

myApps itself is a web application (actually a web site hosted on your innovaphone PBX). It uses HTML5 (with DOM Storage) and JavaScript. As such, it runs inside a window (or tab) of your browser.


As long as this browser is a fairly recent one (so that it supports all the latest greatest tech stuff we use), this is all you need. For more details regarding the requirements, see fish-help.png Concept myApps. We are testing myApps and our own Apps on
  • Chrome
  • Firefox
  • Safari
  • and Edge
But other browsers may work too (subject to the requirements mentioned above).

Login

The first thing myApps will do is to log-in to the PBX. For this, it will ask you for your credentials. However, it will do so only for the first time. The next time you start myApps in this browser, it will not ask again.

While this sounds (and is) convenient, the question is: how does that work? Does myApps store your credentials somewhere on your PC. The answer is: not really.

When you log in, myApps will use your credentials to request a so-called permanent session for you. This session will have a session id and a session password (which is different from your user password). These two are valid credentials for you just like your user name and password is!

Session id and password are stored in your browser's DOM storage (this is like a little database your browser has). When myApps is started on the same browser again, instead of asking for your credentials, it will retrieve the permanent session properties from the local DOM storage and use them to log-in to the PBX.

The PBX will store a limited number of permanent sessions per user (currently 8, but this may change) so you can have multiple browsers (like on your PC and on your mobile) which are logged-in to the PBX with myApps. When more permanent sessions are created than can be stored in the PBX, the oldest one is silently discarded in the PBX. In this case, when you start the browser that used this session, the PBX will reject the permanent session id and myApps will ask for your credentials again.

Of course, neither the real user credentials nor the permanent session properties are sent over the wire in clear. Also, users can screenshot.png see the permanent sessions currently stored in the PBX for them and delete them if need be.


How myApps talks to the PBX

The myApps HTML5 and Javascript code of course is received with some HTTP GET requests. This is how browsers work.

However, once it is loaded and starts up, myApps will establish so-called WebSocket connections to the PBX. These are like normal HTTP connections initially (that is, they are initiated with an HTTP GET request) but upgraded to a bidirectional, asynchronous connection later on.


There is no need to understand in very much detail what a WebSocket connection is and how it differs from plain HTTP. But you should note that
  • it starts as HTTP (so it will use the same ports)
  • it is asynchronous (that is, messages can flow from the client to the server and vice versa at any time)
  • the message content is encoded in JSON format
  • your firewall may have a problem with it wink


Debugging myApps

When myApps doesn't start up properly it's time to debug what is going on.

Of course, you could use WireShark to sniff the network traffic. But myApps usually uses HTTPS, so you will see encrypted traffic which won't tell you that much easily. Fortunately, all these modern browsers have nice debugging tools built-in. In most of them, you can open those by pressing F12. The screenshots used in this book are taken from a Firefox browser but the other browsers provide similar features.

When you press F12, your browser tab will be split and a bunch of tools is shown which allow you to debug.

The Network tab

We're initially interested in screenshot.png the Network tab to see if myApps is able to establish the websocket connection to the PBX. For this, we filter the traffic to be shown to WS (WebSocket) only. There should be a request from the browser towards https://hq.dvl-ckl2.net/PBX0/APPCLIENT/<some-number>/websocket (assuming your PBX's DNS name is hq.dvl-ckl2.net).
  • the domain name in the Request URL tells you if myApps knows the correct PBX name
  • the Remote address tells you if your DNS correctly resolves this name
  • the Status code: 101 Switching protocols tells you that the PBX recognized the request and upgraded the connection to websocket
To see what happens within this new connection, we switch to the Console tab.

The Console tab

In screenshot.png this tab, you can filter the messages shown by type. Select Logs and Requests for now.

myApps will log all incoming (recv from pbx) and outgoing (send to pbx) websocket messages along with their content for you. Fortunately, the JSON encoding is pretty self-explaining, so you can just read what is in the messages.

The first message is sent to the PBX and looks like {"mt":"Login", "type":"user", "userAgent":"myApps (Firefox)"}. JSON messages consists of a number of name/value pairs separated by a colon (:). So here we have
  • mt/Login
  • type/user
  • userAgent/myApps (Firefox)
The mt name stands for message type and you will see it in just any message that is sent or received. Here it is Login, so this is the begin of a fresh login (using the users real credentials, a subsequent login using a permanent session looks a bit different).

The PBX responds with an Authenticate message (recv from pbx: {"mt":"Authenticate","type":"user","method":"digest","domain":"dvl-ckl2.net","challenge":"ec6af491ab3e622c"}). myApps now does a little voodoo based on the information in this message and your credentials and then sends a new Login message to the PBX which includes the result of the voodoo (send to pbx: {"mt":"Login", "type":"user", "method":"digest", "username":"ckl", "nonce":"36d5d54730485685", "response":"1a21e5f25622c16e7d6ca4675a94a396013d256ac5bbbf52ec84befbb2a8c871", "userAgent":"myApps (Firefox)"}).

Now the PBX is pleased and sends back a LoginResult message ({"mt":"LoginResult", "info": {"user": {"domain":"dvl-ckl2.net", "sip":"ckl", "guid":"c7fdf210727d5c0148250090334000b3", "dn":"Christoph Künkel", "num":"10", "email":"ckl@innovaphone.com"}, "session":{"usr":"67aba3887d21987e0b22c58d5e71bd6d18f034739acea7ba3c28d7424c6440fa", "pwd":"66930d771578eda5152c6261d6768ba8204b52728295bc"}}, "digest":"7910bdd91ac29816293cd46d786bf7eaba6d1908b991fbdd846f4565fcc9f328"}). This message includes the session property which contains the session id and session password for the new login.

If the login fails, the LoginResult message would look like so for example: recv from pbx: {"mt":"LoginResult", "error":2, "errorText":"Authentication failed"}.

For the next login (where the stored permanent session is used), the Login message would look like send to pbx: {"mt":"Login", "type":"session", "userAgent":"myApps (Firefox)"}, you can see that the type is set to session instead of user.

You might have observed that the Authenticate message received from the PBX included the method member set to digest. This is because the PBX used here uses digest authentication. Depending on the configuration, it could also use ntlm instead. The message details would be a bit different then but still, there would be a final LoginResult message with a good login.


Providing information for the innovaphone support

Browser trace

(Further Hints) When you run into problems with myApps and open a support ticket for this, you can simply copy the entire content of the Console tab and attach it to your ticket.

So
  • open the developer console with F12
  • clear the console window
  • reproduce the problem
  • save the complete content of the console tab in to a file
  • attach the file to your ticket

The launcher

We already talked about the myApps launcher which provides some additional functionality.

The launcher is an application that you install on your system just like any other application. It is currently available for Windows, iOS and Android.

Technically, the launcher is a screenshot.png separate program with a browser window internally. The myApps web code then runs in this window. Being a separate program (instead of just a website running in a browser) technically offers some more options. For example, the myApp launcher can listen to and handle keyboard events such as Hotkeys (for example to start a call when a phone number is selected in another application).

In addition to that, there are screenshot.png several platform specific services
  • audio
    speaker/headset IO for the softphone
  • video
    native video (used instead of WebRTC video which is used if myApps runs without launcher)
  • ringer
    for ring tones
  • app sharing
    native app sharing supporting both sharing and viewing (used instead of WebRTC app sharing which is used when myApps runs without launcher only supports viewing)
  • outlook
    access to your local MAPI contact information
As you might already have guessed, the launcher would screenshot.png talk to these services via websocket connections.

On a Windows platform, the myApps launcher comes with its own browser (which is known as wikipedia.ico Chromium ). On iOS and Android, the systems native browser is used.

Providing information for the innovaphone support

Browser trace

On chromium however, F12 does not work to open the developer console. Instead you would right click in the launcher and screenshot.png select Inspect.

So
  • open the developer console with right-click on the myApps launcher window
  • clear the console window (right click on the console tab and Clear console)
  • reproduce the problem
  • save the complete content of the console tab in to a file
  • attach the file to your ticket
myApps trace files
If more information is needed, support may ask for "myApps trace files". There is a link Open trace file when video2.png you right click on myApp's tray icon. This will open myApp's working directory. You can simply zip all the files in there and attach them to your ticket.

This is what is meant when the support guy says "can I have the myApps trace, please".

Support may ask you to change the trace levels. This is done video2.png in the extended myApps settings. When you tick the Browser check-mark here, all log messages sent to the browser's developer console are also copied to the trace file. It should always be checked therefore.


Apps

The myApps client (either running in a web browser or in the launcher) does not provide any application functionality. Functionality is provided by so-called Apps.

An App is a piece of web- and Javascript code that is started by myApps and runs in the same browser tab as myApps does (for the HTML geeks: it runs in a separate IFRAME). It can communicate with the myApps client (using inter-window messaging in Javascript).

When an App is started, it can safely assume that the user is successfully logged-in to the PBX (as otherwise, it would not be started by myApps). This provides a convenient single sign on for all Apps running in myApps.

The app can, in addition to being loaded from its App Service, establish a websocket connection to the App Service. With this connection it can exchange service specific messages with the App Service.

Apps are loaded either from the PBX (then they are known as PBX Apps) or from an App Service. An App Service is a web service program running in the App Platform. The App Platform is a very light-weight, high performance Linux system running either on our latest gateway generation (IPxx11 or up) or in a Virtual machine (such as VMware or Hyper-V). Finally, Apps can talk to the PBX and/or their App Service using websocket connections.

An App Service serves as a web server to download the App code from and also has a websocket interface that provides application related services.

So here we have a screenshot.png fuller picture



A single App Service can provide multiple Apps. You have already seen this with the Users and the UsersAdmin App. These are two different user interfaces provided by the same App Service (which makes sense, as both deal with the management of user information).

App Instances

Strictly speaking, Apps do not talk to App Services. Instead, they talk to App Service Instances. These are instances of the same service (that is, they provide the same HTML- and JavaScript-code as well as the same set of messages to be exchanged in their websocket connections). However, different App Service Instances work on different data. All persistent data (service data and configuration) of an App Service Instance is stored in a separate database on the App Platform (no files used).

App Service Instances are identified by a domain name. Technically, this could be just any identifier. However, the Install creates all instances with a domain name that matches the domain name of your PBX (so it is dvl-ckl2.net in your case). But you could create additional instances from inside the App Platform manager (known as Apps in myApps). In normal installations you would rarely create multiple instances.


Multiple instances can be used in multi-tenant installations, where a single App Platform may serve multiple customers. You would create one instance per App Service and customer and you would use the customer PBX's domain name to identify all the instances that serve a single customer.

We have seen another application of multiple App instances before with the Files App. To avoid exponential growth of backup files, the install creates 2 instances of the Files App (called Files and Backup Files). The screenshot.png only configuration difference between those 2 instances is that Backup Files has the Exclude from overall backups check-mark set, so that the backups are not included as part of the next overall Apps backup.

Domains in Devices
Although you could do the same for the Devices App Service (create multiple instances as shown in the picture above), you normally would not. Instead, you would create multiple domains inside one single Devices Instances. This instance then knows about all devices of all tenants, which is convenient and also has improved performance (as multiple instances would also result in multiple databases used whereas the shared approach in Devices works with a single database (as only one instance is used)).

The manager

So far, we have seen that the Application Platform consists of a very light-weight Linux kernel where instances of App Services run. As you might expect, an App Service corresponds to a Linux process (note that an instance is not a process, all instances of a single service run in the same process). In addition to that, we also have 2 basic processes: a web server and the manager.

The web server does what you would expect: it receives web requests and forwards them to the appropriate App Service.

The manager is a bit like an App Service, except that it never has multiple instances and it already exists, when the bare Application Platform has been installed.

It is responsible for installing, removing, starting and stopping of the App Service processes and instances. Also, it provides functions such as backup and restore of App Service instances. When an App Service is installed, the corresponding executable is copied to the system. When an instance is created, its database is created.

So now we have a pretty complete picture of the screenshot.png App Platform's structure.

You have access to the manager's user interface with the screenshot.png Apps App. You can also access the manager directly using your App Platform's IP address or domain name (for you, this would be http://apps.dvl-ckl2.net/ or http://172.31.31.12/). In this case, you will be asked for a password. By default this is simply pwd. Normally, the Install would replace it with the random password chosen during the install process. However, as you might recall, we run the install in a somewhat special mode where the default passwords are kept. So for you, the password is still pwd.

APIs

As we said before, Apps communicate with the myApps client (using HTML5 Windows Messaging). Through windows messaging, myApps itself offers a number of service functions for Apps. A set of such functions is known as API and has a distinct name (for example, the API that myApps offers is known as com.innovaphone.client). Apps could connect to this API and send requests to this API and myApps would execute those on behalf of the calling App (for example, by sending a { mt: "SetAttachedToHome", reference: "id=13#s=doe&d=John%20Doe", attached: true } message to com.innovaphone.client, a link to an object managed by the calling app would be placed on the users home screen). A calling App is known as API consumer.

Apps can register as API provider with myApps too. For example, myApps knows of an API called com.innovaphone.search. This API has some messages to search for users given a name (Search) and to return search results (SearchInfo). While the phone App registers with this API as a consumer, the users and contacts App register as provider. So when the phone App searches for a user, it would send a Search message to the com.innovaphone.search API which includes the search string. myApps would dispatch this message to both the users and the contacts App. Also, it would forward incoming results from both (SearchInfo) back to the phone App.


Finally, Apps can also register their own APIs with myApps. This could be useful for a 3rd party App for example that wants to expose its services to other Apps.

Access to APIs

As an administrator, you do not need to care about APIs - except for one thing: access to API providers is user-based and must be granted to users just like access to Apps must be granted to users. It is not the App that consumes an API that needs access to the API provider. It is the user. And it is not the API the user needs access to. It is the API provider.

When for example the phone App sends a Search message to the com.innovaphone.search API and the user has no access rights to the usersapis API provider, myApps would simply not forward this request to the usersapis API provider (which is part of the Users App) then the phone App would not be able to find any PBX user. Or, the other way round: the administrator must grant users access to API providers (we'll look in to that in a minute).

PBX configuration

As you have seen in the training, all the devices your installation is made up of are listed and managed in the Devices App (and thus all the data is in the single Devices App Service instance called dvl-ckl2.net created by the Install for you). But how does myApps find all the Apps and the App Platform?

This information is stored in specialized PBX objects available in the PBX's advanced user interface. These are
  • AP type objects to store information about Application Platforms
  • App type objects to store information about Apps and API providers

AP objects

An AP type object is used to make an Application Platform known to the PBX. It has the following properties:

General tab


  • Long Name
    The name of the Application Platform as displayed in myApps.
    The Install uses the long name AP for your Application Platform
  • Name
    The id of the Application Platform as shown for example when assigning Apps to users.
    The Install uses the name app
  • Password
    This is used as a shared secret between the PBX and the Application Platform. It must match the password screenshot.png stored as Manager password in the Application Platform's manager App (which is called Apps by the Install)

AP tab


  • URL
    The URL to the Application Platform's manager App Service.
    It looks like http://app-platform-DNS-name/manager/manager-domain-api, so in your case https://apps.dvl-ckl2.net/manager/manager-domain-api
    You can not configure an URL of your choice here. Instead, you simply have to do it "right" - as shown above. The only thing you migth ever want to change here is the host name (if you move from an IP-based to a DNS-based setup for example)
  • Account
    Usually left empty

     

App objects

An App type object is used to make an App or an API-Provider known to the PBX. It has the following properties:


General tab


  • Long Name
    The name of the App as displayed in myApps (not used for API-Provider as they are not shown to users in myApps)
  • Name
    The id of the App or API-Provider as shown for example when assigning Apps to users.
  • Password
    This is used as a shared secret between the PBX and the App Service instance on the Application Platform. It must match the password screenshot.png stored as Password in the Edit instance dialog for the App Service instance in the manager App
There are various other settings (explained below). However, these are not really values you have a choice on. Rather, there are "correct" settings which depend on the nature of the App. So you can either do them exactly as required by the app, or you can do them wrong.

(Further Hints) For this reason, you usually do not configure anything here manually. Instead, you either use the Install to do it for you, or you use the specialized plugins found in the PbxManager to create them. They do know how to do it correctly.

If you for whatever reason need to do it manually, you will find the respective documentation in our wiki. Each App Services has a wiki page and the settings for the App object are described in the Apps section. See fish-help.png Concept App Service Users for the Users App Service as an example.

App tab


  • URL
    The URL to the App Service instance.
    It looks like http://app-platform-DNS-name/app-service-id/domain/interface, so in your case the URL for the UsersAdmin App for example is http://apps.dvl-ckl2.net/dvl-ckl2.net/usersapp/innovaphone-usersadmin. An App Service instance screenshot.png lists all its interfaces in the Edit instance dialog. Also, the interfaces and their respective configuration are outlined in the Apps section of the corresponding concept article in the wiki (for the Users App Service this would be in fish-help.png Concept App Service Users)
  • Licenses
    Some Apps require licenses. If so, you would specify here how many of the available licenses should be used by this App Service Instance
  • Hidden
    This is for apps that don't have a user interface. We have been discussing so-called APIs before. An API is such an App which merely provides an API, but no user interface
  • Plain website
    If this check-mark is ticked, myApps will consider this App as a plain (presumably 3rd party) web site. In this case, when you start the App, it will just open in myApps. No authentication to the PBX is done and no other special interaction between myApps and the web site takes place. Nothing else but the URL should be configured.
    Note that the web site must be able to run in an HTML IFRAME. Many sites do not support this and either refuse to start or behave strange in many ways.
  • Websocket
    If this flag is ticked, the PBX will create a web-socket connection to the App Service. Normally, it will be the other way round (or no websocket connection between service and PBX is needed at all). If this check-mark is ticked, the screenshot.png word connected should appear next to the URL, indicating that the PBX successfully connected the service
  • Local presence
    Ticked if the App does not store and publish its own presence. Rarely used
  • Grant Access to APIs
    the PBX itself offers some services to other services. In order for an App Service to use those, they must be ticked in this section

Apps tab


Some services need help of other services to work correctly. For example, you might recall that the Profile App (this is what is opened when you click on Edit profile in myApp's burger menu) lets you add new devices (such as a phone). This requires the creation of a provisioning code and this is a function offered by the Devices App Service. Therefore, the Profile App needs to use the Devices-API. In order for this to work, the screenshot.png devices-api check-mark in the Apps tab must be set for Profile
     
For a little practice, configure an App object that simply links to our wiki site (https://wiki.innovaphone.com)!

Easily done, here is video2.png how:
  • open the PBX's advanced UI
  • create an App object
  • give it a Name and Long Name (e.g. Wiki), password does not matter here
  • set the URL (http://wiki.innovaphone.com)
  • tick the Plain website check-mark
  • save the object
  • edit the Config User template
  • tick the Wiki check-mark in the Apps tab
  • put the new Wiki App on your home screen

User objects

Making an App available to a user

For a user to be able to use an app, it must be granted to him. This is done by ticking the corresponding screenshot.png check-mark in the user object's Apps tab. If so, the App will be screenshot.png listed in the user's All Apps page.

The app will not appear on the user's home screen though. This is normally done by the user himself (in myApps). However, if need be, you can add the App's Name to the screenshot.png list of Home Screen Apps in the User tab of the respective User object.

Making an App available to a group of users

If an App is to be made available for a number of users, you would tick the respective entries in the Apps tab of the appropriate Config Template. This can be done using the advanced UI or using the Templates PbxManager plugin.

The Install has done that both in the Config User and in the Config Admin template for you.

You can not modify the Home Screen Apps field of a user with templates.

Licensing


Some Apps require licenses. You can assign an installed license to a user in the screenshot.png User object's License tab.

You will find more about licenses in our link_intern.png Licensing guidelines.

Installing an App

So far, the Install has done all the hard work for us. Now we want to see how a fresh install of an App Service is done. This would allow us to provide different users with different contact data. In our little sample, we install a new contact directory where the admins can store away their special contact information.

These are the steps:
  • create a new App Service Instance
  • configure the App Service Instance using the PbxManager
  • define access to the Apps provided by the new instance
  • assign required licenses?
  • import data in to the App Service Instance

Create a new App Service Instance

App Service managers are created by the App Manager which is screenshot.png available as Apps in the ALL APPS area. To screenshot.png add a new instance to an already installed App service, you select the App service in the left pane and click on Add in the top ribbon. The pop-up form that appears lets you specify the instance details:

  • Name
    You can choose whatever name you want for the new instance, but we recommend that it is unique, that is, there is no other instance of any App service with the same name. Later on, you will define how the new instance is presented to end users and we recommend to call the instance here like you want to have it displayed in end-user interfaces, just to avoid your own confusion
  • Domain
    This field must match the screenshot.png System Name field of your PBX. Otherwise, the instance will not be accessible from your PBX
  • The Password is a credential shared between the App service instance and the PBX. More specifically, it must match the Password field of the App object we will create in a later step. As such, it should be strong and secure. For example, it could match the magic password the Install has created for you and which you have stored away in a secure place.
    Practically however, we will use a PBX-Manager plugin later to create the corresponding App objects. The PBX-Manager will then create a new, random, strong password for the instance anyway and share it with the App objects it creates. So the password you set here is only relevant if you do not use the PBX-Manager to create the App objects (which we do not recommend)
  • Webserver path, Database name and Database user
    These could be set individually. However, we recommend to just use the values suggested by the dialog. If you insist on using your own values, be sure that both Database name and Database user are distinct across all App services instances (really: all instances, not only the instances of this App service!)
  • Database password
    You can use any strong (that is: secure) password here. Again, we recommend to use the random password created by the Install as above
Let us create a new instance with the following properties:
  • Name: admin-contacts
  • Domain: dvl-ckl2.net
  • Password: ip411 (as this is the password we're using in the training. In real life, you would be using a strong and secure password of course)
  • Webserver path: dvl-ckl2.net/admin-contacts
  • Database name: dvl-ckl2.net.net_admin-contacts
  • Database user: dvl-ckl2.net.net_admin-contacts
  • Database password: ip411 (see above)

Define access to the Apps provided by the new instance

In order to make the new instance available to users, you first need to create some objects in your PBX. This is done in the PBX-Manager.

When you open the PBX-Manager again, you will see a screenshot.png new icon called like the name of the new instance (AP admin-contacts in our case). This can help us to create the required App objects in the PBX.

As we have discussed before, we need App objects for all the interfaces the App service instance offers. For contacts, we have three:
  • the standard contact search user interface (Contacts)
  • the elevated interface which allows import and deletion of contacts (Contacts admin)
  • the contact-Api which allows other Apps to use the contact information (Contacts API)
So when you click on the screenshot.png add contacts button you will be presented with screenshot.png 3 new buttons.


You may recall that the Contacts admin user interface also lets you search for contacts. As we anyway intend to provide the new contact directory to admins only, we do not need the simple Contacts interface. So we create only the Contacts admin and Contacts API App objects in the PBX.

We will call the Contacts admin interface screenshot.png admin-contacts-admin and the Contacts API screenshot.png admin-contacts-API. So we end up with screenshot.png two interfaces to the new App instance.

Now that we have created the App objects in the PBX, the interfaces are screenshot.png available for assignment in the Templates PBX-Manager plugin.

Licenses

Depending on the App you're dealing with, it might be necessary to also assign the required licenses to users. This is also done in the Templates PBX-Manager plugin.

Licensing information can be found in the innovaphone Licensing guidelines V13r1 found link_intern.png on our web.

Try it!

To try out the new App instance,
  • open the Admin Contacs Admin App which you see in your ALL APPS area (you don't see it? Sure you have added it to the Apps section of the Config Admin template?)
  • click on the 3 dots on the right edge of the search bar
  • click on Import contacts button
  • select the file admin-contacts-sample.utf8 which you can download from moodle
  • search for Mr. Cook (which has been imported from the admin-contacts-sample.utf8 file)
To verify that your new API works too:
  • open your phone App (hq IP Phone IP232)
  • type cook in to the Search contact... field
  • see how screenshot.png T.Cook is found
  • you can try to call him, but that won't work of course

Reverse Lookup

So now we have seen that a forward lookup using multiple directories is possible. But what about reverse lookup (retrieving caller name information based on a calling number)?

As of today, the PBX does the reverse lookup and uses only a single directory (we have discussed that in the PBX base data chapter of The individual Device User Interface). So you need to choose which directory shall be used for reverse lookup and can not use multiple nor user specific directories.
     

Re-Installing an App Service

     
In the last chapter we have seen how a new instance of an App service is created and the corresponding App objects are set up. Now we will have a look at how entire App services are installed and removed.

For this, we will install a Voicemail service in a different language (you should have installed the English version during the Install, so we can now try the Italian one).

Removing an instance

Removing an App service instance involves configuration on the PBX and on the App Platform.

PBX


On the PBX, you need to remove the App objects that points towards the instance you are going to remove. These are easily removed using the respective PBX-Manager plugin.

Before you do this, you may want to un-assign the respective App(s) from users using the Templates PBX-Manager plugin. This step is not strictly required, but it helps to remove unnecessary data from the PBX configuration. In our case, the App object is called Voicemail en (voicemail-en) and we will find it as an App to be assigned to users in the Config User template.

So the first step would be to video2.png remove the Voicemail en App from the Config User template.

Now we delete video2.png the App object itself from the PBX using the PBX-Manager plugin. In that case, the "App object" is a little special, as it has some extended functionality within the PBX. So it is a derivative of an App object of type Voicemail.

App Platform

The only thing left now is to video2.png remove the instance from the App platform itself. We do this of course in the Apps manager.

You will note that now the AP Voicemail en entry in the PBX-Manager is gone (which is why we first remove the PBX objects using the PBX-Manager plugin and then remove the instance).


Removing a service

Now that there are screenshot.png no more instances left for the Voicemail_en App Service, we can video2.png remove the entire App service. The Voicemail_en App service is now gone.


Installing an App service

While an instance is a runtime environment of a service including both data and configuration (both stored in a database on the App platform), an App service basically is an executable including all static files (for example web pages, icons, pictures, voice prompts etc.).

This is why voice mail services in different languages are in fact different services (you might have assumed that they are different instances of the same service). They have different (language dependent) voice promptd and XML scripts - so they are different App services.

App services are downloaded from the App Store. This is a website (usually hosted by innovaphone) that has App services available. The App Store is accessed from within the Apps platform manager. You can browse through the available App services and select one for installation.

As we intend to install the Italian voicemail, go to the App Store and video2.png download the Voicemail_it App service.

Create the instance

It should be obvious now how to video2.png create the required instance for the new App service.

Once this is done, a new entry Voicemail_it appears in the PBX-Manager which allows you to video2.png configure the Voicemail object in the PBX. Use Voicemail IT (voicemail_it) as Name (sip) and 8 as Number please.

So far, so good and easy. However, if you now call 810 from your phone (the IP232) and type the voicemail PIN (8765), you will hear an error message and the call will be disconnected. Why is this?

First of all, the PBX-Manager plugin (as of June 2019) does a little mistake when it creates the Voicemail object in the PBX: the PBX attribute is wrong (master, should be hq). This can be video2.png fixed easily using the Advanced UI. Unfortunately, this alone doesn't fix the problem.

More relationship between PBX and App service instance

To understand what is going on here, we need to understand how the Voicemail object in the PBX works.

First of all, the voice dialog is controlled by an XML script that is stored in the voicemail App service instance on the App platform (if you are curious, you can have a look at it by retrieving https://apps.dvl-ckl2.net/dvl-ckl2.net/Voicemail_it/131916/vm.xml with your browser). In this script, voice prompts are referenced and used, which are also stored as part of the instance.

In addition to that, when a voicebox is created or a call is recorded, files are stored in the instance (using the WebDAV protocol). For this, write access is required obviously and the credentials for this must be configured in the PBX too. The PBX-Manager plugin can't do that currently.

So we do have to video2.png do it manually:
  • in the advanced UI, go to Services/HTTP/Client
  • add an entry in the Authenticated URLs as follows:
    • URL: https://apps.dvl-ckl2.net/dvl-ckl2.net/Voicemail_it
    • User: Voicemail_it
    • Password: here you can choose a new one, we will set the same password later on in the Voicemail PBX object and in the App service instance. As we are in the training, you can use ip411 - in real life, you would choose a strong and secure one
  • go to PBX/Objects and edit the Voicemail IT object
  • change the Password to the same you use for the Authenticated URLs above (ip411)
  • close the advanced UI in Devices and open the Apps platform manager
  • edit the Voicemail_it instance of the Voicemail_it App service
  • change the Password to the same you use for the Authenticated URLs above (ip411)
When you now call 810 from your phone (the IP232) and type the voicemail PIN (8765), you will hear your correct greeting message (well, if you don't understand Italian, you will at least notice that it is much longer than before and the call is not disconnected).
Personal tools