Courseware:IT Advanced - 05 Setting up the Apps

This books looks at the setup of various standard Apps in more detail

More PBX vs. instance interaction

There is much more interaction with App services than what we have discussed so far.

For example, there are URLs served by App service instances which are not for Apps, but for other HTTP clients. An example would be the URL used to send CDRs to, which is provided by the Reporting App service instance. Also, access to such URLs is usually protected and proper credentials are required therefore.

We'll look at that by discussing more advanced configuration settings related to the various App services in the next chapters.

Reports

The Reporting App service provides Apps for end-users (the personal Call List) as well as for administrators (Reporting for overall call reporting). Also, an API (the callistapi) provides services for other Apps so they can display personal call information (for example, the phone app uses this).

For this to work, the App service must receive call data information (so called Call Detail Records, CDR) from the PBX.

CDRs are sent using HTTP GET or HTTP POST requests to the App service instance.

 reporting system overview

The steps to make Reporting work are

• download the Reporting App service from the App store and create a new instance
  
• create the App objects in the PBX and configure the appropriate URLs and flags so it is known how to access them
  
• assign the Apps to a user to make them available in myApps
  
  we have already done these steps before
  
  
• configure CDR delivery from the PBX to the Reporting App service
  
• setup users so that they have the appropriate licenses for their calls to appear in Reporting

The server side

On the server side, we obviously need to tell the App service instance the credentials it shall accept for incoming CDRs. These credentials then have to be configured the same on all PBXs delivering CDRs to the service.

You can also leave both properties empty (as the Install does). However, this would allow anyone to send CDRs to the service, which you might not want.

This is a property of the App service instance and as such configured in the  Configuration dialog of the Settings App plugin Christoph's AP reporting:

In the the Account for the CDR authorization section configure the following properties:

• set User name to cdr
• set Password to ip411 (of course, in real life, etc. etc. )
  

You an leave everything else as is for now.

The client side

To be able to send CDR data to the Reporting App service instance, we need to configure the URL for the GET request and also the credentials for the HTTP authentication in all devices sending CDRs (that is, in all PBXs).

To explore this a bit, let's look at our master PBX again.

CDRs are sent by the PBX to the application that processes them if the Generate CDRs check-mark is ticked in PBX/General. Btw, for historical reasons, the Gateway level is also able to send CDR data, albeit with different format. However, we don't care as this is not used anymore.

The check-mark needs to be set therefore in

• PBX / Config / General (our  master PBX)

But how does the PBX know where to send the CDR data to?

The target and method must be configured in Gateway/CDR0 (again of course in both the master and standby PBX).

To use our reports App service instance for call lists, configure Gateway / CDR0 as follows:

• select HTTPS as Log Server Type
• use apps-dvl-ckl2.training.innovaphone.com as Address as this is the DNS name of your AP
  
• leave Port empty (which will use the https default port 443)
• select External (GET) as Method
• use /dvl-ckl2.net/reporting/cdr as Path
  Note that the prefix /dvl-ckl2.net/reporting is what has been  configured as Webserver path in your Reporting instance while /cdr is a fixed part you always use to send CDRs to the Reporting service instance
  
• configure User like you did on the server side before, which is cdr. Note that this user name will only be used to authenticate the delivery of CDRs to the Reporting App service instance
  
• configure the Password like you did on the server side, which is ip411. Note that this password will again only be used to authenticate the delivery of CDRs to the Reporting App service instance
  

We now have  configured the client side of the CDR delivery on the master PBX.

An interesting case is the construction of the Path value. It probably was no surprise to you that it starts with the PBX's domain name followed by the string /reporting (/dvl-ckl2.net/reporting). This is what we have  configured as Webserver path for our app service instance before, so all URLs provided by this instance will share this prefix. However, the trailing /cdr is sort of classified information as it is not listed as App URL in the list of URLs in the instances edit dialog. It arguably should be listed there.

Now you at least know why you are attending this course

Trying it out

To try it out, we can start the Call List App:

•  start the calllist App from the ALL APPS area
  
  
• the App starts up empty.
  But when you
• lift the handset on the analog phone (which we have registered for John Doe before)
• call 14
• and hang up again,

you'll see  new entries appearing

 

Well done!

Licensing

Just to be on the safe side,

•  start Reporting to see if this works too
• Leave all fields as is in the selection criteria, so that we see todays calls for all users and hit  Show results
  

Oops! What is that? Why are the new entries we have seen in the call list before not shown here?

Call reports (as opposed for listing own calls only) is done only for users which have a reporting license assigned. Assigning the reporting App to users doesn't do the trick as it controls access to the reports only. To have calls included in the reports, the users initiating or receiving the calls must have a Reporting license assigned.

So

•  assign the Reporting license to John Doe
• call 14 again with the analog phone
  
• refresh the list of calls by  clicking on Show results again

When the Reporting license is assigned to a user, all subsequent calls will be listed in the Reporting App . Previous calls will still not show up.

---

For historical reasons, there is some confusion regarding the name of the App. It should have been called Reporting from the very beginning but it started out as Reports and therefore, you find both names.

Users

The Users App service manages various data related to users in the PBX. It provides the Users App which allows end-users to find other PBX users. Also, the UsersAdmin App allows administrators to add/remove and edit PBX users. The Profile App however allows end-users to edit their own properties. Finally it provides an Api (users-apis) to other Apps which allow them to retrieve avatar pictures for users (this is used by the phone App for example).

 users system overview

As you already know, the PBX itself does also manage user data. For this reason, the Users App service needs to synchronize it's own user data with the User and Executive objects in the PBX. This is done in tandem by a function in the PBX known as TableUsers and a replicator in the App service.

Whereas the Apps are available only once a user runs myApps, the replication obviously needs to take place even if no user at all is using myApps. Therefore, a direct websocket connection between the PBX and the Users App service is established. This happens because the  WebSocket check-mark is ticked in the profile App object in the PBX.

As you might remember, the myApps settings have a link to the users profile (Edit profile in MY ACCOUNT available through the burger menu). Therefore, myApps needs to know which profile App is to be used).

The steps to make Users work are

• download the Users App service from the App store and create a new instance
• create the App objects in the PBX and configure the appropriate URLs and flags so it is known how to access them
  
• assign the Apps to a user to make them available in myApps
• configure the Profile App as the app to be linked from myApps burger menu
• configure user replication
  

The App service

To install the Users App service and create a new instance, we can use the App installer:

• open the Settings App in myApps
• start the Christoph's AP app installer
• install the Users App service using version srTraining
  
  You now have  an instance called usersapp running and hence a  new Christoph's AP usersapp plugin in the Settings App (be sure to re-start the App to see it)
  

The App objects

To try it out, we can start the Users App. To do so, we need to assign access to the App to John Doe's list of Apps in his user record. And to be able to do that - you guessed it - we need to create the appropriate App objects in the PBX.

Next step is to create the App objects in the PBX

Just like before with the Reporting App , the way to do this is:

• use the + Add app function of the Christoph's AP usersapp Settings App plugin to  add the App objects for
• the Users App (Name Users, SIP users)
  
• the Users admin App (Name Users Admin, SIP users-admin)
• the Profile App (Name Profile, SIP profile)
• and the Users APIs API to the PBX (Name UsersApi, SIP users-apis)


• now we can  assign the users, profile and users-admin App as well as the users-apis to John Doe in his user record in the PBX
• then  start the Users Admin App from the ALL APPS area

As you will notice, the App starts up empty - no users. This is because the replication is not yet properly configured. We'll do that in the next step.

Replication

To setup proper replication between our Users App instance and the PBX, let's first see if the replicator connection is setup properly.

WebSocket

