Courseware:IT Advanced - 04 Setting up the Application Platform

How to set up the AP manually

Prerequisites

You can run the App Platform on a hardware box (such as your IP411 or IP811) or you can run it as a virtual machine in environments such as VMware or Hyper-V (see  Concept Innovaphone Virtual Appliance for a list of supported environments).

Let's look at installing it on your IP411LEFT.

The only thing you need to do is install an SSD. We recommend that you use at least a 32GB SSD for a real installation (if you are only using the AP for training and testing, then 8GB will be sufficient). About 2GB will be used by the operating system, leaving 30GB of usable space for applications and their data. See  How to install an SSD in your IP411 for some hints on how to physically install the SSD.

Of course, if you do this course as an on-site course or you have already used your equipment in an IT Connect training, then you already have the SSD installed!

Installing the basic Application Platform

The Application Platform (AP) actually is an extremely light-weight Linux kernel with a number of Apps running on top of it. These Apps (technically spoken: Linux processes) are controlled (that is, started and stopped) by a component called Platform Manager. They communicate with other parties (for example, the end-users myApps clients) through web-socket connections handled by a specialized web server on the AP.

Please click the load button so moodle knows that you started this book: Setting_up_the_application_platform

You will see a note to the effect that the APPPLATFORM is missing. Something like:

07.03.2023 15:12:26.6341 0.000 0000.992 runtime script: APPPLATFORM: offline

You can safely ignore this for now!
However, if other devices show up as offline, please keep waiting (and refresh the Devices page from time to time).

Enabling AP support

