Architectural overview

The innovaphone PBX system consists of there components

PBX The PBX authenticates users, registers Endpoints, provides UC signaling functions and grants access to Apps.
myApps Client The myApps client is loaded from the PBX and starts Apps, which are loaded from the PBX and also the App Platform. The myApps client provides the login for the user and some basic features like presence information. All other features are provided by Apps
App Service An App Service hosts the Apps which can be included in the myApps client using the PBX App Object. An App Service can be implemented with any technology and any platform, as long as it provides the needed functionality.
App The App is the code based on web technologies, executed within the myApps client. There different types of Apps:
PBX built-in
Apps which are hosted by the PBX itself. These are apps like phone, softphone or chat. The environment is built in a way that any of these built-in apps could be replaced by an app hosted by an external service
User Apps
Apps associated to a user.
Device Apps
Apps which are associated to a device configured at a user. This are apps relayted to Voip services. There are some predefined types of such apps: phone, softphone, rcc or chat.
App Platform The App Platform hosts App Services, which provide Apps to the myApps client. All backend serices for the Apps are implemented there.

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.

AppWebsocket The AppWebsocket protocol is the used for all communication between the myApps client, the App Platform the PBX and the Apps. It is based on Websocket connection and JSON coded messages. The AppWebsocket protocol itself defines the basic message structure and some basic features like authentication, version control and capability exchange. Other features are implemented individually by the instances which use this protocol.
myApps The protocol the myApps client uses to communicate with the PBX

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

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.

App Object

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

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.

Organization of apps

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.

Runtime environment for apps

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.

If all conditions are met, the PBX generates the response digest and provides an additional JSON structure with information about the user that is also protected by the digest. Both is transmitted back to the app that can forward it to the app service. As the app service also knows the app service password it can check the digest, associate the AppWebsocket with the user info and grant access.

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.

myApps launcher

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:

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

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.

App Platform Webserver

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!

App Platform Database

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.

App Service

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:

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.

App

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.