Course13:IT Advanced - 06 Setting up the Apps
This books looks at the setup of various standard Apps in more detail
More PBX vs. instance interaction
Reports
- download the Reports App service from the App store and create a new instance (we have already done this before)
- 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 CDR delivery path and credentials in Gateway/CDR0
- setup users so that they have the appropriate licenses for their calls to appear in Reports
The client side
PBX / Config / General (our master PBX)
- select HTTPS as Log Server Type
- use apps.invalid member reference '.domain' in 'domain' 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 /invalid member reference '.domain' in 'domain'/reports/cdr as Path
Note that the prefix /invalid member reference '.domain' in 'domain'/reports is what has been configured as Webserver path in your Reports instance while /cdr is a fixed part you always use to send CDRs to the Reports service instance - use an appropriate User of your choice for CDR delivery. Note that this user name will only be used to authenticate the delivery of CDRs to the Reports App service instance. Here in the training, please use cdr (so that your teacher knows it and can help if need be)
- use an appropriate secure Password of your choice for CDR delivery. Note that this password will again only be used to authenticate the delivery of CDRs to the Reports App service instance. Here in the training, please use ip411 (so that your teacher knows it and can help if need be)
The server side
- set User name and Password in the Account for the CDR authorization dialog to the values you have configured on the client side before (cdr and ip411)
Trying it out
- use the + Add app function of the Christoph's AP reports PbxManager plugin to add the App objects for
- the Call List app
- the Call List API
- and the Reports app to the PBX
- now we can assign the reporting and callist App as well as the callist-api to John Doe in his user record in the PBX
- then 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) and call 14, you'll see new entries appearing
Licensing
- start Reports 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
- 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
For historical reasons, there is some confusion regarding the name of the App. It should have been called Reports from the very beginning but it started out as Reporting and therefore, you find both names.
Users
- 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
- download the Users App service from the App store
- add a new instance called users for domain invalid member reference '.domain' in 'domain' with Password and Database password ip411
- start the new instance
The App objects
- use the + Add app function of the Christoph's AP users PbxManager plugin to add the App objects for
- the Profile App
- the Users App
- the Users Admin App
- and the UsersApi API to the PBX
- now we can assign the users, profile and usersadmin 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
Replication
WebSocket
Replicator properties
- the PBX Password (we had set that to ip411 in the PBX)
- and the PBX name (which is hq)
Self-service device provisioning
- 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)
The profile App
- 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 IP411LEFT here (as it is the master PBX)
- 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)
Contacts
- install the Contacts App service from the App store
- add an App service instance called contacts for domain invalid member reference '.domain' in 'domain' with password ip411 (of course only in the training, in real life you'd rather choose a secure password)
- start the instance
- use the Christoph's AP contacts PbxManager 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.
When you 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
- 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
- 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.
Directories
- 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
Number resolution in action
- 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 call (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 (seeConcept 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 to this request to all search API providers available:
- Contacts
- Users
- any PBX LDAP object available
- Outlook contacts
For an outgoing call, the scheme is pretty similar: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.
- 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
Number normalisation
- 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.invalid member reference '.domain' in 'domain'/dc=entries?givenname,sn,company?sub?(metaSearchNumber=+%n)?bindname=apps.invalid member reference '.domain' in 'domain'\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)
Name resolution in action
- 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:
- 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)
Number normalization
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
Name resolution in action (cntd.)
- 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 myAps (using EpSignal)
The full picture
Multiple directory sources
- 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). Results are made available to all PBX users
- 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
- 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
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.check-marks.
- 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.invalid member reference '.domain' in 'domain' in your case). We suggest to use ldap-guest as user. So in your case, you end up with hq.invalid member reference '.domain' in 'domain'\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
- tick the Enable and Use TLS check-marks
- set the Server property to the DNS name of your App platform (apps.invalid member reference '.domain' in 'domain' 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. The domain is your PBX System name (invalid member reference '.domain' in 'domain' in your case). user is the name of your Contacts App service (contacts). So in your case, you end up with apps.invalid member reference '.domain' in 'domain'\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 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
- set Country Code to the country code of your trunk line, invalid member reference '.netccext' in 'netccext' 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
invalid member reference '.netrealacext' in 'netrealacext' invalid member reference '.netrealacextexplanationbracketsempty' in 'netrealacextexplanationbracketsempty' - 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
invalid member reference '.netacescape' in 'netacescape' invalid member reference '.netrealacextexplanationbracketsempty' in 'netrealacextexplanationbracketsempty' - 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).
invalid member reference '.netccescape' in 'netccescape'invalid member reference '.netacescape' in 'netacescape' - 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
- add a new User called hq.invalid member reference '.domain' in 'domain'\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
- open the PbxManager in myApps
- click on the Christoph's AP contacts plugin
- click on Change 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
... number/name resolution in the PBX
Reverse lookup
- 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=apps.your-domain\name-of-your-Contacts-instance.
In your case, this would be
ldaps://apps.invalid member reference '.domain' in 'domain'/dc=entries?givenname,sn,company?sub?(metaSearchNumber=+%n)?bindname=apps.invalid member reference '.domain' in 'domain'\contacts
The Password shall be set to a secure password in real life. However, as usual, here in the training we use ip411 as password. Note that this configuration won't work for now, as we first need to also set it up in Contacts - set the Prefix for Intl/Ntl/Subscriber/Area-Code/Country-Code prefixes to
- Intl: prefix to access international numbers, including the trunk-access-code. In your case
0invalid member reference '.myccext' in 'myccext.ccescape'invalid member reference '.myccext' in 'myccext.acescape' - Ntl: prefix to access national numbers, including the trunk-access-code.
In your case
invalid member reference '.netrealacescapewithtrunkac' in 'netrealacescapewithtrunkac' - Subscriber: prefix to access local numbers (also known as trunk-access-code).
In your case
0 - 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!
invalid member reference '.netrealacext' in 'netrealacext' invalid member reference '.netrealacextexplanationbracketsempty' in 'netrealacextexplanationbracketsempty' - Country-Code: the country code of your trunk line.
In your case
invalid member reference '.netccext' in 'netccext'
... Trying it
Trying it
- 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
- 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.
- try to search for both j and f
Notice that the search for f works as expected but the search for j does not. This is because visibility through LDAP access is a yes/no configuration in the PBX object (controlled by the Hide from LDAP check-mark which is off for John Doe). Visibility through search-api access however is controlled by a much more sophisticated privacy mechanism which we need to configure before it works
- 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 invalid member reference '.domain' in 'domain' (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