The SSD of your box is normally used by the built-in web server to provide a WebDAV drive (which is available as http://172.31.31.2/DRIVE/CF0), so it is not available for the AP.

To use the SSD for the AP instead of for the WebDAV drive

• click  on Enable App Platform support in App-Platform / General (if not yet done and App Platform support is not enabled is shown).
  A reset required message appears and you need to reset the box to have the setting take effect. As soon as the box is online again, the App Platform/General menu will have much more sub-menus and also the App Platform/General form now has a number of properties which can be set

If you proceed, all data will be erased from the SSD!

 

The APs IP address

As the AP is a separate Linux system running on your box, it has its own network interface and hence needs a separate IP address. We recommend to use DHCP along with a proper reservation for your AP.

To set up the reservation on your DHCP server, you need to know your AP's MAC address. This is the MAC address of the box you are using (this would be 00-90-33-40-00-B3) with the first 00 replaced by 02. So in your case, it's 02-90-33-40-02-B3.

Fortunately, moodle has already prepared our little training DHCP server in IP4 / ETH1 / Leases with a reservation for the AP (called App Platform IP411LEFT). In real life, you would need the customers network administrator to provide it.

To turn on the DHCP client on the AP to be installed,  change Interface for DHCP to ETH0 in App-Platform / IP4.

We stated above that the AP has its own network interface. However, if you look at your box, there is no extra physical socket for this interface (there is only ETH0 and ETH1, which are the two network interfaces used by the standard firmware of your box). In fact, the AP's network interface is bridged internally. Therefore, you need to set the physical interface of the box you want the AP to use (usually ETH0) in to Proxy ARP mode.

You do this by ticking  the Proxy ARP check-mark for the physical ethernet interface you intend to use. In our case this is IP4 / ETH0.

Don't forget to reboot your box again (as indicated by  the reset required message)!

Downloading the AP

The next step to install the AP is to download the operating system, Platform Manager and Web Server. This is done directly from the box you want the Application Platform to run on.

As we will install the AP on the IP411LEFT, an SSD must be installed in it. Fortunately, in your training equipment in the on-site course, this already has been done. If you do the course on-line, make sure you have your own SSD installed (see  How to install an SSD in your IP411 for some hints).

The box will suggest in App-Platform / Installation an URL to download the image of the latest-greatest version of the system from (something like https://store.innovaphone.com/release/download/app-platform/XXXXXX/app-platform-armel.img). But how does it know this version?

AppStore structure

Let's look into how an App Store works a bit. The App Store is reached through an URL (for example,  store.innovaphone.com: release/download.htm which is the standard innovaphone release App Store). In this place (which is hardwired to the firmware of the box), you find a number of JSON files which describe what can be found in that store. One of these files is  store.innovaphone.com: release/download/linux.json. As the name suggests, it defines the Linux (a.k.a. AP) files available. When you download it, you'll find something like

{
"platforms": [{
"id": "arm",
"text": "App Platform ARM",
"file": "app-platform/110026/app-platform-armel.img",
"update": "app-platform/110026/update-armel.img",
"version": "110026"
}, {
"id": "arm64",
"text": "App Platform ARM64",
"file": "app-platform/110026/app-platform-arm64.img",
"update": "app-platform/110026/update-arm64.img",
"version": "110026"
}, {
"id": "x86_64",
"text": "App Platform x86_64",
"file": "",
"update": "app-platform/110026/update-x86_64.img",
"version": "110026"
}],
"devices": [{
"id": "IP0011",
"platforms": ["arm"]
}, {
"id": "IP3010",
"platforms": ["arm"]
}, {
"id": "IP3011",
"platforms": ["arm"]
}, {
"id": "IP311",
"platforms": ["arm"]
}, {
"id": "IP411",
"platforms": ["arm"]
}, {
"id": "IP511",
"platforms": ["arm"]
}, {
"id": "IP6010",
"platforms": ["arm"]
}, {
"id": "IP810",
"platforms": ["arm"]
}, {
"id": "IP811",
"platforms": ["arm"]
}, {
"id": "IP0013",
"platforms": ["arm64"]
}, {
"id": "IP6013",
"platforms": ["arm64"]
}]
}

This is to say that there are APs for the IP0011, IP3010, IP3011, IP311, IP411, IP6010, IP810, IP811, IP0013 and IP6013. Some of them use the arm platform, some the arm64 platform. The image for these platforms can be found at app-platform/110026/app-platform-armel.img (or app-platform-arm64.img). This is how the firmware determines the currently released version of the AP and where to download it.

There are similar .json files which describe the  firmware and  Apps currently available.

But don't be afraid if this looks all Greek to you For now it is enough to understand that the files available in an App Store are controlled by some .json files specifying what is available and on which path. So if you ever run into issues where you can't download a file from the app store (for example, if you have set up your own), this is the time to dig into this a bit deeper

Using your own AppStore

You sometimes will want to use a different AppStore (for example, when your device does not have access to store.innovaphone.com). You can do this by simply changing the URL property to where the AP Linux image is on your AppStore.

As we indeed want to use moodle's AppStore (so we always get the versions used in the training) we will exactly do this. So enter http://class.innovaphone.com/moodle2/webbuild/store.php/1-3/app-platform/0/app-platform-armel.img  as URL and click on the Install button.

The box will now download and install the AP. When it is done, you will see the message

Installation finished!

App Platform booted

You can now switch to the App Platform/General tab and see that

• Status is App Platform processor active
  This basically says that the AP support is enabled and the box's second CPU (which is used to run the AP) is started
  
• Boot status is App Platform booted
  This indicates that the Linux kernel has booted successfully and also has started the platform manager
  
• the Autostart App Platform check-mark is ticked
  So the AP will be started whenever the box is booted

The fields Kernel file (kernel-armv7te), Initrd file (empty) and Kernel command line (root=/dev/sda3) should never be changed unless you really know what you are doing.

For more details, see  App Platform/General and  Concept App Platform.

Logging in

The AP is now ready to accept a log-in to its Web user interface. It can be reached using its domain name apps-dvl-ckl2.training.innovaphone.com ( https://apps-dvl-ckl2.training.innovaphone.com) or IP address 172.31.31.12 ( https://172.31.31.12).

Trusting the Web user interface

When you click on either of the links above, you will probably see your browser complain that accessing it is a security risk. This is because the AP web server has a self-signed certificate installed, which is not trusted by the browser. We will see later how to replace it with a trustworthy certificate. For now, you  can convince your browser that you accept the risk and want to access the site anyway.

The browser message may look different, depending on the browser you use. Or it may not appear at all if you have added a security exception before for this name. In any case, your browser will  treat the connection as insecure.

The default password to log in to the AP via the Web UI (the so-called AP Manager password) is pwd.

The user interface you see is familiar to you from the IT Connect course. It is what you see when you opened the  AP Manager App in myApps.

Setting the AP passwords

There are  three passwords used on the AP:

• the AP Manager password
  This is required to log-in to the Web UI and also to link a PBX to the AP (we will discuss this later). The default is pwd, no user name required
• the Linux root user password
  This is required to perform restricted commands on the SSH command line. As before, you will never use it in normal operation. The user is root (and you cannot change it), the default password is iplinux
• the Linux admin user
  This is required to log-in to the AP using SSH. Note that you will never need this in normal operation (only if some emergency repair work needs to be done). Nevertheless, an attacker might (and probably will) try to exploit a weak password here. The default user is admin (cannot be changed), the default password is ipapps
  

Of course you don't want to leave those passwords as is. The Install would set them to the highly confidential, very secure password it randomly creates for your installation.

Fortunately, even though we don't use the Install here, the three passwords will be set to secure values later on by the Devices App. We will see how this works later.

For now, we only change the AP Manager password. You will find the place to do that when you open the Security tab in the  Platform Settings. Set the  AP Manager password to ip411 please !

Setting our private App Store

While we are at that: we also want to use moodle's App Store to install Apps later on. Using a private App Store is configured in the AP by  setting the App Store URL to the URL of the apps.json file on your App Store.

To use moodle's App Store, set http://class.innovaphone.com/moodle2/webbuild/store.php/1-3/apps.json as  App store URL.

Setting the AP's DNS name

The AP should know the DNS name you have created for it. Well, actually, in this training, we have done this for you. Anyway, the AP should know.

Right next to the Devices app URL 2, there is the field for the AP's DNS name which is called App Platform DNS name. Set it to the DNS name moodle has created for your AP, which is apps-dvl-ckl2.training.innovaphone.com.

Making your AP known to moodle

In order for moodle to be able to see your devices (to check the configuration you have done), these devices need to connect to moodle. This is actually the same mechanism that your devices use to connect to your Devices app!

For this to work, you need to tell your AP how to reach moodle. The URL for this is set in the Devices app URL 2 field in the Settings / General. Obviously you wouldn't do this in real life.

For now, you don't need to understand what exactly is going on here, just configure wss://training-apps.training.innovaphone.com/class.net/Trainee-Devices/sysclients in the Devices app URL 2 field and you're done (be sure to put it into Devices app URL 2, not Devices app URL).

As soon as you have done this correctly, the complaint about the missing APPPLATFORM on the Devices page will disappear.

Using the command line

As said before, you should never need to use this. However, for disaster recovery it is useful to know how you'd do it if you need to

Access to the command line is done using the SSH protocol. You will therefore need an SSH-client. We recommend to use WinSCP (which you anyway want to use as a WebDAV client) in conjunction with putty. Both are linked on our  Recommended Tools for this Course page.

If you have installed putty and WinSCP, this link should work for you: SSH client for your AP (ssh://172.31.31.12). Otherwise you can simply start your favorite SSH client.

We are not going to have a unix basics course here, but let's at least try to log in and do some basic commands:

•  connect your putty client to apps-dvl-ckl2.training.innovaphone.com or 172.31.31.12 and log in as admin with password ipapps (note: you cannot paste the password into the putty window, you must type it yourself). You will see what's called  the command prompt now. It shows who you are (admin@app-platform) and where you are (/mnt/sda2/home/admin)
  
  
• You  can change the place you are (a.k.a. the current directory) using the cd command. Try
  
  cd /etc/init.d
  
  and you will notice that the prompt changes to admin@app-platform|/etc/init.d>, reflecting the new working directory. So when a support guy someday says "go to /mnt/sda2/log/apps/manager" then you know how to do it
  
  
• to  list the content of a directory you can use the ls command. Just type
  
  ls
  
  and you will see a list of files in your current directory. Type
  
  ls -l
  
  to see the same list with more details for each file. Finally type
  
  ls /mnt/sda2/log
  
  to see the list of files in that directory
  
  
• df is another interesting command.  Type
  
  df
  
  to see the current disk usage split up by logical devices. The device you are probably interested in is /dev/sda2 by the way (this is where all the live data is written to)
  
  
• the rm command (shorthand for remove) removes files and should be used with some care obviously. Sometimes however it is useful to remove large log files. You could try
  
  rm /mnt/sda2/log/apps/manager/*.txt
  
  the rm command however will deny to do so:
  

  admin@app-platform|/mnt/sda2/log/apps/manager> rm /mnt/sda2/log/apps/manager/*.txt
  rm: can't stat '/mnt/sda2/log/apps/manager/*.txt': Permission denied
  

  
  
• as you have seen, the things you may do using the admin account are limited. To have unlimited access, you need to elevate yourself to being root.  Do this by typing
  
  su root
  
  as soon as you have provided the password for the root account (remember, this is iplinux by default) you will see that the prompt changed to root@app-platform|/etc/init.d>, reflecting the new user (you can actually omit root, in the command, so you just type su, as root is the default account then). As root is the Linux super-user, you now can do everything on your AP, good and bad!
  
  So you now could remove the log files as shown above. It'll work. Of course, you can also just trust me and do it only when you really need to
  
  
• but you can now try a variation of the df command which is called du. Change to the /mnt/sda2/log directory by typing
  
  cd /mnt/sda2/log
  
  here you find a number of sub-directories (try the ls command to see them!) where all kinds of log files are stored.  The command
  
  du -h
  
  will show you the  disk usage split up by directory
  
  
• to terminate the elevated command prompt,  type
  
  exit
  
  (see how the prompt changes back). The su command has stacked a new command prompt (unix'ish this is known as interactive shell) for root on top of your initial command prompt for admin. The exit command terminates the command prompt.
  
  You can also do just one elevated command by typing sudo -u root cmd. For example, the whoami command (which tells you who you are) will output admin when you call it now. However, if you call
  
  sudo -u root whoami
  
  it will output root (as it will elevate you to root, execute the whoami command and then fall back to admin's privileges again)
  
  
• to log out, you must terminate the outermost (that is, initial) command prompt.  Simply type
  
  exit
  
  and your SSH session will be closed. If you still see a prompt, you probably have stacked another shell (for example using the su command). Just type exit again until you are logged off
  

The list of Linux commands is quite long, even in our lightweight kernel. But as already mentioned, you should never need them anyway. However, if you do have to proceed as advised by the innovaphone support staff or as recommended in our wiki for disaster recovery, then it is good if you at least know how to log in and log out.

Adding Apps

We have set up the basic AP already. That wasn't too hard.

However, if you start myApps now (you can do that using the URL /PBX0/APPCLIENT/131375/appclient.htm?lang=en and use john.doe as Username and ip411 as Password) you  will see no Apps at all. Even if you click on Add some apps -> you will find that there are none.

Let's see how to fix that.

PBX Apps

As we already have seen in the IT Connect training, some Apps are actually hosted in the PBX instead of the AP (for example, the Settings App ). So these Apps should appear in John Doe's myApps client (as the PBX is already there and therefore their Apps should be there too) - but they don't. Why is that?

As you might recall from the IT Connect training, Apps are only available if they are assigned to a user in the Apps tab of the User object (or in the Apps tab of a Config Template PBX object that the user is inheriting). So far, we have  not assigned any App to John Doe.

Fix this by  ticking the pbxmanager check-mark in John Doe's Apps tab.

Note that the Settings App used to be called PBX Manager in previous versions. This is why its short name is still pbxmanager (and not, as you might expect, settings).

When you now open John Doe's myApps client (john.doe, ip411) you will find the Settings App App in the Add some apps -> area and can  add it to his home screen.

Please note that the exact number of PBX-hosted Apps available to you here depends on the firmware version used.

To make Apps available which are hosted on an AP, more needs to be done.

Updating the basic AP services

To be able to access Apps hosted on an Application Platform, we need an App Service on this AP to begin with. So far, our AP is just empty, no App Services and hence no Apps at all. So let us begin with installing an App Service.

App Services can be loaded from App Stores. By default, this would be store.innovaphone.com (which redirects you to the release store http://store.innovaphone.com/release/<some-number>/download.htm). However, as we already have seen, you can create your own store. Moodle has also done so and we are using this (https://class.innovaphone.com/moodle2/webbuild/store.php/1-0).

You can access it by clicking on the  App Store icon in the AP Manager UI (which we still need to access using its domain name (https://apps-dvl-ckl2.training.innovaphone.com) or IP address (https://172.31.31.12) as it is not yet available in our myApps client yet - we're working on it ).

The first thing it requires you to do is to accept the Terms for Using the innovaphone App Store without Charge. Note that you must scroll down to the end of the agreement and tick the I have read and acknowledge and agree to the Terms of Use of the innovaphone App Store check-mark to do so!

As soon as you have done so, you can unfold the Installed apps / innovaphone AG area and will observe that most of the App Services you have seen before are not (yet) present.  Only the App Platform Manager and the Webserver are there.

They have been installed as part of the AP (along with the light weight Linux kernel). If you  look at them however, you may see that they are outdated and can be updated. In this case, it would say An update is available instead of The latest version is installed.

How comes that there are updates to components which we installed just now (and we did use the latest-greatest to install the AP)? The answer is quite simple. The AP install package is a bundle of the Linux kernel, the Webserver and the Application Platform Manager. This is essential cause the Linux kernel needs something to start when it boots (which is the Webserver and Application Platform Manager). Of course, when bundling them with the Linux kernel, we use the then-current versions. Both are built and released frequently while the Linux kernel (and hence the AP install package) is updated only rarely.

To be sure your system is up-to-date if there are outdated components,

• select the  srTraining firmware in the version drop-down
• click on Select...
• click on  Select all
  
• and on  Update
• as soon as you  confirm the update, both the App Platform Manager and the Webserver will be updated to the proper version
  

The updated Webserver and App Platform Manager will be re-started right away, so don't be surprised that the manager's web UI is closed and you are requested to log-in again.

Adding an App Service instance

Now that we have updated the base system and seen how to open the App Store UI, we can easily add some App Services.

Let's start with the Devices App Service:

•  open the App Store again
• this time, unfold the  All apps / innovaphone AG list
• scroll down to the Devices App and click on it ( note that you can also type vice in to the search field on the upper right)
• in the right pane,  select the srTraining version
  
•  click on Install to install the App Service
• accept the license agreement and click on Install

When you close the App Store area, you will see that the Devices App Service was downloaded, installed and  started right away.

What a Service is

In the Application Platform, an App Service essentially is a piece of code that runs on the AP. However, to be usable, the code would need some data storage and some configuration settings in addition to the pure code.

An app service can therefore be thought of as a blueprint or template for a service. In order to actually use it, a concrete instance of this service must be created (known as an App Service instance).

So installing the Devices App Service gives us the option to create an instance which we then actually can use . This is done with the App Platform Manager of course. Only if this is done, we can actually use the services provided by an App Service!

So when you think "I am using Devices" then you should actually think (or at least keep in mind) "I am using my particular Devices instance".

To be able to use Devices, add an instance to it:

• click on the  Add button in the Instances part of the upper ribbon band to add an instance

Service instance properties

Let's see what properties an instance has:

• Name
  This is the technical name of the instance. It shows up in administrator interfaces only, so not in end-user interfaces. We recommend to use only short lowercase, letters and digits only names (no punctuation or white space).
  Although the Name does not need to be unique in an AP, the combination Domain/Name has to be! In other words, if you serve multiple PBXs with an App Service (say, Fax), you can create multiple instances (one per PBX) and call all of them fax but only if you use different domains
  
  
• Domain
  This has to be the System Name of the PBX the new instance is intended to be used with. Note that you can create multiple instances and each of these instances can be used in multiple, unrelated PBX systems (e.g. if a hoster provides PBX systems which share the same AP). But you cannot have multiple PBXs sharing the same instance
  
  
• Password
  The instance password. This is used as a shared secret between an instance and the PBX. Both sides need to share this password in order for the connection to work.
  
  Please note that the Password is a secret shared between an App service instance and a PBX whose users shall be able to use the instance. No two App instances should share the same password thus (especially, the same password should never be used for all of the instances). In fact, the instance password is not used anywhere else and thus there is actually no need to remember it once it is set. If it gets lost, you can simply set a new one on both ends (the instance and the PBX App object). This is why the Install creates different random passwords for each App service instance
  
  
• Webserver path
  
  The first part of the URLs which are used to access the services provided by this instance. It must be unique in this AP
  
  
• Database host
  The name or IP address of the host where the database for the App Service instance is to be created. In most cases (and certainly in this course), this is the local host where the App Platform runs and hence we can leave this field empty
  
  
• Database name
  The database name used by this instance. It must be unique in this AP
  
  
• Database user
  The name of the database user that is allowed to access the instance's database
  
  Note that Webserver path, Database name and Database user have reasonable default values which you should only change if you really know what you're doing!
  
  
• Database password
  The password used by the Database user. You will need this only in the rare case when you need to access the database using Linux database tools
  
  
• Exclude from overall backups
  You might recall this from your IT Connect training. Should be ticked if the instance shall not be backed up by the standard backup routine done by the Devices App. Usually not ticked except for the special Files App instance which is used to store your backups (to avoid recursive backups)
  

Let's  create a new instance of the Devices App service:

• the Name shall be devices
• The Domain shall be the System Name of your PBX (dvl-ckl2.net in your case)
• In real life, the Password shall be a secure one (like the Install uses the generic, secure password that it randomly chooses). Here in the training, we use ip411 (as we do all over the place) for both the Password and the Database password

The  new instance will be created. The only thing left to do here is to start it, so it can accept service requests. You do so by  selecting the instance and then hit the Start button.

Making Apps available to myApps users

Now that we have installed the App (more precisely, the App Service Instance), we need to make it available to users.

As discussed before, you need to tick the respective check-mark in the Apps tab of a user or template to give access to an App. However, when we  look now in to John Doe's user object, there is still no such check-mark.

This is because AP-hosted Apps first need to be made known to the PBX before they can be made available to users. This is done by  creating a PBX object of type App.

App object properties

The App object's properties on the General tab are pretty straight forward:

• Description
  is for some optional notes explaining the purpose of the App to end users. It will be  shown in a popup message when you hover over its icon in myApps. You can change that at any time later on without breaking anything
  
  
• Long Name
  is the name used to display the App to end-users. This of course is not optional and it needs to be unique throughout your system. You can change it later on without breaking anything
  
  
• Display Name
  Like for any other object, this is a name that will be used when displaying the object to users (e.g. this is what would be shown as the name of the App in the myApps client). It is used if set, otherwise, the Long Name is used. In many situations therefore, you will simply leave it empty. The difference is that the Display Name does not need to be unique
  
  
• Name
  however is used as an id for the App. Like the Long Name, it needs to be unique throughout your system. Choose it carefully as you can't change it later on easily
  
  Note that the Name does not need to match the  Name of the App service instance. However, it might be less confusing obviously, if it does.
  
  Also note that we - as usual - recommend to use A-Z, a-z, 0-9, ``.´´ (dot) and ``-´´ (dash) only in a Name. It must not start with a dot however. This rule-of-thumb is good for the Name or SIP property in all PBX objects whatsoever
  
  
• Password
  is used as a shared secret between a PBX and an App service instance. It has to  match the App service instance's password

The Hide from LDAP check-mark does not affect the functionality of the object. However, as for all objects which should not be called by everyone (either cause it doesn't make sense or not everybody should know about it), you should tick it for each App object. If so, the object is never shown in end-user user lists (neither in myApps nor on the phone).

Making Apps available to myApps users (contd.)

The properties in the App and Apps tab however are as follows:

• URL
  is the URL to reach the respective App. It is built according to the following template: https://<ap-fqdn>/<appsi-path>/<appsi-name>:
  
  
• ap-fqdn: the fully qualified domain name of your AP (e.g. apps-dvl-ckl2.training.innovaphone.com)
  
• appsi-path: the Webserver path as configured for the App service instance (dvl-ckl2.net/devices in our case, which was the default the AP manager suggested to create a unique path)
  
• appsi-name: the name for the App as shown in the Apps popup for an App Service (innovaphone-devices for this App, this is hard-coded by the App Service and cannot be changed)
  
  Sounds more complicated as it really is, as you can see all the  available App URLs at the end of the Edit popup in the AP manager
  
  
• Licenses
  defines the number of so-called Service licenses allowed for the App. Usually, if the App does not use Service licenses, you leave that empty. Service Licenses are used by App Services with custom licensing schemes

The rest of the properties in both the App and Apps tabs depend solely on the application you are configuring. In other words, you don't have a choice - you have to set it up the way the application requires.

To know what is required, you can consult the documentation. For innovaphone Apps, you will find the information in the wiki article describing the respective App service. For the Devices App for example, this would be  Concept App Service Devices. These articles will have a chapter called Apps with a section for each App which lists all required options. In our case section innovaphone-devices is relevant and  tells us that we need to tick the Websocket check-mark.

You can find a complete list of App object properties in the  App Objects Parameters chapter of  Concept Apps.

Making Apps available to myApps users (contd. II)

So let's do it now:

 To create the Devices App in your PBX

• open the list of PBX objects on your IP411LEFT
  
• create a new PBX object of type App
• type whatever you like as Description (or leave it empty)
• tick the Hide from LDAP check-mark
  
• use Devices as Long Name
• leave Display Name empty
  
• use devices as Name
• use ip411 as Password (as this is what we used as Password for the App instance before)

In the App tab

• for the URL property recall that
• the protocol is always HTTPS, so we use https:// as scheme
• the App is hosted on your App platform, so the host is apps-dvl-ckl2.training.innovaphone.com
• usually, the system's domain is used as the App service's unique path, so it is dvl-ckl2.net
• the name of the instance we have created was devices (note that we could have named it foo or bar instead)
• the technical name of the App is innovaphone-devices and this is hard coded in to the App service (so we cannot call it differently here)

So when we glue all these pieces together, we use https://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/devices/innovaphone-devices as the URL

• tick the Websocket check-mark

In the Apps tab

• leave all check-marks un-ticked

Congratulation! You created your first App object

Nevertheless, the Devices App is still not available to John Doe. We still need to assign the App to the user.

To do so, proceed as follows:

• open John Doe's user object
• switch to the Apps tab
• and  tick the devices check-mark
  
  Note that the name that appears in the list of assigned Apps here (devices) is exactly the Name property of the corresponding App object (the one we created just before). This is why you can't easily change the App object's Name - you would loose all assignments!

John Doe now has Devices in his ALL APPS list in myApps available and can put it on his home screen.

---

This is probably a good time to log in to the myApps client.

You can open the myApps client using the URL https://hq-dvl-ckl2.training.innovaphone.com/PBX0/APPCLIENT/appclient.htm?lang=en and login as john.doe using ip411 as password.

You may also want to put our first Application platform App (which is Devices) on John's home screen.

Multiple Apps in a single App service instance

As we have seen in the AP Manager's Apps tab for Devices, this App service provides  multiple Apps (innovaphone-devices, innovaphone-devices-api and csvapi).

Although the second interface (innovaphone-devices-api) is a programmatic interface that does not have a web UI (hence the name API), it must be made known to the PBX so that it can be used from the PBX (either by other App services or by users who use Apps that use the API).

So as you might have guessed, it is necessary to create an App object in the PBX for each of these Apps. Again, the details how to set the various properties of those App objects can be determined as before.

So, to create the App object for the innovaphone-devices-api

• create an App object in the PBX with Long Name set to DevicesApi
• tick the Hide from LDAP check-mark
  
• Name set to devices-api
  note that both Long Name and Name could be set differently, the App would work nevertheless
• Password set to ip411(this has to be like this exactly, as this is the Password we have set for the devices App service instance before)
• URL set to https://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/devices/innovaphone-devices-api
• the Websocket and Hidden check-marks ticked (we know this from the  Concept App Service Devices article in the wiki)
• as this API is required for some administrative Apps which our John Doe shall be able to use, we need to tick devices-api (that is, the Name of the new App) in John Doe's Apps tab

App services with multiple Apps

As we have seen, App services may provide multiple Apps (and hence multiple App URLs). When this is the case, make it a habit to always create App objects for all of the Apps that are listed in the respective wiki article for the App service (e.g. in  Concept App Service Devices) in your PBX. So for Devices for example, create App objects for innovaphone-devices-api as well as for innovaphone-device (just like we did right now).

The reason for this is, that proper function of all the Apps may rely on the existence of all those App objects. In other words: if the App object for one App is missing, another App may fail.

This is one of the most prominent reasons for the Users App to fail.

Adding your devices to Devices

While dealing with the Devices App, we can also do some basic steps to add all of your devices to the Devices app.

As you probably recall from the IT Connect training, all of the devices of an installation can (and actually should) register with a Devices App service instance.

This is simply done by configuring the websocket URL of your Devices instance (also known as sysclient URL) to all your devices. The URL is made up of

• the URL scheme wss:// (which as you probably know stands for web socket secure)
• the DNS name of your application platform (apps-dvl-ckl2.training.innovaphone.com in your case)
• the System name of your PBX (dvl-ckl2.net in your case)
• the instance name of your Devices instance (devices in your case)
• the fixed string sysclients
  

So you end up with wss://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/devices/sysclients as Devices-Registration URL (also known as sysclient URL).

Registering PBX and AP with Devices

To register your devices with your Devices instance, you need to configure the sysclient URL in two places:

• the PBX
  
  configure the sysclient URL from above (wss://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/devices/sysclients) for your PBX in General / Devices-Registration
  
  Please leave the TLS/SSL certificate checking check-mark un-ticked for now. We will discuss this later
  

• the Application Platform
  
  You may recall that the AP actually is a fully fledged second device within your IP411LEFT. So the Devices App URL property which we have set in the IP411LEFT before is only for the firmware part of your IP411LEFT. The AP part must be configured separately.
  
  To do so,

• open the AP manager UI
• edit the  App Platform Settings
  
• set the  Devices App URL property (use the same sysclient URL as above)
  

Of course we could add the Sysclient URL to each of our remaining devices (IP111 etc.) too. We will skip this for now because we will get to it later anyway.

Creating the domain in Devices for your installation

Devices is a service that can manage all the devices of your system.

However, it can also manage the devices of more than one system (imagine a hosted PBX provider who manages all of the devices of all its customers in a single Devices App). In case of multiple systems you could of course create one Devices instance for each system and register the devices with the respective instances using different sysclient URLs. But that would force you to use a separate App for each of your systems, which might be annoying.

Therefore, Devices itself supports the concept of multiple domains (which might be a little confusing in the beginning admittedly, as we now have domains in the App Platform Manager and also in the Devices App). You would then create a separate domain (within Devices) for each of your systems and use the same sysclient URL for all the devices.

But even if you only run a single system, you need to create this single domain inside Devices.

So the next step is to create an appropriate registration domain for your PBX system in Devices:

• within the Devices UI,  switch to the Domains tab and
• add a new domain by clicking on the + Add domain link
• use your  PBX's System name property as  Domain name (be sure that they do match exactly!). In your case, this is dvl-ckl2.net
  
• use ip411 as password (of course, in real-life, you would use a secure password)
  
  In real life, as noted above, you would want to use a secure (probably random) password for the domain. Also, you probably want to check the Deploy the domain password on all devices check-mark. This makes sure that any device registered to your Devices instance will have the password for the admin UI changed to the domain password. The reason for this is that device access should always take place using the Devices App, not directly through the Web UI (this is for emergency cases only). But in the training, we do not want this to happen, as all devices must retain their default password!
  
  
• make sure you uncheck the Deploy administrative device passwords check-mark before you save the form!
  
  You can leave all other properties as is.

Adding your devices to the Devices domain

When  switching to the Devices tab, you might observe that your domain devices, although listed, are shown with this strange  wrench symbol. This is to say that the device tries to register with Devices but is unknown. In other words: you need to approve each device that wishes to join the domain explicitly.

Don't be afraid: this is not going to be too much work. When devices use the provisioning (as you have seen in the IT Connect training), they will be approved to the domain automatically.

Adding the device to the domain can be done when you select such an unknown device. The Edit dialog which appears then allows you to specify the domain and an arbitrary name for the device.

Be sure not to join devices to the domain which you don't know! This might be an attempt to attack your system (as devices get access to sensitive information during their configuration by Devices).

To add your devices to the domain

• click on each device with the  wrench symbol on the Devices tab
• set a useful name (this is only for you to distinguish the devices later on).
  For the "firmware devices", a suitable name is already suggested (actually, moodle has configured these names in their General/Admin section before) and you can keep it if you like. For the AP (this is the one with the MAC address starting with 029033, remember?) you need to set one
  
• and  set the device's domain to the  System name of your PBX

Special App objects

There are a number of specialized App object types available in the PBX. All of them serve the same basic purpose: make an App known to the PBX and hence available to users. However, they are hand-crafted for specific Apps and their needs:

•  AP
  Defines the Settings App Plugin App provided by each AP (this App allows you to easily create App objects for the Apps provided by the App services installed on the AP, we'll look into this in a minute)
•  Push
  Defines the Push App which is used by a PBX to notify/wakeup Android and iOS apps (e.g. to signal an incoming call)
  
•  Voicemail
  Defines the Voicemail App (surprise, surprise)
  
•  Fax
  Defines the Fax App (again, surprise)
• more to come...

For now, it is sufficient to understand that these objects define Apps just like we did before for the Devices App which then need to be assigned to users (using their user object's Apps tab).

 

The "AP Manager" App

There is one specific App available on each AP even if no App service at all has been installed. This App provides access to the AP's admin web user interface (the one you see when you log in to the AP (e.g. https://apps.dvl-ckl2.net) using the manager password as we did so far).

 This App (usually called AP Manager) is provided by the AP's manager and does not need to be (neither can be) installed or configured on the AP. Still - as with all Apps - it must be made known to the PBX so that it then can be made available to users.

The URL for the App is https://<ap-fqdn>/manager/manager where ap-fqdn is the DNS name of the AP (apps-dvl-ckl2.training.innovaphone.com in our case).

The password for the AP Manager App object must match the admin password of the application platform (ip411 in our case). If you leave it empty, it defaults to the box's admin password.

To provide access to the AP manager's admin UI, you proceed as follows:

• create a new PBX object of type App with the following  properties on the General tab:
  
  
• Hide from LDAP: ticked
• Long Name: AP Manager
• Display Name: leave empty
• Name: apps
• Password: ip411
  
  
• ... on the  App tab:
  
  
• URL: https://apps-dvl-ckl2.training.innovaphone.com/manager/manager
  
  
• ... no changes on the Apps tab
  
  
• tick the  apps check-mark in John Doe's user object's Apps tab

John Doe now has the AP Manager App available in his ALL APPS area (from where you may want to add it to the home screen).

The App Service Settings Plugins

There is some support for Application Platforms and App Services available in the  Settings App.

The elements in the Settings App are dynamically created when corresponding items exist in the system. This is why they sometimes are also referred to as plugins. Let's see what they can do for us.

Adding APs

App services installed on an AP can provide  Settings App plugins (you have seen this in the IT Connect training already). They can help with adding the App objects to the PBX (which we have done manually before for the Devices App) and can also do some basic configuration of an App instance.

For these plugins (sometimes referred to as the colorful icons for obvious reason) to show up, we need to make the AP itself known to the PBX. This is done by creating a PBX object of type AP for each known Application Platform.

As we already discussed, an AP type object is in fact a specialized App object especially for Settings App plugins. Not surprisingly, it looks quite similar to the standard App objects.

To make our Application Platform known to the system, the following steps are required:

• create a new  AP type PBX object
• set  Description to This is Christoph's application platform
• tick the Hide from LDAP check-mark
• set Long Name to Christoph's AP
• set Name to ckls-ap
• set Password to the platform manager's Manager password (which we have set to ip411)
• set  URL to https://apps-dvl-ckl2.training.innovaphone.com/manager/manager-domain-api
• leave Account empty

When you now open the Settings App again, you will notice a  new (colorful ) icon called Christoph's AP devices. This name is built up by the  Long Name of the AP object for the Application platform (Christoph's AP) and the  Name of the respective App service instance (devices).

This icon is created by the App Platform Manager (the one that the URL https://apps-dvl-ckl2.training.innovaphone.com/manager/manager-domain-api we used above for creating the AP object points to). It is related to an App service instance, not an App service and the manager will create one such icon for each App service instance. In other words: If we were to add another instance to the Devices App service, another icon would appear.

The host-local path of the URL above (/manager/manager-domain-api) is actually fix, that is, it will be exactly this path on every AP. This is in contrast to other Apps, as the manager of course only exists once and is not domain-specific.

Dynamic AP password

In the previous chapter, we have used the AP's manager password (ip411 in our case) as password for the AP object. This is correct because both the AP object's and the AP manager's password are used as shared secret which must match so that the connection is authorized.

If you change the password in the AP object (Christoph's AP) into something random (say xyz123), you will see that the Settings App does not show the respective icons any more (you need to refresh the myApps client with F5 or right-click/reload to see the effect). This is of course expected behavior as the shared secrets do not match any more.

The surprising thing is that if you now actually delete the password in the AP object (not the password of the AP manager!), the Settings App plugins will be available again.

So how can that be?

If the password in an AP object is left empty, the PBX will use the device's admin password instead.

In the course, as we have discussed before, DO NOT SET THE Deploy administrative device passwords option in the domain configuration within the Devices App!

This makes sense as the Devices App service has an  option to Deploy the domain password on all devices (you have seen that in the IT Connect training already). If this option is turned on and the domain password is changed, then all connected devices get their admin password changed - including the AP! The AP's manager password is its admin password (you might recall that you use it to log in to the AP manager using this password when you access it through its IP address directly). So when this happens and a fixed password was configured in the AP object, you would loose access through the Settings App (as now the shared secret do not match). If you leave the AP password empty however, the new (changed) admin password will be used which again matches the AP manager's password.

So if you use the Deploy administrative device passwords option, we recommend to leave the AP object's password empty.

Btw: this only works if the device's User Name in General / Admin is  set to admin. So do not change this if you want to use this mechanism.

Two instances

As mentioned before, a single App Service can have more than one App Service instance. To see how that works, let's reproduce what the Install does with the Files App service.

It installs the Files App service and also two instances of it, Files and Backup Files.

Install the service

We already know how to install the Files App service:

• open the Platform Manager (now that we have the nice little  AP Manager icon, we can open it from myApps which is more elegant than to open it directly through its web interface at https://172.31.31.12)
• open the App Store
• unfold the All apps/innovaphone AG list
• scroll down to the Files App and select it
  
•  select version srTraining from the drop-down
  
•  click on Install
• accept the license terms if you are asked for it and install the Files App Service
•  leave the App Store area
  
• then add  an instance called files for domain dvl-ckl2.net, set both Password and Database password to ip411
• add  another instance called backup-files for domain dvl-ckl2.net, set both Password and Database password to ip411
• also, tick the Exclude from overall backups check-mark for the backup-files instance (this flag will stop Devices later on to backup this instance)
• start  both instances
  

We now have a new App service with two instances, so we'd expect 2 new (colorful) icons in the Settings App - and indeed,  here they are

Create the App objects in the PBX

We could create the App objects manually in the PBX as we did before. However, this time, we want to do it using the Settings App plugins which appeared.

It is important to understand that each of the two new icons relates to a specific instance of the Files App service. You can see which icon relates to which instance because the instance's name appears in the icon label. So to create the App objects for both Apps provided by the Files App service (which are the Files App and the Files Api) for both instances (which are files and backup-files) we need to use both icons.

Let's start with the files instance:

• start the Christoph's AP files plugin
• click  on Files Api to add the App object for the files api to the PBX
  
•  use FilesApi for the Files Api field (which will become the Long Name in the new PBX App object) and files-api for the SIP field (which will become the Name)

Eh voilà, the App object  has been created. Even the  URL and the check-marks have been set.

We can add the App object for the Files App itself the same way:

• click on Christoph's AP files plugin again
• click on + Add an App and select Files App
• use Files for the Files App field and files for the SIP field

The  App objects are easily created.

Finally:

• Now repeat the same procedure for  the backup-files instance. Use Backup FilesApi/backup-files-api and Backup Files/backup-files  as identifiers.
• Don't forget to assign our newly created apps to John Doe so he can use it in his myApps.

Creating App objects for Apps

As we said before, the Settings App plugins can do basic configurations for an App service instance and help with creation of App objects for the Apps provided by the App service.

The Devices's App plugin however does not feature any special configuration dialog. So the only thing you see when you  open the plugin is the + Add app function (as well as the two App objects we have already created manually). The green checkers next to the App objects indicate that the plugin seems to like what we have created

Creating the App objects for the App service's Apps is easier via the Settings App plugins than in the advanced UI where we have done it just before. Of course, the plugin itself knows how the URL needs to look like and which check-marks have to be set. So the only  properties you need to set (and hence can set or modify) are Name and SIP (which are equivalent to Long Name and Name in the advanced UI, which is a bit confusing).

How the plugins manage the instance password

You might have observed that you cannot actually set or modify the password though. So how does the plugin know the password to be able to set it correctly in the App object?

As described in  Concept Apps, the plugins use a little trick here. If they need to set the password and don't know it, they simply create a new random password and set it in both the App object and the App service instance. While this has the beauty that both passwords match thereafter (which is a requirement for the App object to work as you already know), it has the drawback that it silently changes the instance's Password. This is a bit confusing and sometimes even breaks working configurations. Keep this in mind or simply create the App object manually using the advanced UI.

Generally, when using the Settings App plugins for the App services, make sure that

• the App service instances are used from a single PBX only (that is, you have a single master PBX)
• or, you have a master / slave setup where all PBXs using the App service instance are fully replicated (we will look into what this means in more detail later, for now: all slaves share the same PBX objects)

If this is not the case, do not use the plugins to create or modify the App objects in the PBX (but don't be scared, you will usually meet the criteria listed above).

Using the app installer

In fact, there is also an easier way to install an App Service along with a single instance.

You may have noticed that when the new Settings App plugin called Christoph's AP devices appeared earlier, another plugin called Christoph's AP App installer  also appeared. The app installer is an additional App provided by the AP Manager a priori. That is, it exists even though it was never explicitly installed (just because the AP Manager exists). It greatly simplifies the task of adding App Services.

Let's see how that works by installing the Reporting App Service:

• open the Christoph's AP App installer plugin from within the Settings App
  
  What you see should look somewhat familiar to you as it resembles the App Store part of the AP manager
  
  
• unfold All apps / innovaphone AG
  
  
• select the Reporting App service
  
  
•  select srTraining from the Select a version... drop-down
  
  
• click on Install
  
  
• accept the terms of use if you are asked to do so
  
  

Just after a few seconds, the app will be  shown as installed and you now have the option to update or to uninstall it.

When you now refresh the entire Settings App (by closing it and starting it again), you will see that a new colored icon called Christoph's AP reporting  appears.

What it does

To see what the app installer actually does, we can have a look at the AP manager again:

• open the AP manager from your myApps client
• in the Installed apps list, a new entry Reporting is shown
• select it and you will see that it has a single  instance called reporting which is already started

The app installer has

• installed the App service
• created an instance with sensible default values for all properties
• started both the App service and the instance

This is why the Christoph's AP reporting  plugin appeared in the Settings App .

What is left to do

While this greatly simplifies the installation of an App service, there are still a few steps to do. We can see that when we open the new Settings App plugin: the plugin shows  no App objects at all.

So we quickly need to complete the setup as follows:

• click on + Add App
• create the App objects for the Call List API, the Call List app and the Reporting App using the following Name and SIP properties:

  App	Name	SIP
  Call List API	CallListAPI	calllist-api
  Call List app	Call List	calllist
  Reporting App	Reporting	reporting

  
  You will notice that these are also the default values suggested by the plugin.

• Now that we have the proper App objects, we can  assign the new Apps to John Doe using the Apps tab in his User object
• and ultimately find them  in his ALL APPS area (where we might want to assign them to the home page)
  

You might ask yourself "why don't we assign the app to the Config User template so that all users have it? Or at least to Config Admin?". Well yes, you could do that of course. However, the Reporting App provides access to very sensitive data. As such, it is usually not assigned to many users, not even to all administrators in many cases.

Did you notice that we have assigned 3 Apps to John Doe in his User object but only 2 show up in his ALL APPS? This is because one of the Apps that we have created has the  Hidden flag set. This is to say that it has no user interface (as it is an API only).

 

Instance configuration

Some Settings App plugins can do even more: they can set some basic configuration parameters in the App service instance.

To see how this works, open the Settings App

• open the  Christoph's AP reporting Settings App plugin
  
• open the  Configuration dialog
  

This is an example for a general configuration dialog which an App instance can provide (you may view it as an administration settings dialog in contrast to user specific configuration dialog which would appear in a burger-menu in the Apps themselves).

In this case here, you can - amongst other things - modify the deletion strategy for the CDRs processed and stored in the Reporting App service instance.

And by the way, believe me, you don't want to set it to disabled. CDRs will quickly fill your database and one day, your AP's disk will be full and it will not boot any more and  you're in trouble.

Instance properties are stored in the App instance database on the AP itself, not in the PBX. This is why they are also saved upon a backup and restored with an instance restore.