Architectural overview

The innovaphone PBX system consists of there components

Starting from version 13 the PBX provides interfaces based on Websocket/JSON protocol. A common structure is used for authentication an capability exchange. This is called AppWebsocket. Individual messages are used for various functions.

PBX

PBX objects are used to link the different modules/components of a innovaphone PBX system. There are different types used for different purposes

Table of content

• AP Object
• App Object

The App Platform (AP) object is used to integrate an AP into a PBX. For this purpose a URL to the respective App Platform Manager is stored in the AP object. A shared secret stored in the AP object and in the App Platform Manager is used for authentication. There are two types of integration of an AP:

Integration as owner

For integration as owner of the AP, the shared secret stored in the AP object must also be the AP manager instance password, which allows opening of the AP manager. The PBX domain and the intance domain must be identical in this case.

Service Provider

An AP may be used to publish services to other domains. To uses such services, an AP object is created to link the AP. A shared secrect stored in the AP for this domain and in the AP object is used for authentication.

The AP object provides the com.innovaphone.manager API which is used by the PBX Manager to access PBX Manager Plugins provided by the AP, which can be used to configure access to App Instances provided by the AP.

The PBX Manager Plugin APs is used to create the AP object to integrate a AP into the system.

An App Object is used to integrate an App Instance in the PBX. For this purpose a URL to the respective App Instance is stored in the App object. A shared secret stored in the App object and the App instance is used for authentication.

By configuration in the App object a permanent Websocket connection from the App object to the App instance can be established. This is needed if the App instance needs to access PBX APIs. Which PBX APIs are accessible by the App instance is also configured in the App object.

myApps Client

The myApps client is the main application for users and admins. It has some very basic functionality like user authentication, presence and app handling. All other functionality is added by apps that are started inside the myApps client.
myApps is designed as a webapplication that runs in a browser. But there is also an installable version we call the myApps launcher that is available for some platforms - currently Windows, iOS and Android.

• Authentication
• Organization of apps
• Runtime environment for apps
• myApps launcher

The first time the user logs-in on a new device, myApps asks for the username and password. If two-factor authentication on the PBX is activated, the user also needs to confirm the login by clicking an email link or using an existing myApps session on a different device. If the login was successful, a permanent session is created and stored in both the PBX and the local storage of the browser. This session is used for all subsequent logins on the same device. So the user is not asked for the username and password again. If the user logs-out, the session is deleted on both the PBX and the browser.

For security reasons the user can view all the permanent sessions in myApps. If a session is suspicious or not needed any more, it can be deleted. Devices using that session are instantly disconnected and have no more access to the user account.

In order to grant access to an app, the admin needs to configure a permission at the user object in the PBX. myApps then shows a list of all available apps to the user. The user can choose interesting apps from the list and attach them to a home screen for direct access. This selection is also stored in the PBX so it is synchronized across all devices of the user.

Also each app can attach items to the home screen. They are referenced by an app link: <app-name>?<app-parameters>#<client-parameters>. When the item is clicked the app is opened and the app-parameters are passed to the app. The client-parameters are used by the myApps client. They can contain a SIP URI for presence monitoring and a display name.

If the app service specified that it provides presence information the client starts a subscription for all links to that app on the home screen. The app service can then provide a badge count in the presence note that is displayed at the item.

Apps are started inside an iframe in the main window or in a separate browser window. URL parameters are used to pass some initial settings like the active color scheme and language to the app. Afterwards the communication is done exclusively using window messages between the iframe and the myApps client.

For authenticating against the app service the apps use a challenge response mechanism on the AppWebsocket connection. For creating the response digest, knowledge about the app service password is needed. Neither the app nor the client know it but the PBX does. So the app passes the challenge to the client (using a window message) and the client forwards it to the PBX (over its authenticated websocket connection). The PBX checks the following conditions before it answers the request.

• The websocket connection of the myApps client has a valid login.
• There is an app object for that app in the PBX.
• The user object has a permission for that app.