If the  WebSocket flag is set in an App object, the PBX strips the last component of the URL property (leaving https://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/users from https://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/users/innovaphone-profile for example) and uses this as target for a WebSocket connection.

This connection is then authenticated based on the shared secret (the Password in the App instance on the AP and in the PBX App object). Once the connection is established, messages can be exchanged between the PBX and the App service and vice versa. In case of the Users App service, this is used to exchange user object update messages. The access rights which are granted to the App service for this connection are ticked in the Grant access to APIs section.

As soon as the WebSocket connection between the PBX and the App service instance is established, the state shown next to the URL property field  changes to connected. If it stays in the connecting state, there is probably something wrong with the credentials or the URL. Also, the App service instance may not be running.

We actually have nothing to do so far, as the Settings App has perfectly created all the required objects.

Replicator properties

However, to get the replicator up and running, some additional configuration needs to be done in the Users Admin App's burger-menu settings. When you open them right now, you'll see it  complaining.

To fix that, you need to enter

• the PBX Password (we had set that to ip411 in the PBX)
• and the PBX name (which is hq)

Now everyone is  happy

You may ask yourself why we need to specify the PBX name. This is because in a master/slave system (we'll look at that in a later topic), all of the PBXs will connect to the Users App service instance. However, you will want to make sure that replication takes place from/to the master PBX. So you need to tell Users the name of the master.

Self-service device provisioning

While you are at that page, we can quickly look at the very bottom of the burger-menu page. You'll see a check-mark called Allow users to edit and provision phones. If this is ticked, end-users will be allowed to provision their own phones (you have seen that in your IT Connect training).

Whether you want your users to be able to do this themselves or not is at your own discretion. If the flag is turned on, users will see some  options to add phones in their profile. If it is turned off, the assigned phones will just be  listed with no option to add one.

For the course, make sure you  ticked the option.

The second check-mark in the PERMISSIONS section (Allow to edit the name and the display name on the app profile) allows end users to change their own Name and Display name properties. While this won't break configurations, it might still be undesirable: for example, users can then set their Display name to whatever they want, including the name of other users.

All other settings on this page (password policy, SMTP, default settings for new users, ...) should be pretty self explanatory and/or they have already been discussed in the IT Connect training.

To set these values to what the Install would set,

• set the password policy's Minimum length to 8 and
  
• Minimum number of categories to 1
  
  
• set the default settings - new user's Node to root (so far, there is no other node than root),
• PBX name to the name of the master PBX (which is hq),
• Default password (import) to password,
• Home screen apps to users,
• Template to Config User (which does not yet exist in our PBX but we'll create it later)

For the course, you can leave the SMTP settings as is, as we don't use them. In real life, you would enter the customers SMTP data just as you would do when running the Install.

The Home screen apps property defines the Apps the user will find on the myApps home screen initially. It consists of a comma separated list of SIP values (or, in the advanced UI, the Name property) of the apps which shall appear.

pbxmanager,apps,calllist,reporting,users-admin,devices

will put the Settings, AP Manager, Call List, Reporting, Users Admin and Devices App to the home screen.

Grouping is done using a colon (``:´´) followed by the group title:

:,pbxmanager,apps,calllist,reporting,users-admin,:group-a,devices

will therefore create two groups (this first without a name and the second called group-a).

The easiest way to create a proper value for the Home screen apps property is to configure a reference user's myApps home screen as desired and then copy  the Home Screen Apps property from the User tab of this user in the advanced UI.

The profile App

You might recall that myApps allows access to the  user's own profile editor through its burger-menu.

However, when you look at myApps' burger-menu now, there is  no Edit profile link. This is because we need to configure the profile App that should be linked-to in PBX / Config / myApps. So far, this field  is empty, so no profile App is linked.

This can easily be fixed using the Users Settings App plugin (Christoph's AP usersapp):

• when you click on Users configuration / Change configuration a drop-down will appear (admittedly, it doesn't look like one initially, but just trust me and click on it, you'll see a drop-down list).
  Select  your Christoph-IP411LEFT here (as it is the master PBX). It is the only choice at that moment
  
  
• you will see a dialog there which allows you to set the Profile app. Even more, it allows you to control some additional behavior in your PBX:
  
  
• can users register themselves?
• can users reset their password?
• can users delete their account?
  
  Just click on profile (this is the only profile editing app we have anyway). You can  select whatever you like for the other choices, but letting users register and delete themselves is a rather rare setting (unless you run a web-based public PBX)
  
  
• once you have saved the new settings, you will see the settings in PBX / Config / myApps  updated and the Edit profile link appears (you might have to re-open the profile though for the change to take effect)

All these settings are done in the individual PBX settings. Therefore, they must be done on each PBX in the system (if you have multiple, that is)!

Contacts

Contacts can be used to dial out from a shared contact database (directory) and to provide caller id data for incoming calls.

You already have seen how to upload directory data and how to use it in the Contacts App during your IT Connect training. In this chapter however, we will look at how non-App clients get access to this data.

To play around with Contacts, we have to create a new App service instance.

Even though we run the risk to bore you, here is how to do this:

• open the Settings App in myApps
• start the Christoph's AP app installer
• install the Contacts App service using version srTraining
  
  You now have  an instance called contacts running and hence a  new Christoph's AP contacts plugin in the Settings App (be sure to re-start the manager to see it)

As before, you need to add the App objects using the Settings App plugin:

• use the Christoph's AP contacts Settings App plugin to add the App objects for
  
  
• Contacts (Name Contacts, SIP contacts)
• Contacts admin (Name Contacts Admin, SIP contacts-admin)
• Contacts API (name ContactsApi, SIP contacts-api)
  
  
• assign contacts, contacts-admin and contacts-api to John Doe
  
  
• start Contacts Admin
  
  
•  upload the  Sample contacts file (UTF8) in to the new instance
  
  
• type fen in to the search window
  you should see the  entry for Renée-François Fenêtre if everything went well.

 

Name/number resolution overview

Let's have a bit of theory and look at how name/number resolution works.

So what is name/number resolution anyway?

There are two kinds of resolution:

• name resolution maps a name to a number (e.g. by looking up the name in a directory so the user can use it to dial out). As this is usually what a user expects to happen when he does an outgoing call, a.k.a. forward lookup
• number resolution does the opposite thing: it resolves a number to a name (e.g. to display the caller-id for an incoming call), a.k.a. reverse lookup

Directory Interfaces

Both kinds of resolution work with a number of possible directories.

There are basically 3 types of directory-access:

• local
  The hard-phones feature a local directory list which can be edited by the end-user (on the phone)
• LDAP
  both the phone and the PBX can use LDAP to look in to a directory (which might be a Contacts App service instance, an external LDAP server or the PBX internal LDAP server)
• search-API provider
  myApps (and hence all the Apps running inside myApps) can use the com.innovaphone.search API. There are several providers for this API:
• the Users App service instances. Provides data for PBX User and Executive objects
• the Contacts App service instances. Provides data for the entries stored in their respective database
• the PBX LDAP objects. Provide proxy access to entries stored in a remote LDAP server. myApps can not talk LDAP directly. These objects are the way to provide access to LDAP entries for myApps.
• your local Outlook contacts. myApps for Windows will search your local Outlook contacts for a matching name.
  

The PBX system will use these interface to resolve names to numbers (or SIP URIs, which is functionally equivalent) e.g. to place calls or to resolve numbers to names to display the caller identity of the remote peer of a call.

Directories

In practice, the following directory services exist:

• the  PBX User database
  these are the PBX objects that do not have the Hide from LDAP property set. They are made available both by the PBX's internal LDAP server (via LDAP obviously) and the Users App service instance as a com.innovaphone.search API provider to Apps running in myApps (however, limited to User and Executive objects only in the latter case)
• the directory entries uploaded to the  Contacts App service instances
  made available by the Contacts App service instances both via LDAP and as a com.innovaphone.search API provider
• contact entries stored in the user's own  Outlook installation (e.g. an Exchange contacts folder)
  made available by the myApps launcher as a com.innovaphone.search API provider
• directory entries stored in the user's own  hard-phone
  accessed locally and hence only available on a single phone
• directory entries stored in an LDAP compatible  3rd party directory server such as Estos' MetaDir, C4B's XPhone Virtual Directory or any OpenLDAP server
  made available both by the 3rd party's server (via LDAP obviously) and (optionally) by an LDAP type PBX object
  

This adds up to a  pretty complex scenario. But don't be afraid, we'll look in to how this works in the next sections.

Number resolution in action

Let's see what happens for an incoming call.

• An external call comes in
  It is received by the PBX's signaling core. The signaling core now uses it's  configured Reverse Lookup URL and  performs a reverse lookup request (as to map the incoming number to a caller-id).
  The Reverse Lookup URL usually points towards a Contacts App service instance. However, it does not need to. If you decide to use an external directory system instead, you can do so (see  Concept Number Resolution and LDAP for some samples how to address other services)
  
  
• meanwhile,  the call is forwarded to both the hard-phone (using H.323) and to myApps (more precisely, to the phone App running in myApps, using the EpSignal WebSocket API)
  
  
• when a search result is received from Contacts, the PBX creates a name-identification from it (this could look like Christoph Künkel innovaphone AG for example) and sends it to the hard-phone and to the phone App (again using H.323 and EpSignal, respectively) which will display it to the user
  
  
• the phone App does an attempt to even do better and sends the name-id (Christoph Künkel innovaphone AG) to the search API available in myApps. myApps will  forward this request to all search API providers available:
  
  
• Contacts
• Users
• any PBX LDAP object available
• Outlook contacts

Each of them may or may not yield a result, however, the Contacts App service certainly will, as the name-id was constructed from its search result by the PBX in the first place. The difference now is, that the full directory information is available to the phone App which will use it to display a  nice vCard

Note that the hard-phone does not do any such attempt, as it relies on the PBX to do the reverse number lookup and also has no ability to display extended vCard information.
This behavior is controlled by the  Disable Phonenumber Look-up check-mark in the user's Phone configuration. For legacy installations (pre-V13), this is turned off (so that phone number lookup is done) because the PBX did not do the reverse lookup in these systems

Also note that reverse lookup is only performed for calls to user objects. For example, if you call a waiting queue with two agents, number resolution will be done for each agent separately (as there might be different results) but it will not be done for the waiting queue. So when looking at a call report for the waiting queue, no resolved names will be seen.

For an outgoing call, the scheme is pretty similar:

• the call is sent from the endpoint (either hard-phone or phone App) to the PBX
• the PBX does the reverse lookup and sends back a name-id
• myApps attempts to display a vCard and sends a search request to the search API therefore

In fact, there are other apps in an innovaphone system that offer a com.innovaphone.search (i.e. a search API) interface. However, the phone app only searches for results of the type contact:

{ "mt": "Search", "type": "contact", "search": "Christoph Künkel innovaphone AG"}}

Only those providers that deliver such result types are of interest here. The search provider of the Conference app, for example, will not return any such results. Other result types are described in the  SDK API description.

Number normalisation

Let's have a slightly deeper look at the reverse lookup done by the PBX.

The number to resolve will usually be a dial-able number in the so-called unknown format (could be e.g. 007031730090 or 000497031730090). That is, it is not a full number in a format usually stored in a directory (such as eg. +49 (7031) 73009 0).

In order to find an entry in a directory regardless of the format that has been dialed, the PBX does an attempt to normalize the number. This is done using  the Prefix for Intl/Ntl/Subscriber/Area-Code/Country-Code properties in PBX / Config.

• if the number matches the Intl prefix (usually 000), the prefix is removed
  
  000497031730090 -> 497031730090
  
  
• otherwise, if the number matches the Ntl prefix (usually 00), the prefix is removed and the Country-Code (49 in our example) is prepended
  
  007031730090 -> 7031730090 -> 497031730090
  
  
• the resulting number (497031730090) is made available to the Reverse Lookup URL as variable %n
• in the default lookup URL
  
  ldap://apps-dvl-ckl2.training.innovaphone.com/dc=entries?givenname,sn,company?sub?(metaSearchNumber=+%n)?bindname=apps.dvl-ckl2.net\contacts
  
  you see the part metaSearchNumber=+%n. %n is replaced by 497031730090 as shown above. The URL also has a + (plus sign) in front of the %n, so the number actually looked up in the directory is
  
  +497031730090
  
  which is actually the full international format usually maintained in a directory (although it might be displayed with some decoration as in +49 (70317) 3009-0)

So keep in mind that your directories should always contain all numbers in a full international format! Otherwise, reverse number resolution might not work.

Name resolution in action

When a user types in a name in myApps (or even on the hard-phone) the system must map the name to a dialable number in order to place the call.

Here is how this works in myApps:

• the user types in a search string in the phone App
  
• the phone App will send the string to myApp's com.innovaphone.search API
• myApps will  forward the search request to all com.innovaphone.search providers, e.g.
  
  
• Outlook
• Users
• Contacts
• any available PBX object of type LDAP
  
  
• incoming results will be displayed to the user
• the user selects an entry (and the number within this entry, there might be multiple)
  
• the phone App  creates a call using the EpSignal API and sends the selected number with it
• the PBX  forwards the call to the users local phone and the remote peer (using either the appropriate trunk or a local PBX object)

Again, its not an  easy picture

Number normalization

Unfortunately, numbers found in directories need to be modified too before they can be used to dial (just as you already have seen for the reverse lookup), as they appear in different formats (Users for example will yield pure extensions such as 123, whereas Contacts will deliver international numbers like +49703173009123 and user-maintained directories such as Outlook often contain dialable numbers such as 0703173009123).

Assuming the following prefix configuration:

Intl = 000

Ntl = 00

Subscriber = 0 (note that the Subscriber prefix is also often known as trunk access prefix)

the phone App can handle a variety of number formats:

type	input	dialed
international numbers	+49 (7031) 73009-123	00049703173009123
international numbers with full dialing prefixes	00049703173009123	00049703173009123
international numbers	0049703173009123	00049703173009123
national numbers	0703173009123	00703173009123
subscriber numbers	73009123	073009123
local extensions	123	123

Local extensions are distinguished from subscriber numbers by their length (less than 7 digits).

Name resolution in action (cntd.)

Name resolution also takes place when dialing directly from a phone.

In this case,

• when the user types in a search string the phone would consult 3 different databases, depending on the  registered user's Phone/Directory configuration:
  
  
• the Local phone-book, which is stored in the phone's flash memory and can be maintained by the user itself directly on the phone
• the PBX phone-book, which lists all the PBX objects
• the External LDAP Server phone-book, which usually is configured to look in to the Contacts database
  

Except for the Local phone-book, they are  accessed using LDAP

• the call is then  sent to the PBX with H.323 and forwarded both to the remote peer (using SIP) and the phone App running in myApps (using EpSignal)

Note that also for outgoing calls, the PBX will do a reverse number lookup for the called party as explained in Number resolution in action above. Again, the result is sent back both to the hard-phone and the phone App (this is the reason why you ultimately see the nice vCard of the called party again in myApps).

The full picture

Whenever you configure or debug name/number resolution issues, the following full picture may be useful:

lookup-full-scenario

Multiple directory sources

Most installations will want to use their own phone-books. Looking at the scenarios for forward- and reverse-lookup it should be clear that

• forward lookup on the phone allows access to :
  
• one external phone-book (the External LDAP Server). Access to it is controlled by the User PBX object's Phone configuration
• and the phone-book stored directly on the phone
  
  
• forward lookup in the phone App (that is, in myApps) can handle many phone-books:
  
• zero or more Contacts App service instances
  
• as well as zero or more external LDAP servers connected through PBX LDAP objects.
  Access to those phone-books is controlled by the respective User PBX object's Apps tab
• local Outlook contact folders for myApps running on Windows
  
  
• reverse lookup (being done centrally in the PBX) can only use a single phone-book, connected through LDAP (controlled by the PBX's Reverse Lookup URL property). Individual results are made available to all PBX users (that is, directory lookup is done in a user-specific way, so that different users can yield different results, for example if they have different personal address books (see  Reverse Number Lookup for Personal Directories for details))
  

The most common setups are:

•  use Contacts
• a single Contacts App service instance is used for forward- and reverse-lookup
• no PBX LDAP objects
  
  
•  use 3rd party directory
  
• Contacts is not used
• Instead, a 3rd party LDAP server is used in the PBX's Reverse Lookup URL property and in a single PBX LDAP object
  

Configure Forward Lookup

Now that we're gone through all this weird theory, let's get practical and configure the whole thing. After all: if you are able to configure it correctly and it works, there is no need to understand the details

To configure forward lookup in myApps (and hence the phone App), you need to

• enable  all the com.innovaphone.search API providers in John Doe's PBX User object's Apps tab. These are
  
  
• contacts-api
  
• users-api

Note that there is no App check-mark for the Outlook search provider. This is available to myApps simply due to the fact that it is installed on the PC where myApps runs.

Also, if a user may search a directory (as allowed by enabling the search providers above) it obviously makes sense to give access to their respective UI too. So we also tick the

• contacts and
• users

check-marks.

To enable forward lookup on the hard-phone, we need to configure the directories to be used by the phone. This is done in the user's Phone config tab in the PBX.

At first we need to activate the  Store Phone config checkmark in John Doe's user object because otherwise changes of the phone config won’t be transmitted to the phone.

To enable the local phone-book on the phone

• tick  the Local/Enable check-mark

To configure access to the PBX's objects (such as e.g. Users), you need to configure the LDAP access to your PBX in  the PBX section:

• tick the Enable and Use TLS check-marks
  
  
• leave the Server property empty. In this case, the server address found in the phone's registration configuration is used and this is most likely what you want
  
  
• leave the Port property empty. In this case, the LDAP (389) or LDAPS (636) default port is used, depending on your Use TLS setting. Again, this is probably what you want
  
  
• set the Username to a name in the domain\user format. The domain is your PBX's DNS (hq-dvl-ckl2.training.innovaphone.com in your case). We suggest to use ldap-guest as user. So in your case, you end up with hq-dvl-ckl2.training.innovaphone.com\ldap-guest
  
  
• set the Password to a secure password (yeah, you guessed it, in this course, you set it to ip411)
  
  
• leave the Gatekeeper Identifier property empty
  
  
• Leave the Name Attribute property as-is. You could set it to Display Name instead of Long Name. However, Display Names are not unique throughout the system, so you could get ambiguous results, which you probably don't want
  

Again, note that this configuration won't work for now, as we first need to also set up the user and the password in the PBX's LDAP server settings.

To configure access to the entries found in Contacts, you need to set  the External LDAP Server properties:

• tick the Enable and Use TLS check-marks
  
• set the Server property to the DNS name of your App platform (apps-dvl-ckl2.training.innovaphone.com in your case)
  
  
• leave the Port property empty. In this case, the LDAP (389) or LDAPS (636) default port is used, depending on your Use TLS setting. This is probably what you want
  
  
• set the Username to a name in the domain\user format. domain is the DNS name of your App platform (dvl-ckl2.training.innovaphone.com in your case). user is the name of your Contacts App service (contacts). So in your case, you end up with apps-dvl-ckl2.training.innovaphone.com\contacts
  
  
• set the Password to a secure password (again, how boring, we use ip411 in the course)
  
  
• set Search Base to dc=entries (just don't ask this is a hard-wired value imposed by the Contacts app service)
  
  
• leave Mode as is (that is, basic). Again, this is a hard-wired value imposed by the Contacts app service
  
  
• leave Object Filter empty
  
  
• leave Sort Results un-ticked
  

• leave Name Attributes empty since it is a legacy option and not required to configure any longer.
  
  
• leave Number Attributes empty (remember: we do not use reverse lookup on the phone)
  
  
• set H323 ID Attribute to sip
  (this is the name of the attribute in the Contacts database which allows to be called like a phone number)
  
  
• set the Detail Attributes to title,company,street,postalCode,city,country,email,url
  This is something you may modify to your taste. It defines the way the phone would construct the display search result entry
  
  
• set the Meta Name Attribute to metaSearchText
  
  
• set the Meta Number Attribute to metaSearchNumber

These two Meta attributes are an interesting case. They are meant for servers which can perform intelligent wildcard searches on their own, just based on a simple search string given as value for the meta attribute. This often leads to better search performance but requires a server which is capable of doing it. Contacts is . If you use an LDAP server that can't do it, leave the Meta- attributes empty. In this case, the LDAP client will construct its own search expression based on the Name Attributes and Number Attributes.

• leave the Hold Server Connection property as is
  

The remaining fields are for the dialing location. This resembles the Prefix for Intl/Ntl/Subscriber/Area-Code/Country-Code property in PBX/Config/General, however, the format is slightly different.

To set the  Dialing Location for the phones

• set Country Code to the country code of your trunk line, 49 in your case
  
  
• set Area Code to the area code of your trunk line
  
  If there are no area codes in your country, this field must be left empty. So for you, set it to
  
  621
  
  
• set National Prefix to the prefix you need to dial to access a national number but without the trunk access prefix (this is the difference to the setting in PBX/Config/General).
  
  So for you, set it to
  
  0
  
  
• set International Prefix to the prefix you need to dial to access a international number but without the trunk access prefix (this is the difference to the setting in PBX/Config/General).
  
  00
  
  
• set External Line to the trunk-access prefix of your trunk. In your case, this is 0
  
  
• leave Subscriber Numbers as-is (empty)
  
  
• set Max Internal Number Length to 7 (so it is consistent with the hard-coded limit implemented in the phone App)

... PBX local LDAP server

PBX local LDAP server

We have configured the client side to the PBX's LDAP server above. However, you also need to configure this LDAP server side in Services / LDAP / Server.

To configure the  PBX's LDAP server properties so that phones can access PBX object information

• add a new User called hq-dvl-ckl2.training.innovaphone.com\ldap-guest with Password ip411
  This needs to be exactly the credentials you have configured in the  PBX settings of the PBX User record in the last section!
  
  
• make sure you tick the Apply Hide check-mark for this new user
  
  
• optionally delete the existing ldap-guest user. This legacy setting is there by default but is not suitable for remote access to the PBX LDAP (that is, access through a reverse proxy)
  

... Contacts LDAP server

Contacts LDAP server

The last missing part is the setup of the Contacts App service instance's LDAP server. The only thing to be done here is to set the LDAP access password which we have used before both in the PBX's reverse lookup URL and in the phone's external directory setting.

To see the configuration of your Contacts App service instance

• open the Settings App in myApps
• click on the Christoph's AP contacts plugin
• click on Change configuration

You can leave all settings as-is except for the User (LDAP) and Password (LDAP) and Enable LDAP.

Set the User (LDAP) to apps-dvl-ckl2.training.innovaphone.com\contacts

The password is currently not set (you can check this by ticking the Display check-mark next to the input field.

To complete the Contacts LDAP server configuration

• type a secure password in to the Password (LDAP) field
  In this course, as usual, use ip411
  
• tick the Enable LDAP check-mark to start the LDAP server

The Install also does this configuration for you (although slightly differently). If you used the Install and you need to know the secure password created by the Install, you can always run the plugin and tick the Display check-mark to see the password.

The remaining fields User (HTTP Post) and Password (HTTP Post) can be left as is. They are used if you want to upload contact data from a third party client (see  Concept App Service Contacts for details).

... number/name resolution in the PBX

Reverse lookup

To configure reverse lookup in the PBX

• set the  Reverse Lookup URL in PBX / Config / General to
  
  ldaps:// DNS-name-of-your-AP /dc=entries?givenname,sn,company?sub?(metaSearchNumber=+%n)?bindname= ldap user configured in your Contacts instance
  
  
  The ldap user would be what you have configured as User (LDAP) in the Christoph's AP contacts Settings App plugin.
  
  In your case, this is
  
  ldaps://apps-dvl-ckl2.training.innovaphone.com/dc=entries?givenname,sn,company?sub?(metaSearchNumber=+%n)?bindname=apps-dvl-ckl2.training.innovaphone.com\contacts
  
  
• set the Password to what is configured as User (LDAP) in the Christoph's AP contacts Settings App plugin. In your case (as usual) ip411
  
  
• make sure  Prefix for Intl/Ntl/Subscriber are set to
  
  
• Intl: prefix to access international numbers, including the trunk-access-code. In your case
  
  000
  
  
• Ntl: prefix to access national numbers, including the trunk-access-code.
  
  In your case
  
  00
  
  
• Subscriber: prefix to access local numbers (also known as trunk-access-code).
  In your case
  
  0
  
  
• make sure Area-Code/Country-Code/Subscriber are set as follows:
  
  
  • Area-Code: the area code of your trunk line
    
    In countries which do not have area codes (that is, users must always dial full national or international numbers) this field must be left empty!
    
    621
    
    
• Country-Code: the country code of your trunk line.
  
  In your case
  
  49
  
  
• leave Subscriber as is (empty)
  
  
• set Max. length internal number to 7 (so it is consistent with the hard-coded limit implemented in the phone App)

 

You could also set the Subscriber field to the trunk line's subscriber number (3428231 in our case). However, in many cases this is not necessary (as it mainly inhibits loopback calls to local extensions through the trunk line when a colleague's extension is dialed from a directory) and the Install therefore also does not do it.

... Trying it

Trying it

To verify your phone's LDAP configuration

• use your IP111 where John Doe is registered
• do a long press on the 5 (j)
  you should see a  search result entry for John Doe (14). This is a result from the PBX LDAP server
  
• clear the j using the backspace key on the upper right
  
• and press 7 three times (yielding an r)
  you should see a  search result entry for Renée-Francois. This is a result from the Contacts App service instance LDAP server

To check the search-api provider from within myApps, we first need to make the phone App available to John Doe (so we can try the search function within):

• open John Doe's PBX User record
• switch to the Apps tab
• tick the phone App
  
  now, several Apps representing John Doe's devices are available in the ALL APPS area (POTS phone, Hot Desking and IP111)
  
  
• start one of your phone apps
  
• search for both j and f
  
  Notice that the search for f works  as expected but the search for j does not. John Doe is found by the telephone's LDAP client because visibility through LDAP access is a yes/no configuration in the PBX object (controlled by the Hide from LDAP check-mark which is currently off for John Doe). Visibility through search-api access (which myApps (or more precisely: the phone App) is using) however is controlled by a much more sophisticated privacy mechanism which we need to configure before it works

To configure privacy for John Doe

• edit John Doe's profile by starting the Profile App available in the ALL APPS area
• switch to the Privacy tab
• click on + Filter for domain to add a rule for all users in your PBX system
• put dvl-ckl2.net (your PBX System Name) in to the input field next to the @
• tick the Visible check-mark
  
  This is to say that John Doe is visible to all users in this specific domain. If you like, you can tick all the other privacy options (except for Group, you must not tick this as this is not a privacy option but changes the interpretation of what you have typed in the input field from being a domain name to being a group name)
  
  
• if you now go back to the phone App and re-run the search for j, it should work
  

Note that searches are done with head matches. For example, when you search for an e, you will find neither John Doe nor Renée-François Fenêtre lthough both names include the letter e. Only names that start with the search expression are delivered. However, matches are done on each individual word of the name, so that both searches for j and d will yield John Doe and searches for both r and f will yield Renée-François Fenêtre.

Also, searches for multiple words (such as e.g. j d, resulting in a match for John Doe) will match if for all words there is a matching word in the result name. The sequence of the words does not matter, so

d j will also yield John Doe.

Finally, a number of attributes are searched for, not only the name. The exact nature of these attributes depends on the App that holds the information. For the Contacts App (and hence the ContactsApi search provider) also attributes like company, zip code, city or country are searched.

User friendly naming of search API providers

We have seen in the last chapter that search results provided by the search API are sorted by search provider (such as ContactsApi) and the  name of the search provider is shown on top. However, the string ContactsApi might not be appropriate for end users.

Fortunately, you can specify an arbitrary name that suits you well by  editing the Display Name property in the ContactsApi PBX object, e.g. Corporate directory.

This will then be  shown as group heading.

Finding search API providers

You would obviously want to do something similar for all search API providers. This raises the question of how to know which of these providers are installed in the system.

Keep in mind that there is no definite list of search providers in myApps. This is because such providers can be installed (usually as part of a new App), even as part of 3rd party (or home-grown) Apps. So the question is which of the installed Apps are actually search providers.

To answer this question, we can use the API monitor App. This is actually part of the PBX and as such does not need to be installed from the App store.

To make it available to John Doe, we need to  tick the apimonitor check-mark in John Doe's PBX user record. We can then start it from the ALL APPS section in myApps.

The app will display a lot of confusing stuff, the meaning of which is not really immediately obvious. Fortunately, we just have to search for the text com.innovaphone.search. What we are interested in is contained entirely within the curly brackets directly after this text.

And it looks something like this:

"com.innovaphone.search": {

"@client": {

"title": "myApps",
"url": "http://0090334000b3.local/PBX0/APPCLIENT/1420315/appclient.htm",
"info": {},
"model": {

"relevance": 500

},
"restart": 0

},
"devices-api": {

"title": "DevicesApi",
"url": "http://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/devices/innovaphone-devices-api.htm",
"info": {},
"model": {}

},
"users-apis": {

"title": "UsersApi",
"url": "http://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/usersapp/innovaphone-usersapis.htm",
"info": {},
"model": {}

},
"contacts-api": {

"title": "Corporate directory",
"url": "http://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/contacts/innovaphone-contacts-searchapi.htm",
"info": {},
"model": {}

}

},

The bold parts in the above text snippet are the values of the names of the installed search API providers and these are exactly the value of the Name properties of the PBX objects whose Display Name property we could change to get nice labels in the search results.

The Search App

Wouldn't it be nice to have a unified place to search for whatever can be found in your system?

Yes indeed and it exists: the Search App. Just like the API Monitor this is actually part of the PBX and as such does not need to be installed from the App store.

As before, we simply need to tick the search check-mark in John Doe's user record to make it available to him.

However, this App is of general use, so in a real-life installation you would probably choose to assign it to the Config User template.

The Search App uses the search API to search for whatever can be found in your system using the search string. This is quite similar to what the phone App does. However, the phone App would let the search API know that it is interested in results of type contact only, whereas the Search App allows any result types.

Give it a try and search for 009033. You will see that you now get  results from 2 search API providers you haven't seen before: myApps and DevicesApi.

myApps is the myApps client itself. In this case, it will deliver 2 of your Apps (which are related to an innovaphone device whose MAC address begins with 009033).

DevicesApi however is the name of the search API provider the Devices App brings to the table. It searches for devices and domains in its device database.

Currently, the following result types are defined and can be handled by innovaphone Apps: contact, app, message, device. However, third party apps may define their own.

You meanwhile know how to give a user friendly name to the DevicesApi search API provider. However, you can't change the name of the myApps provider as there is no corresponding PBX object for it.

The Events App

We have already seen what the Events App does in the IT Connect training. Now we want to have a look at how all this is configured in detail.

App service instance

To install the Events App service and their instance,

•  use Christoph's AP app installer
• restart the Settings App
• use the Christoph's AP events plugin to create all the App objects in the PBX:
• Events with Name set to Events and SIP to events
  
• Alarms with Name set to Alarms and SIP to alarms
• Logging with Name set to Logging and SIP to logging
• Events API with Name set to Events API and SIP to events-api

Now you have a service that would receive Event, Alarm and Log messages from your devices using an HTTP POST request. However, so far you don't have any device that would send such messages.

For devices to be able to send such requests, you need to set appropriate credentials in the Christoph's AP events plugin:

• click on Events configuration / Change authentication account
• set the Username to something sensible, e.g. events
• set the Password to a secure value, which is ip411 in the course as you know
  

To be able to use the Apps and APIs provided by the Events App service, we need to assign them to John Doe.

Tick the alarms, events, events-api and logging  check-marks in the Apps tab of John Doe's PBX user object.

Client side

To have your devices send such messages, you need to configure the respective client in all of your devices. This is what the Devices app service does by virtue of its Device configuration jobs of type Alarm server.

To configure the target URL for posting the alarms, events and logs, you need to know the relative path of the respective services on your AP. These are made up as follows:

http:// dns-or-ip-of-your-AP / System Name of your PBX (i.e. domain) / name of your Events instance /

followed by one of the following fixed strings:

• innovaphone-alarms for events and alarms
• innovaphone-logging for logs

The DNS name of your AP is apps-dvl-ckl2.training.innovaphone.com and the name of your Events instance is events.

To configure your IP411LEFT to send logs, alarms and events to your new Events service instance

• go to Services / Logging on your IP411LEFT
• set some of the properties in both the Log Server and Alarm and Event Forward Server area as follows:
  
• select HTTPS for Type
  
• set Address to apps-dvl-ckl2.training.innovaphone.com
  
• leave Port empty (which defaults to 443 for Type HTTPS)
• select External (POST) for Method
• set User to what you have defined as Username above in the plugin, which is events
• set Password to what you have defined as Password above in the plugin, which is ip411
• set the Path to /dvl-ckl2.net/events/innovaphone-logging for the Log Server and
  
• set the Path to /dvl-ckl2.net/events/innovaphone-alarms for the Alarm and Event Forward Server

In most cases, you will send log messages to the Events services too. However, some installations are using third-party logging services to handle log messages. In this case, you would want to set it differently (and un-tick the  check-mark next to the Logging URL in the Alarm server device configuration so that Devices leaves these settings untouched).

 

Trying it

To verify your configuration

• open the Maintenance / Diagnostics / Logging tab on your IP411LEFT
• un-tick all check-marks which may be set so far
• tick the PBX Calls check-mark
• open the Logging App from the ALL APPS area in myApps
• lift the receiver of John Doe's IP111
• hang up again

You should see  two log messages now in the Logging App (or may be three, if you have a left-over search expression in the IP111 before lifting the receiver).

The Messages App

The Messages App service offers a variety of apps for written communication: Chat, Premium Chat, and Connect. Chat (and also Premium Chat, which is not a separate App but a way of running it when the Messages service is available and licensed) have been discussed in the IT Connect training.

The new App that comes with the Messages App service hence is Connect. It provides an interactive platform with micro blogging aspects.

Apart from the fact that Connect is a pretty awesome app anyway, it also has some special configuration features that are of interest to us here.

Let's see what there is to discover here.

 

App service instance

To install the Messages App service and its instance,

• use Christoph's AP app installer
  
• restart the Settings App
• use the Christoph's AP messages plugin to add all the App objects in the PBX:
• Api with Name set to MessagesAPI and SIP to messages-api
• Connect with Name set to Connect and SIP to connect
  

For the time being, you can ignore the App available for public access option.

To be able to use the App and API provided by the Messages App service, we need to assign them to John Doe.

Tick the connect, connect~admin, connect~moderator and messages-api  check-marks in the Apps tab of John Doe's PBX user object.

But hey, wait a minute!
We only created two App objects (with SIP set to connect and messages-api), but now we set 4 check-marks in John Doe's user object?

This introduces a concept we haven't seen before, known as modes.

A mode is an operating mode of an app that usually involves certain access rights. They are defined as a comma-separated list of words in the  Modes field within the Apps tab of the respective App object.

In our case, the Modes field in the Connect App object is set to admin,moderator,admin-service. This results in the appearance of the Apps connect, connect~admin, connect~moderator and connect~admin-service. When a user uses the App described by the App object, the App would know all the modes the user has an assignment for and can treat the user accordingly.

As still there is only a single App object, only a single App will appear in the user's ALL APPS area, regardless of how many modes have been assigned to the user.

You may ask yourself why we did not assign connect~admin-service to John Doe. Well, modes are not necessarily meant to be assigned to users. Some are meant to be assigned to Apps so that they can incorporate some of the Connect functionality. See the chapter on connect admin-service mode in  Connect's concept article.

Finally, you might ask why the messages-api is not called the connect-api. This is for historical reasons: the Connect app started out as Messages and has since been renamed. The name of the app service (Messages) and the API object (MessagesAPI/messages-api) are reminders of this.

A 10 minutes Connect crash course

A nice overview of what Connect does can be found in  www.innovaphone.com: en/software/all-apps/connect-app.html.

However, we want to do a little hands-on of course. So let's play a bit with your new Connect App.

To do so, we need to create a second User PBX object in PBX / Objects with the following properties:

• Long Name Lisa Svensson
• Name lisa.svensson
• Password ip411
• Assigned Apps connect, messages-api, profile, search and users-apis
  
• active/static group membership in group group-for-connect
• visibility setting for @dvl-ckl2.net with Visible ticked
  
  Also,
• add John Doe as an active/static member to the group-for-connect group
• start Connect as John Doe
  
  finally
  
• open http://hq-dvl-ckl2.training.innovaphone.com/PBX0/APPCLIENT/appclient.htm?lang=en in a new browser and log in as lisa.svensson with password ip411
  
  this needs to be a different browser, not just a new browser window or tab. For example, if you use Firefox currently, you could use a Chrome window. If you don't have another browser on your laptop, you can use the native myApps client (you can get it from the  Recommended Tools for this Course page)
  
  
• start Connect as Lisa Svensson

You may want to put both Connect Apps side-by-side so you can see what is happening on both ends in real time.

---

If you also want some nice avatar images for Lisa and John, you can use these: , and upload them using the Profile App.

These pictures are courtesy of  www.freepik.com.

 

Handling posts

As you would expect from a microblogging tool, Connect allows you to post and reply to messages, creating what is called a thread.

In John Doe's Connect,

• type a new message in to the Start a new discussion field, say something like what I always wanted to say
  
  This creates a post which you can reply to
  
  
• click on the message, then on the  reply-symbol and type do you hear me
  
  Here you have your first thread

As you can see, Lisa Svensson has John's message in the  right pane of her Connect App. This area where the threads are shown is known as the stream.

Lisa can now like any of John's messages by clicking on the thumbs-up symbol.

What happens then is that the message being liked is shown in the  left pane of John's Connect App, notifying him that something worth noting happened. This area where the threads are shown is known as the feed. Also, a little counter (known as a badge-count) appears at the top of the Connect icon. So John would notice the news even if he is not using Connect at the same time.

John can now confirm that he has taken note of the information by clicking on the tick symbol. This removes the message from his feed. The feed is your tool for managing the information that comes in and that you need to pay attention to.

Following

Lisa's feed is still empty, so she may not see John's message.

If John wants to make sure that Lisa notice his message soon,

• he can edit one of his messages
• and add the text @lisa.svensson to it

The message will appear in Lisa's feed and a badge-count will be shown.

What if Lisa wants to be notified every time John posts?

In this case, Lisa can follow John. On Lisa's Connect App

• go to More / USERS
• click on John Doe
• click on the bell-symbol next to John Doe's avatar picture
• click More / FOLLOWING. You will see that John Doe is in the list of people Lisa is following
  
  
• switch to John Doe's Connect App and post a new message with content no at

The message will  appear in Lisa's feed and the badge-count will be set to 2.

Mentioning groups

You can also mention groups by using @@group instead of @user.

Groups in Connect are defined by the groups in the PBX. All active members of a group are will be considered by Connect when addressing with @@group.

You can try this with @@group-for-connect

Zones

Up until now, we have been posting messages in an "everybody sees everything" fashion. This may be appropriate in some contexts, but not everywhere.

You can structure the communication space Connect provides by using so-called zones.

Let's say you have the issue that people tend to discuss things off-topic in a thread. You could then create a new zone for it.

In John's Connect App

• click on the burger menu (upper right)
  
  This is where user settings for ordinary users can be found. However, users with admin rights (those that have connect~admin assigned in their Apps tab) can access administrative functions here
  
  
• then select Zones
  you will see a list of existing zones with the entries Connect and John Doe
  
  
• click on Add a zone to create a new zone
• set Display name to Coffee gossip
• set Name to coffee-gossip
• and finally set App id to connect

You have now created a  new zone where people can indulge in coffee gossip (actually a sub-zone to the default zone which is known as Connect).

Well, almost.

When a new zone is created, it is configured with default access rights so that the user who created the zone is the only user with access rights (he or she is configured as the administrator). To grant rights to other users, you must add users or groups to the zone's list of access rights.

To do so, proceed as follows:

• click on the new zone entry (the zone editor pops up)
• click the Add a group button (a list of group names shows up in the list field labeled Group)
• optionally type the prefix of a group name (e.g. group-for-connect) to filter the group list
• click on the group you want to add (group-for-connect in our case) to  add the group to the new zone (no need to tick the Administrator check-mark now)

Instead of explicitly adding users and groups to a zone, you can also set no groups and users at all. If the access rights list is empty, all users have access.

More on zones

You may have noticed that there are zones named Lisa Svennson and John Doe. These are personal zones that exist by themselves and cannot be removed or changed. Each user only has access to his or her own personal zone.

Also, you may ask if it is possible to use something else than connect as App id when creating a new zone. Well, yes and no. Primary zones (those where Name is empty) only exist for Apps. This is why there is a zone called Connect. They are created automatically for all Apps that have the Connect App in their Apps tab (and can not be created manually by leaving the Name property empty).

To create a zone for the Profile App

• open the App object for Profile in the PBX
• switch to the Apps tab
• tick the connect check-mark

When you re-start the Connect app and open this list of zones, you will see a zone called Profile.

Additional zones (not sub-zones) are meant for other Apps who want to post content in Connect. Such an App is Projects for example.

Note that such Apps would set the connect check-mark in their own App object by virtue of their Settings plug-in if they support posting messages to Connect. As such, you will in reality likely never have to do it yourself as we did for the Profile App above.

For speed, the Connect App caches a number of things that usually don't change frequently. As a result, you may sometimes need to restart the application to see changes.

Home

As there are now several zones, it can happen that certain users are not interested in some zones. This can make the list of all zones unwieldy.

To fix this, there is an area called HOME where you can add zones. You can also set one of these zones as the main page. This is the zone whose messages are displayed in the stream right after opening the Connect app.

Let's set the gossip zone as Lisa's main page:

• in Lisa's Connect App, click on MORE
• select Zones
• click on the Coffee gossip zone (if it doesn't show up in the list, restart Connect as dicussed in the previous chapter)
• the zone now shows up above the list with 3 dots to the right
• click on the 3 dots
• select Pin to home
• Connect switches to the HOME area, the zone is now in your list
  
• click on Coffee gossip in the list
• click on the 3 dots
• select Set as main page
  
  The icon next to the zone's name changes to a house-symbol.
  

Hashtags

The Connect App supports hashtags as you would expect.

Post a message (in zone Connect) in a new discussion (a.k.a thread) with content This is #devops's #party-of-the-week: 10 GB of spam went to #"/dev/null"!

When you now click on the message header (on the word Connect), you will see all hashtags present in this message. These include #devops, #party-of-the-week and #/dev/null.

You can also follow them (see MORE / TAGS / Follow). Followed posts do appear in the feed.

Also, you can restrict the messages in your stream to those matching the hashtag. This is done by selecting one in MORE / # TAGS and clicking on them while in the HOME area.

A bit more interesting is that you can also put a hashtag on your home page:

• click on MORE / TAGS
• click on party-of-the-week. If more than one tag shows up above the list, remove the others by clicking on the cross symbol
  
• on the three dots select Pin to home
• switch to the HOME area

You'll see a new entry for the tag. When it is selected, all messages that include the tag will be shown in the stream.

If you select multiple hash-tags and pin them to your home page, then the resulting stream will include all messages that have all of the hash-tags.

---

Hashtags can consist of any character except . : ; , < & ' # ) ( and white space. If a hashtag shall include one of these characters, you must enclose it in quotation marks, such as in #"Christoph's tag".

 

Channels

An interesting concept in Connect is called a "channel". In essence, channels are combinations of hashtags (as we have seen before) which are automagically applied to messages. All threads that match the combination are considered to be the content of the channel.

Suppose the company Lisa and John work for has weekly meetings.

• They have agreed to use the hashtag #weekly-meeting for posts about this meeting. This is used for several types of posts that are related to that particular regular meeting, such as meeting minutes, agenda items, and other discussions
• So they have also agreed to use the hashtag #agenda for agenda items.
• To identify items that have not yet been discussed, they use the hashtag #open

Have Lisa post a message with content #weekly-meeting #agenda #open let us discuss if we need this meeting or not in the Connect zone.

After a while, however, they find that managing all these hashtags correctly is cumbersome and error-prone.

Now, to fix that, Lisa does the following:

• in the MORE / TAGS list, she clicks on weekly-meeting
  
• using the 3 dots, she selects Create channel
• and creates a new channel with Name set to Weekly Meeting and Description set to Lisa and John use this to discuss their work items on a weekly basis.
• she switches to the CHANNELS area and clicks on #weekly-meeting (or Weekly Meeting). The tag is now shown in top of the home page
  
• using the 3 dots next to it, she  selects Pin channel

A new entry Weekly Meeting with a new type of symbol  appears in the list of items on the home page. It might be a bit confusing that you have to select the hashtag (#weekly-meeting) to pin the channel and then, the name you defined for the channel (Weekly Meeting) is shown in the list.

When the item is selected, all messages matching the hashtag are shown in the stream. Also, when a new message is posted when the channel is selected, there is no need to explicitly type the hashtags. Alls messages in the channel implicitly have the channel's tags. This greatly reduces the chances to mistype a hashtag.

Even more, when John switches to his CHANNELS area, he will find the same channel and can put it on his home page or follow it.

To support the management of agenda items, Lisa additionally does the following:

• in the MORE / TAGS list, she clicks on weekly-meeting , agenda and open
  
  The 3 tags accumulate on the top of the list
  
  
• using the 3 dots, she selects Create channel
• and creates a new channel with name Things to discuss
• and finally uses Pin channel to put the channel on her home page

When the new channel is selected and shown in the stream and a new message is posted, it inherits all three hashtags. To add a new agenda item, she merely needs to enter the text, no hashtags at all. This greatly reduces the amount of clutter in messages due to hashtags.

Select the Things to discuss channel (either from HOME or from CHANNELS) and post a new message with content extremely urgent - is the earth a disk?.

It will show up whenever the Things to discuss channel is selected or if one or more of the hashtags weekly-meeting, agenda or open are selected.

Finally after the meeting, when the issue has been discussed,

• she edits the post
• writes a summary and
  
•  removes the #open hashtag by clicking on it underneath the text box (it will be striked out then)
  

The post is now not part of the Things to discuss channel any more (but is still  part of the Weekly Meeting channel).

Search

Connect comes with a search provider.

Therefore, you can use the Search App to  search for messages in Connect. Can you see what a powerful App Search is?

While we are at that: do you remember how to give a user friendly name to the MessagesAPI search API provider?

Of course, there is also a search function within Connect. You can search for words where multiple words match if a post includes all the words. You can enclose strings in quotation marks to search for these exact strings.

Chat

There is also a Chat area in the Connect App.

Users can chat to other users or to groups (as defined in the PBX). As opposed to content in threads, chat messages cannot be seen by other users. It is meant for private conversations between users or within groups.

Also, chat messages are not searched for in the search area.

Non-persistant chat

You might have observed that there is a  chat option available when assigning Apps to users (or templates). This refers to a separate App built-in to the PBX (that is: no need to install an App service on your App platform).

This is a basic chat application with the following limitations:

• no persistent storage of messages
• no offline delivery of chat messages (that is: you can't send messages to users who have no myApps running at that time)
• no attachments with messages
• no group chats

This is a legacy App separate from Connect. It is therefore not necessary to assign that to users to have chat in Connect.

If a user has the chat App assigned (and hence the Chat App available in myApps) and also has the Connect App and a Connect license assigned, clicking of the Chat App icon will in fact open the Connect App instead. This is to help migrate users of the deprecated premium chat license to the Connect App.

The mechanism is controlled by the App for Advanced Chat property set in PBX/Config/Chat which must be set to the value of the SIP property of your Connect App PBX object. The default value is connect, so it is probably set like it should be without any administrator intervention.

More administrator stuff

There are a few more things to know for a Connect administrator. See the Configuration section in  Concept App Connect for more details.

The Translations App

You have already seen generic APIs such as the search API that allow Apps to provide services that can be consumed by arbitrary other services.

Another interesting API of that kind is the translation API.

To proceed with this chapter, you will need to obtain a (free) Deepl API key as outlined below. If this is not possible for you, you may skip all the practical exercises (those marked with this symbol: ).

Obtaining the API key

DeepL is the online translation service that actually provides the translations made available by their Translations API. To use it, you need to have an API key. Fortunately, DeepL has a free plan that includes such a key, that is sufficient for our demonstration purposes.

To obtain a free DeepL API key, follow the steps outlined in Agenda: Additional DeepL API key requirement in some courses.

App and Instance

To provide the translation service from the App platform proceed as follows:

• install the Translations App using the App installer
• use the corresponding Settings plugin to create the App object (use Translations API as Name and translations-api as SIP)
• also provide the API key you have received from DeepL

Allowing translations-api

To make sure both Lisa and John can use the translation feature, proceed as follows:

• assign the translations-api App to Lisa Svensson
• assign the translations-api App to John Doe

Use of the tanslation api

The (hidden) translation App which we have installed and configured actually provides a certain API known as the com.innovaphone.translate. We can see this in the API Monitor App:

"com.innovaphone.translate": {

"translations-api": {

"title": "Translations API",

"url": "https://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/translations/innovaphone-translations-api.htm",

"info": {},

"model": {}

}

},

This way, other Apps which have support for translations built-in can make use of it. Connect is such an App.

To see how that works, do this:

• as John Doe, select the Weekly Meeting stream
• reply to Lisa's agenda post with the text ???????????????????
  if you have translations in moodle turned on, then please turn it off before copying this text. This is an issue in the moodle translation feature that garbles non-ISO8859-1 text
  
  
• as Lisa Svensson, open this post
• note that there now is a Translate button
• click on the button and  see the translation

The virtual background App

The Virtual Background App is pretty similar to the Translations App in that it only supplies a hidden App which can be used by other Apps. In this case, it is the com.innovaphone.virtualbackground API which is provided:

"com.innovaphone.virtualbackground": {

"virtualbackground": {

"title": "Virtual Background",

"url": ""http://apps-dvl-vgr.training.innovaphone.com/dvl-vgr.net/virtualbackground/innovaphone-virtualbackground.htm",

"info": {

"config": "innovaphone.virtualbackground.config.mjs"

},

"model": {}

}

},

In order to be accessible by a user,

• the Virtual Background App and an instance of it must be installed
  
• the App object must be created (Virtual Background/virtualbackground)
• and the user must have the App assigned
• the using App may also require you to enable use of the function (for example, the phone or softphone App require you to  select the background mode)

Make sure both Lisa and John use the Blur background mode in their phone App.

Let's Encrypt

In order to obtain valid TLS certificates from the public Let's Encrypt (LE) certification authority  Lets Encrypt for our device, we can use the Connector for Let's Encrypt App.

So go ahead and install the App service along with its first instance from the App Store.

For any further information about this free, automated, and open Certificate Authority (CA) service, see their  official home page.

Service configuration

In order to request certificates for your devices, you need to configure the service. This is done in its Settings App plugin.

To configure the Connector for Let's Encrypt App service:

• download and install the Connector for Let's Encrypt via the app installer

• re-start the Settings App plugin
  A new item Christoph's AP letsencrypt appears
  
  
• open the plugin and switch to the Settings
  
  
• tick the Enable check-mark
  
  
• change the Let's encrypt directory URL from its default (which is https://acme-v02.api.letsencrypt.org/directory) to the staging service URL https://acme-staging-v02.api.letsencrypt.org/directory
  
  Of course, in a real-life situation you would not do this. However, here in the training, you don't want to create and subscribe real certificates. This is just for playing around with them and for this, the staging directory is exactly the way to go
  
  
• agree to the subscriber agreement
  
  
• set the Client password to ip411ip411 and take note of it (a strict policy here does not allow our usual friend ip411). You will need it later on each device you want a certificate for
  
  Again, in a real-life situation, you would use a secure password
  
  
• you can leave the Certificate Installation before expiry (days) as is (the default is 3)
  
  
• take note of both the Client URL and the URL for Let's Encrypt root certificates. You will need them later on each device you want a certificate for

Trust

So far, we have enabled and configured the Connector for Let's Encrypt (LE) App service instance. However, no one is using it yet. The next step would be to configure the devices (in our case, the IP411LEFT and the APPPLATFORM) to use it. They would then receive new device certificates issued by Let's Encrypt.

However, there is an important step to take before we do this. To understand what that is, we need to dig a little deeper into how TLS uses certificates.

TLS Handshake

There are several steps for a TLS client to connect to a TLS server:

1. Establish a TCP connection to the server
2. Obtain a certificate from the server
3. Verify that the certificate is from a trusted source
4. Verify that the subject name (or SAN) of the certificate matches the client's expectation
5. Start the data conversation

Note that some of steps 3 and 4 may be omitted at the client's discretion.

Step 4 is relatively simple: the client would check if the subject name matches the DNS name used to establish the connection.

Step 3 however is a bit more difficult. To perform this step, the client needs an a priori knowledge of trusted sources (known as certificate authority (CA)), the so-called trust list.

Each of our devices has such a list, which can be configured in the Trust list section of General / Certificates. By default there are  three entries:

• innovaphone Device Certification Authority
• innovaphone Device Certification Authority 2
• *.innovaphone.com

Note that these entries to the trust list are installed as part of the firmware. the first two certificates change rarely (in fact, the current ones are valid until end of 2047). The *.innovaphone.com certificate is being renewed each year. So if you updated a device from an older firmware, you might see multiple versions of it,  all but 1 of them probably expired.

The AP, by default, has a device certificate installed that is  issued by innovaphone Device Certification Authority 2 which is mentioned in the trust list. If we enable the LE client on the IP411LEFT, the TLS connection attempt from the PBX to the AP would pass step 1 (connect), 2 (obtain certifictate) and 3 (verify trusted source) above.

However, the certificate used by the AP by default is hard-wired to the software and has a generic subject name (i.e. not apps-dvl-ckl2.training.innovaphone.com). Therefore, step 4 (verify subject name) would fail.

If we enable the LE client on the AP first instead, a new certificate issued by LE would be installed there. This would have the correct subject name (apps-dvl-ckl2.training.innovaphone.com), so step 4 would pass. However, step 3 would now fail as the issuing certificate used by LE is not in our trust list.

Fortunately, the offending certificate would then be added to the list of Rejected certificates on our IP411LEFT. From there, we can simply add it to our trust list and here we go.

So now, the correct sequence should be clear:

1. configure the App service instance (already done)
2. configure the AP's LE client
3. wait for the new AP certificate to appear
   
4. configure the IP411LEFT's LE client
5. wait for the untrusted certificate to appear in the list of Rejected certificates
6. from there, add it to the trust list (the IP411LEFT LE client can now connect to the AP)
7. wait for the new device certificate to appear
   

---

When you are using the Devices App (which you should do of course ), there is another option available. You can copy the URL for Let's Encrypt root certificates found in the AP letsencrypt Settings App plugin to the  list of Sources for certificates in the Certificates device configuration settings.

Requesting a certificate for your AP

As you can  see in the AP's Settings / Security menu (accessible from the Burger menu), your AP still has the hard-wired default certificate installed.

To change that, we need to configure the Let's Encrypt client on the AP as follows

• go to Settings / Let's Encrypt (accessible from the burger menu)
  
  
• tick the Enable check-mark
  
  
• set the Let's Encrypt App URL to the service URL of your Connector for Let's Encrypt App instance: wss://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/letsencrypt/clients
  
  You can copy this  from the Client URL field in the Christoph's AP letsencrypt Settings App plugin
  
  
• set the Let's Encrypt App Password to the value you have set as Client password in the Let's Encrypt App service instance configuration (didn't you take note of it? never mind, it is ip411ip411)
  
  
• never touch the Key length (bit) (which defaults to 2048 bits) unless you really know what you do
  
  This is because changing the certificate's key length to a higher value would impact the performance of your system significantly, as it slows down each and any TLS connection establishment
  
  
• set the DNS name(s) to the DNS name of your AP: apps-dvl-ckl2.training.innovaphone.com
  
  We could add more DNS names here which would appear as subject alternate name (SAN) in the certificate issued by LE
  

The DNS name must be functional in your DNS system and must point to a device that allows external TCP access to the device for which the certificate is intended on port 80 (HTTP). LE will use this DNS to connect to it, thus verifying that you are the owner of this DNS domain. In practice, this will probably be your Internet router with port forwarding or a reverse proxy.

It's a good time to have a cup of coffee now (well then, perhaps better an even quicker espresso) until you see the  new device certificate appearing in burger menu / Settings / Security.

It is essential that you first acquire the LE certificate for the AP. This is because access to the AP is required for all other devices in order to obtain a certificate from LE. For this to work, you need to trust the AP's certificate (and hence LE's certificates). This can only be done once you have configured the LE client on the AP.

 

Requesting a certificate for your IP411LEFT

Now that you have a service that can talk to LE, you can have your IP411LEFT request a certificate from there.

On Services / Lets-Encrypt configure the following items:

• tick the Enable check-mark
  
  
• set the Let's Encrypt App URL to the value shown as Client URL in the Let's Encrypt App service instance configuration (didn't you take note of it? never mind, here it is wss://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/letsencrypt/clients)
  
  
• set the Let's Encrypt App Password to the value you have set as Client password in the Let's Encrypt App service instance configuration (didn't you take note of it? never mind, it is ip411ip411)
  
  
• never touch the Key length (which defaults to 2048 bits) unless you really know what you do
  
  This is because changing the certificate's key length to a higher value would impact the performance of your system significantly, as it slows down each and any TLS connection establishment
  
  
• set the DNS name to the DNS name of your PBX: hq-dvl-ckl2.training.innovaphone.com

The DNS name is the same as you have set as DNS on PBX/Config/General. Again, it must point to a device that allows external access to the PBX.

As we have discussed before, this will not work as the LE root certificate that is used to create the new device certificate is not in the IP411LEFT's trust list. Instead, it is  listed in the Rejected certificates section in General/Certificates.

To fix this situation, we must add the LE root certificate to our trust list. You will probably see two certificates: apps-dvl-ckl2.training.innovaphone.com and (STAGING) Wannabe Watercress R11 (or something similar, LE is using several root certificates). Although you could add the first certificate and it would work, we recommend to  add the LE root certificate to the trust list. This will be the last entry in the list of rejected devices right now. This will trust all certificates that are issued by this root certificates.

Again, this is now a good time for a (very quick indeed) coffee. After that, you will see the  new device certificate issued by LE.

We recommend to add it's root certificate to the trust list as before.

---

You will notice that both accessing the IP411LEFT and accessing the AP from the browser (i.e. from within myApps) requires you to accept a security warning from your browser.

This is because the certificate issued by LE is not a true good&trusted certificate. It would be if we hadn't specified the staging URL to the Let's encrypt directory.

Deploying the LE root using Devices

There is another option to make sure your devices trust the certificates issued by LE. This method is also used by the configuration done by the Install. This is to add  the URL for Let's Encrypt root certificates (which you find in  the AP letsencrypt Settings App plugin) into the list of Sources for certificates in a Certificates configuration job in the Devices app.