myApps provides a framework called Client APIs that can be used to communicate with the myApps client or with other apps. Apps can specify that they are a provider of an API. Other apps can then find that API provider and send messages to it for inter-app communication. This is the way how apps can do search requests or start phone calls in a different app. APIs have an ID in the reverse domain syntax like com.innovaphone.search. For each Client API - especially for the phone and chat API - the user can select a standard app that shall be used for all actions regarding that API.

An app does not necessarily need to have a user interface. If its only purpose is to provide an API it can declare itself as "hidden". Those hidden apps are not displayed to the user. myApps starts them automatically in the background on incoming API messages.

Apps have access to the runtime environment (myApps client and ClientAPIs) using the start object that is passed to them during initialization.

The myApps launcher is a software that can be installed on the computer or smartphone of the user. It comes with an integrated browser for running the myApps client. Some additional services are included in the launcher that would not be available in regular browsers. Apps can find that services using Client APIs and then establish websocket connections to them. For example phone apps can use an application sharing service that is part of the launcher.

App Service

An App Service hosts the App, which is loaded with HTTP into the client. It also may provide backend services for the App. For the backend services the App may communicate with the App Service usually with Websocket, but other web communocation is possible also. For the authentication of this communication the password of the PBX object is used as a shared secret which must therefore configured on the App Service also.

If configured the PBX App Object establishes a AppWebsocket connection to the App Service. The password of the PBX App Object is used for authentication. This AppWebsocket connection is used for multiple purposes:

• The App Service announces properties of the respective App, like if it is a User App or a Device App, APIs which are provided by the App or if the App is hidden, which means it is not display in myApps but started in the background to provide an API.
• The App Service annonces services which are provided by the App Service itself. With this information other Apps can find this App Service using the Services API and establish a connection to the App Service.
• The App Service can use APIs provided by the PBX. Which API can be used by the App Service is configured in the App Object.

App

The App consists of code based on web technologies loaded from the web service. This can be anything which can be executed within a browser. It is loaded, starting with a HTML file which is configured within the App Object. The name of this HTML file, excluding any path is the name of the App. Based on this name licenses can be configured. For this reason the name should be unique, which is achieved by prefixing this name with the name of the company providing the App (e.g. innovaphone-...). Only the built-in Apps do not use the prefix.

When the App is loaded by the myApps client, the URL argument "name" is set to the PBX name of the App provider. For User Apps this is the name of the App Object. For Device Apps this is the hw-id of the device, prefixed with "dev:"

An App can establish several type of connections based on the authentication provided by the App object.

AppWebsocket to the App Service

The URL from which the App is loaded can be used to contruct the URL to which the AppWebsocket connection is established. The AppWebsocket libray uses the myApps client to Get a login from the PBX. The login includes a digest, which is a hash calculated over the different parts of the login and the password, so it can be verified by the App Service.

The login contains the property "app", which is the name of the initial HTML, the user name (sip), the domain, the display name of the user and more information, which maybe useful for the App Service

AppWebsocket to a PBX Device

For this to work the name of the App Object has to be configured as App on a device and a unique hw-id has to be set on the device. The user has to be given access to the device.

The App Service has to set the "deviceapp" propery in the AppInfoResult message for the PBX to provide such a login. Since this propery is available only after the PBX App Object has established a connection to the App Service, it is also advised to set the "Hidden" checkmark for such an App Object to avoid the generation of an invalid login.

For AppWebsocket connections to a PBX device the URL ws(s)://<PBX>/PBX0/APPS/websocket is used. To obtain a login for this connection the URL argument name has to be provided as app argument for the innovaphone.appwebsocket.Connection contructor. This connection allows to used PBX APIs (like PbxSignal) on behalf of the user.

App Platform

The innovaphone App Platform is a Linux based system, which may run on a innovaphone gateway or in a virtualized PC environment. An App Platform manager allows to install, start, stop and update innovaphone App Services.
For an App Service a abstract operating environment is provided, so that App Services can be implemented completely operating system independet. For developing an innovaphone App no Linux knowlege is needed.

Table of content

• App Platform Manager
• App Platform Webserver
• App Platform Database
• App Service
• App

The manager is responsible for managing the App services and instances (see below). There is the place where each service and instance can be stopped or started, Apps can be installed and removed, backups can be created and restored, the logs of the apps cen be shows, the app itself can be configured (Webserver path, database name, ...) and so on. The manager is the place to go also to access the innovaphone App Store to download and install new apps. The manager also creates a sandbox environment for each app for security reasons. So an app can only access and modify their own data.

The webserver is the entrance to the world for each app. An app will register itself to the webserver buy using an plugin system of the SDK. When registering, the app will use a path which can be accessed by a HTTP client. (The path will be defined in the App instance setting inside the Manager). There are three types of access the app can register: HTTP, Websocket and Passthrough. HTTP means, that under the path to register an client can access HTTP files. This files can be static files (statically linked to the app) or dynamic files, the app will build up on runtime. Registering as websocket means, that the app will receivie incomming websocket connections. And Passthrough gives the full responsibility of the access to the app. So the App needs to know what to to with the HTTP protocol, so it is recommended to use passthrough only, if you have to!

Even if the SDK supports two database systems (mySQL and PostgreSQL), PostgreSQL is the database used for the apps. So it is recommended to use it for your application, too. The database is not only used for application related data, also the configuration as well as files (only when created using the IDbFiles interface) are stored inside the database. Each App instance has it's own database and database connection, which will be shared between all of the instances session (see below). When creating a backup of an instance, the complete database for that instance will be saved and restored, if you're going to restore the backup. This makes creating a Backup of the apps data easy.

The App Service is an application running on the App Platform. It can be written in C++ or JavaScript. The SDK provides a set of interfaces for everything needed to created an app for the innovaphone App Platform. This includes database access, include the app into the webserver like a plugin, a HTTP client, sockets, file storage and so on.

It will be managed by the app manager, where an instance of that application will be set up. Other instances can be created, too. Because of that mechanism, each App Service must have a subclass of AppService. There, the AppService::CreateInstance() must be implemented to return a new instance SubClass of AppInstance, each time the CreateInstance() function will be called. And the AppInstance itself needs to create an instance of subclass of AppSession each time an incomming websocket request from a new UI session comes in. The procedure is as follows:

• The manager loads the app into the memory.
• The app creates an AppService, which will report to the manager, that the app had been loaded.
• The manager now sends a message to the app to create an instance of AppInstance.
• The created AppInstance will start to listen to incoming websocket request.
• If a websocket request for a new session comes in, the AppInstance will create an instance of an AppSession and assigns the websocket connection to that instance.

So finally, each app has only one AppService instance, which is the part of the app that communicates with the Manager. It also is responsible to create the AppInstance, the manager calls to create (depending how many app instances had been configured). The AppInstance itself is responsible for listening to incomming websocket requests and create a AppSession for each websocekt connection that comes from an Apps JavaScript UI. That AppSession is the core of the application, because it handles the user input, sent from the UI to the session, returns results, reads and writes from and to the database, etc.

The App Platform Manager can start multiple instances within an App Service, to support different configurations or even different customers. The different Instances run within the same process context.

The App is the component, which runs in the myApps client. It is written in Javascript. Of course an App typically needs an backend service to provide useful functionality, so the App is mostly just the User Interface.

To create the UI, the SDK provides some JavaScript files that handles all of the App Service / App communcation. This communication happens over the websocket connection, sending JSON messages back an forth. So the AppSession needs to implement the messages it will receive from and send to the UI, while the UI must handle the same messages, too. The SDK also provides some base and extended JavaScript UI controls, as well as everything needed to localize the app and use the themes of the innovaphone App Client. But the developer still needs knowledge of JavaScript and HTML to create the UI.

The files for that UI will be linked as static files into the binary of the App Service. Each request to one of those files will be handled automatically by the IWebserverPlugin, so the App Service itself do't need to handled that by itself. The good side effect of this is, that no one can change the files because there are not sotred seperatly on an hard disk.