Course11:Advanced - myPBX

From innovaphone wiki
Revision as of 10:46, 29 April 2015 by Ckl (talk | contribs)
Jump to navigation Jump to search
There are also other versions of this article available: Course11 (this version) | Course10 | Course12

Book about the UC client myPBX

Introduction

What is UC?

Unified communications (UC) is the integration of real-time communication services such as instant messaging (chat), presence information, telephony (including IP telephony), video conferencing, data sharing (including web connected electronic whiteboards aka IWB's or Interactive White Boards), call control and speech recognition with non-real-time communication services such as unified messaging (integrated voicemail, e-mail, SMS and fax).

UC is not necessarily a single product, but a set of products that provides a consistent unified user interface and user experience across multiple devices and media types. ...

Source: wikipedia.ico Unified communications

So far so good - but what does this mean for an innovaphone based communications platform?

innovaphone UC

With the UC-client myPBX, innovaphone provides a solution in the UC-area and integrates additional new ways of communication into its existing solution portfolio. In v11r1, we have added some new features to myPBX
  • application sharing
    the windows myPBX version supports native application sharing (no 3rd party application) between myPBX clients
  • the multi-party conferencing facility now supports both audio and application sharing conferences
  • WebRTC
    by virtue of wikipedia.ico WebRTC, myPBX now supports a purely web-based HTML5 audio endpoint. This works like a software phone, however, it is not necessary to install any software or plug-in for it to run. The WebRTC function is integrated in the plain HTML5 client. It therefore runs on any WebRTC-enabled web browser on any platform!
  • a native myPBX app has been released for Android-based mobile phones

This book will give you an overview about the capabilities of myPBX, tell you how to setup and of course use the various features it offers. As always, we refer to other books of this course, to our wiki-based documentation and will sum-up all this with a lesson.

Concept

In general, fish-help.png myPBX is a web based UC client.

It interacts with several other devices and applications as shown in this screenshot.png overview.

myPBX always communicates via an http- or HTTPS-based AJAX connection to an innovaphone PBX - which is powered by firmware Version10 (this is what the book and whole training is about).

As myPBX is compatible to any innovaphone PBX it is independent whether this is an innovaphone gateway or an IPVA.

At the PBX, usage of a myPBX client creates a myPBX session which is always connected to a dedicated user object. By this it can control one or more phones that are registered to this object (including any forking destination when mobility is used). The user needs to own a license to operate myPBX.

Call-control is done via the PBX. Dialing a number from myPBX forces the PBX to signal the call-request to the selected phone and to setup a call to the destination. This behaviour applies for audio, video and chat signalling.

For the video service, there's another HTTP-based connection directly from the myPBX-launcher to the phone. By this, the phone negotiates video-calls with myPBX. Video-streaming is done directly between myPBX-launcher-clients.

As usual any directory services are defined in the PBX and any search results are retrieved via the HTTP connection to the myPBX client. Number resolution of incoming calls is done in the same way - first lookup in directory services, then transmission of results to myPBX for display.

The call list service to keep track on any calls originated or terminated by this user is based on the reporting application, hosted by the Linux application platform. Any call data records belonging to the myPBX user extension are transferred from the PBX to the reporting application. From here myPBX retrieves them via an http- or HTTPS-based connection.

There are 2 operation modes of the myPBX client

  • purely web based, only a fish-help.png web browser is needed and thus it can run on any OS
  • an installer version called fish-help.png Windows Launcher, installed at the local Windows PC.

Web-based Client

The web-based client offers the possibility to use myPBX at any operating system via a simple browser. This means just opening a administrator-given URL of the PBX gives access to various UC-features to be used on any end-user device.

The URL can be retrieved from the screenshot.png PBX-menu - by either directly clicking on the Go! button or just copying the URL to your browser.

The web-client does not require any additional software to be installed and offers following features:

  • control of any user-registered IP-telephony-device
  • call-control (originate and terminate any calls, various telephony-features, etc.)
  • access to phone book(s)
  • presence handling (set own presence, retrieve presences of other PBX-users)
  • emailing
  • call-history via call-list feature
  • chat
  • application sharing
  • favourite-list (aka buddy list) management

Remark: In spite of the OS-independence of the web-client, we want to highlight that there's no support for touch-screen-devices till now. You may try to open the URL within your touch-screen-devices' browser, but may encounter some issues in accessing myPBX-functions requiring mouse-over or right-mouse-button actions.

Windows Launcher

Some desirable features can not be implemented on a pure HTML5 base. To be able to offer such features too, we provide the fish-help.png myPBX launcher program (for Windows only). This is a tool developed for the Windows OS (Windows7 and later). It is not needed to use myPBX but it adds some convenient functions that are not available otherwise.

Benefits of the myPBX launcher are amongst others:

  • video telephony
  • application sharing
  • Microsoft Office Integration
  • dialling from an application by using a hotkey
  • display of a popup notification (e.g. for incoming calls)
  • configuration of a standby - URL that can be used in case that the master - URL is not accessible (standby function)

The installation file of the "myPBX Launcher" tool uses the MSI format and can be used for a domain wide roll-out of the software. The "Windows Launcher" stores its configuration files in user specific folders and can be used in Terminal Server environments as well.


Features

For features and their usage please refer to the link_intern.png myPBX user guide (as of this writing 3/2015, this is still based on version 10 though).

Configuration

Depending on the used myPBX client, you may need to configure only the PBX (web-client) and also the user (launcher version). Following subchapters will provide you with an overview how to do so and which are the most important issues.

A chapter about general rollout completes this section.

Administrator Configuration

First of all, the PBXs need to have an sufficient amount of myPBX licenses at all for myPBX usage in general.

(Overall Description) Second, the dedicated users need to have an active myPBX license ticked at the fish-help.png user object.

Please note that the myPBX license is part of the UC-License. Wherever a myPBX license is used, a UC-License will do too. For more detauils about licensing please refer to the link_intern.png innovaphone Licensing model.

To enable myPBX for the PBX users, you only need to tick the screenshot.png enable check-mark in PBX/Config/myPBX.


You must enable myPBX on each PBX, having registered users that want to use myPBX.
The myPBX HTTP connection terminates always at that PBX where the user objects Parent PBX is configured. When a myPBX user starts the client using a link from another PBX, the HTTP connection will be redirected to this PBX.

Device definition

As the user can choose the device for call control (phone registered at the user object and/or forking destination), it is recommended to give each device a unique and self-explaining name. This device name is then displayed in the myPBX screenshot.png drop down device list.

Password definitions

Phones should not register with the user's password, as this would break the registration when the user changes his password. Instead, either the screenshot.png PBX password or the screenshot.png certificate based registration should be used.

Refer to the Access to VoIP chapter in the innovaphone Security Features book for more details about these registration methods.

Access Rights at User

For presence and dialog monitoring access rights have to be configured at the individual user objects. The admin can do that in the fish-help.png PBX/Objects - menu, at the "Access" column. As discussed before config templates can be used for mass deployment of Access Rights.

A user can grant access rights to another user, a group of users(PBX-groups) or to all users in a domain(System name). If access rights are given to users in a PBX-group, the users in the group must be active members in order to get information about the monitored user.

The administrator must keep in mind that access rights are implicitly assigned to active users of a PBX user group. Active group members can see the presence and call information of other users in the group.The Admin can use the Group Default Visibility settings in fish-help.png PBX/Config/General to restricts this implicit rights.

Phone book definition

myPBX can use centralized phone books, the PBX phone book and an external phone book (via LDAP). It uses the same fish-help.png settings as a phone that is registered at the user object, thus the users directory settings must be stored at the PBX. The myPBX client uses these settings (directory setting must be stored at the user object or on a template) to retrieve the Directory and Dialing Location settings. Dialing Location settings are important to normalize numbers being retrieved from any central phone book for dialing purposes.

User Profiles


Each myPBX user can have a number of fish-help.png favourites (a.k.a. as buddies). The administrator can screenshot.png pre-configure these in the Profile column of the PBX's object list.

Notes:

  • To add internal users, either use name or number, never set both
  • For adding external contacts, you can enter the number (including trunkline access-code). This type of a buddy behaves like a short-dial, as no dialog and presence information can be fetched.
  • If your instead configure a SIP-URI, the PBX will try to setup a dialog und presence subscription. If this succeeds, the buddy will be monitored. If not, the buddy can not be added from withing the myPBX client. However, it can still be added through the admin interface

Email integration

myPBX also supports sending emails out of the fish-help.png buddy list. The client creates the recipients email address using this procedure:

  • if ticked, the screenshot.png email of the fish-help.png user object is used as local-part (everything prior to the @) of the email address.
  • the fish-help.png System Name is used as domain-name if the Use as Domain option is activated.
  • if in the users email field the user name is not ticked, anything configured in the email-freetext-field is used as either the local-part (together with the system name as domain), or even a completely different email-adress including the domain.
  • definition of external email recipients only works via the fish-help.png profile settings, where a SIP-contact has to be defined using the mail-address as contact name (this could not be done via the client because of unreachability during definition).

Correct definition of email-adresses is important for proper function of the fish-help.png Microsoft Office integration . Email adresses of MS-Outlook-users need to be defined here as well.

Video


The PBX needs to have a sufficient amount of video licenses at all, and second the dedicated users need to have a video license activated at the fish-help.png user object itself.

The video license is part of the UC license.

Application Sharing

There is no special setup required to make application sharing work. Generally, the steps required to make video work are sufficiant.

Call List Services

The myPBX client retrieves the user's call list information from a call list service. This can either be a reporting server on a Linux application platform or a PBX running a CALL-LIST service.

screenshot.png Call List Options



In both cases, the PBX must be screenshot.png configured to generate CDRs.

Using Reporting as Call List Service


For the call-list service, an innovaphone reporting application may be used. This setup is selected by screenshot.png choosing REMOTE-AP as Type in the Call List Service settings.

The IP address of the Linux application platform is screenshot.png configured as Host in the Call List Service settings.

To ensure secure access to call list data, both the PBX and the reporting service need a shared secret. Therefore, the User name of the Linux web server credentials of the Linux application platform providing the reporting service is screenshot.png configured as User and the respective password as Password in the Call List Service settings.

(Overall Description) Even though the Reporting Application is used to store the call lists, a Reporting License is not needed for this service. Therefore the fish-help.png reporting license flag at the user object should not need to be ticked for call list service only.

Using the PBX built-in CALL-LIST Service


If there is no Linux AP and hence no reporting service available (on IP302, IP305 and IP800), the built-in CALL-LIST service can be used. It is enabled by screenshot.png specifying a Folder in the Call-Lists Services properties. This will be the name of the folder on the CF card where the call information is stored.

If the Folder property is set to an URL (instead of a plain directory name), the CDRs would be stored remotely instead of on the local CF card.

As with the above setup for the reporting service, the PBX and the reporting service again need a shared secret. In this setup, the screenshot.png User and Password in the Call List Service section must be set to the User Name and Password of the administrator account defined in General/Admin.
(Overall Description) This call-lists service does not support LDAP name resolution. If LDAP name resolution is required, use the Reporting application as Call List Service.

Multi site - master/slave - installations

In a multi site setup the myPBX client has to be logged in at the registration PBX of the phone that it will control. If the myPBX client registers at the wrong PBX, the connection attempt is redirected to the master PBX. The master PBX will then check the Parent PBX attribute of the user and redirect the connection to the correct PBX. In case that the master PBX is also to Parent PBX of the user, it will accept the registration by itself.

screenshot.png Redirection scenario

Example: When you use the master PBX for login (and your parent PBX is the slave, like in the picture above) and the slave breaks down, the phone will register at the master and thus the myPBX still works.

The redirection of the master PBX requires that the master PBX knows all users in the PBX system. This will not be the case in a installation were the slave PBXs don't replicate their users from the master PBX but have own user databases.

Notes:

  • When in the case above master breaks down myPBX-webclient usage will no more be possible as the link does not work even when the slave is up. By using myPBX Windows Launcher, this circumstance can be fixed when using an alternate URL - see next topic.

The redirect feature also works for the myPBX Windows Launcher.

Standby PBX

(Overall Description) This feature is only supported with the myPBX windows launcher.

Within myPBX launcher configuration you can define an screenshot.png alternate URL

, that represents the standby PBX for this user.

As myPBX connections do have a time-out of 30 seconds, upon timer-expiry due to no answer, the Windows Launcher will switch to the alternate URL. If both PBXs are not available, the launcher will try to reach both URLs in a round-robin mode, until it is connected or the launcher gets closed.

Assuming that the standby - PBX is available, the myPBX connection remains active until the master PBX becomes active again. As soon as the standby - PBX is able to register at the master PBX, it will close all its myPBX connections. The windows launcher will then try the primary URL and connect to the master PBX.

User Configuration

The user will get a link where to connect with a user name and password. When using the Windows Launcher, the user needs the install file, the link, the user name and password to login.

You get the link when enabling myPBX as administrator and screenshot.png click on Go!. In a master slave scenario each myPBX user can use either a link to the local PBX or to the master PBX(as the myPBX - client gets redirected to the Parent-PBX of the user).

Login


For login a user-name and password is needed, this screenshot.png settings are done by the administrator at the user object. The user can change screenshot.png his password in the myPBX client and thus changes the password setting at the user object. This cannot be disabled.

Profiles


The myPBX user can set up to 4 different profiles. This fish-help.png profile settings are stored at the PBX. For each profile the myPBX user can have up to 32 different contacts in his buddy list.

Diversions


The myPBX user can configure standard diversions(no dynamic or conditional diversions). You cannot restrict the myPBX user to not configure diversions.

Access Rights


The myPBX user can pro-actively set the fish-help.png access rights for a certain user, a group or the whole domain via the screenshot.png client UI.

If access rights are set via a template the user can see them in the myPBX client and can overwrite them using his client.

Miscellaneous


As maybe not generally used and required, we want to mention here an additional V10-myPBX feature for end-user - implemented protocol handlers. 

That is setting up a phone-call or chat directly from the browser using a dedicated protocol tag:

tel:xxx - will start a h323-phone call to extension xxx
sip:xxx - will start a sip-phone call to extension xxx
sips:xxx - will start a sips-phone call to extension xxx
im:xxx - will start a chat to extension xxx

As this implies proper registration of applications to these tags, we just want to mention the possibility about its usage.

For questions concerning installation issues, please refer to the fish-help.png corresponding article

Roll-out

Centralized configuration roll-out can be done with the fish-help.png config template, you can set:

To roll-out the client you can :

Note: When you run the windows launcher, it opens only with the Microsoft IE browser, even if you have set another browser as standard browser. myPBX supports the Internet Explorer from Version 8.

Softwarephone

Softwarephone

The innovaphone fish-help.png softwarephone is an own product without user interface. For controlling purposes (call control) a CTI software is needed.

It can be controlled with the myPBX client or with any other third party CTI software.

The innovaphone softwarephone is an .exe file and currently supports only Microsoft Windows operating systems.

Its installed using a MSI-package and comes with a setup wizard for fish-help.png configuration settings.

A fish-help.png softwarephone license is needed to run the softwarephone. Additional to the softwarephone license a port license is needed to register the phone at the PBX (if not already obtained for this user).

WebRTC Client

The myPBX HTML5 application can be used as a software phone if it runs on a WebRTC compliant browser. In this scenario, the web browser running myPBX is used a media endpoint. Therefore, the bowser will ask your for permission to use your microphone and loudspeaker/headset. When this is done, you can place and accept calls right from within myPBX as usual and you will need no other phone, just the browser.

screenshot.png webrtc



This allows users to take part in PBX conversations with just a web browser and an HTTP connection to the PBX.

Although WebRTC itself supports audio, video and xparent channels (such as application sharing), myPBX as of v11r1 is limited to audio (G.711).

Please note that even if WebRTC emerged in the browser environment, it is not limited to browser communication. innovaphone device do support WebRTC natively. That is why they can communicate directly to a WebRTC enabled device, without need for a gateway.

PBX Configuration

In order to use WebRTC, the WebRTC client must use a STUN server. In the case of the web browser, the STUN server made known to the web browser by the myPBX HTML 5 code which in turn receives the STUN server configuration from the PBX. The PBX will send the value screenshot.png configured as STUN Servers in fish-help.png IP4/General/STUN.

Please note that the PBX may receive this setting in turn as a fish-help.png vendor option (STUN Server) with DHCP.

Which STUN Server to use?


You can of course use any publicly available STUN server (such as e.g. stun.l.google.com shown in the STUN Servers example). However, this may be dangerous, as the owner of this service may impose access restrictions later on without any notice. As STUN is essential for your setup to work, you should rather select one you can be sure of.

The STUN server of your SIP provider may be a good choice. Also, any innovaphone device that is exposed to the internet can be used as STUN server (read more about this in the Public PBX Access book).

User Configuration

The WebRTC function in myPBXneeds to be enabled per user. This is done by creating a special entry in the Devices list of the user that screenshot.png has the Config VOIP check-mark ticked. Once you have done so and applied the new configuration, a new tab appears in the user object editor. It has the Name you configured in the WebRTC Devices entry as title. As opposed to other entries in the Devices list, you must supply a Name thus. Otherwise, the new tab will not appear. In the new tab, you select WebRTC from the drop-down list.

The Hardware Id is irrelevant, except that it must be unique throughout the system. The Name is screenshot.png shown as device name in myPBX as usual.

Usage

If the administrator has configured WebRTC for a user, the new device can be selected from within myPBX as usual. In this case however, the browser (which actually implements the selected device), will screenshot.png ask your for confirmation to use one of your devices. The details of this depend on the browser you use and will differ from browser to browser thus.

Once you have confirmed access to the device, you are ready to start or accept calls.

Please note that the entire handling of the headset depends on the browser and may vary thus too.

Supported Browsers

As of this writing (3/2015), Firefox, Chrome, Opera, thr Android Browser and Chrome for Android support WebRTC. However, none of them support it on iOS. For a then-current list of supporting browsers, see www.png caniuse.com.

Unfortunately, Internet Explorer does not support it either currently. So WebRTC can not be used from within the myPBX launcher yet (you need to open an extra myPBX instance using one of the supported browsers). Microsoft has announce support for WebRTC in upcoming Internet Explorer versions.

Limitations

WebRTC enforces ICE and DTLS


WebRTC as per standard mandates the use of ICE/STUN and DTLS.

While this is a good choice from a technology and security point of view, it may create interoperability issues. Traditional VoIP endpoints which do not support these protocols (and only a few do so far), will not be able to communicate with an endpoint that uses WebRTC. This will for example disable any call from a WebRTC endpoint to most if not all SIP trunks.

To overcome this, you can use media-relay in the SIP trunk.

screenshot.png Overcoming Interop Issues with Media Relay



Please note that media relay in the PBX (RTP Proxy in fish-help.png PBX/Config/General, as opposed to media-relay in the SIP trunk) will not fix the issue. This is a limitation in v11r1 and v11r2 and may be fixed in v12. As a result, this mechanism can be used to allow WebRTC calls from/to entities that are connected via the Gateway level (such as SIP trunks). It does not fix interop issues towards endpoints registered with the PBX (such a 3rd party phone or XCapi). If this required, you need to route calls from/to these devices through the Gateway level.

No automatic physical location detection for the WebRTC client


The WebRTC signalling client actually resides within the user's registration PBX. The WebRTC entity in the web browser merely acts as media endpoint. For this reason, there is no automatic detection of the user's physical location. (for more information on this, see the chapter Physical Location in Distributed PBX).

If correct handling of the physical location is required, you can set it as part of the URL used for myPBX: http://pbx-address/PBX0/MY/client.htm?phys=location will force the PBX to treat location as physical location for the WebRTC client.

myPBX for Android

From v11r1, we have a product called myPBX for Android. This is a complete software phone for the Android smartphone platform with a modern look and feel.

However, in the context of this book, this is not really a myPBX. Rather, it is a full-blown software phone with user interface app. From a protocol and configuration point of view, it behaves exactly like any other innovaphone hardware phone.

There is one particularly useful setting for myPBX for Android users (although it could be used for other endpoints too). When you use a VoIP client on a smartphone, you really want to use VoIP calls as long as you have network access. However, when you loose IP connectivity, you would like to use plain old PSTN-based mobility.

This can be done by screenshot.png setting the No Mobility check-mark for the Devices entry you use for the smart phone. When this check-mark is ticked and you have mobility configured, the mobility function is disabled as long as the device is registered.

For more on mobility, see the Mobility book.

ToS mappings via Policy-based QoS

The signalling and media data packets sent by the innovaphone myPBX and innovaphone SoftwarePhone applications should be marked with corresponding ToS value, as it is done on other innovaphone Hardware. This is required to be able to prioritize the voice traffic before other non time critical heavy traffic on WAN connections.

Also, the calls in local network to WiFi phones IP62 and IP72 rely on the correct mapping of the RTP packets, to be able to implement WMM PowerSave (U-APSD) on the WiFi equipment.

However, the direct marking of the IP packets on the modern Microsoft Windows operating systems must be done by usage of the Policy-based Quality of Service (QoS) mappings of the local computer.

In the wiki article fish-help.png Set Type of Service (ToS) DiffServ DSCP Values for innovaphone Windows Applications (SoftwarePhone, myPBX Video) you will find the way how to configure the policies and which ToS values can be used as default.

Troubleshooting

Troubleshooting

Troubleshooting in myPBX can be done by different roles which should be escalated in the following order:

  • tracing by the administrator
  • tracing at the users PC

As myPBX is an end-user application we recommend in any case first to try finding out any problems by checking from administrator side before disturbing user with such elementary tasks like tracing.

So - how to do this?

Tracing by the administrator

(Overall Description) This setting is for administrator usage only.

Status overview

Active myPBX applications for all users can be monitored with their status via the fish-help.png PBX/myPBX tab.

Correct activations of video are shown via the fish-help.png PBX/Registrations tab. Within screenshot.png column Video, one can see if a dedicated user has an activated video license [Activted] and if a video device is connected by use of myPBX [Connected]. There's no status about an already active video call.

Tracing

To trouble shoot user interaction and capture any potential errors, it is useful to switch on the myPBX and Administration logging in fish-help.png Maintenance/Diagnostics/Logging:

screenshot.png Logging Settings for myPBX

All user interaction will be logged under the Administration logging. Look for lines like

20120508-092518 PBX_CLIENT 0 (0590493282:CLSD) created
20120508-092518 CMD - mod cmd PBX0/MY pbx-client-message /message login /username ckl /nonce 73870806 /session 590493282 /seq 997840753 /digest d5401a9232ec7427779cbe5389c206c1a5571bac
20120508-092518 PBX_CLIENT 0 (0590493282:CONN:ckl) login


The /session parameter ( /session 590493282 in the sample above) will show up in each interaction for the given user session, so it can be used to find all relevant CMD entries for a single session (as all sessions running on this particular PBX will be shown in the log). Likewise, all the relevant PBX_CLIENT messages will share the same session id in round braces (such as in (0 590493282 :CLSD) in the above example).
Here is a sample logging where a user (ckl) logs in, creates a chat session ( im-add ), invites another user ( im-call-initiate /name afi ) in a chat and then creates an application sharing meeting

20120508-092518 PBX_CLIENT 0 (0590493282:CONN:ckl) login
20120508-094015 CMD - mod cmd PBX0/MY pbx-client-message /message im-add /pseudo im-null-afi-13740 /session 590493282 /seq 997840759 /digest b3fdfec066b14e48d3b6a26988cf1acf4fb35681
20120508-094015 CMD - mod cmd PBX0/MY pbx-client-message /message im-call-initiate /im 1 /name afi /session 590493282 /seq 997840760 /digest 2bbc30b6f4f781e64653e0577470e7188d9a3855
20120508-094016 CMD - mod cmd PBX0/MY pbx-client-message /message im-meeting /id 1 /session 590493282 /seq 997840761 /digest 3f9facd61e7a6988d2d4f205599c40d847532767
20120508-094017 PBX_CLIENT 0 (0590493282:CONN:ckl) create meeting

Tracing at the users PC

(Overall Description) This tracing option is for myPBX windows launcher only.

If the screenshot.png checkmark "Write trace" is enabled in the launcher configuration, the launcher writes a rotation of trace files to the folder :\Users\[UserName]\AppData\Roaming\innovaphone\myPBX.

To access these files, just click on the link below the trace button - an explorer will open showing you all available traces. They are numbered in ascending order - the latest trace is contained in the highest numbered file!

myPBX call list


First of all make sure the Reporting Application is configured correctly.

In case you see an error message instead of the Call List like received auth 21f...9ced does not match, check if the User Name and Password configured fot the fish-help.png Call List Service are correct.

User Guide

There is a user guide available on the web. See link_intern.png Bedienungsanleitung myPBX, V11R1 and link_intern.png Operating Manual myPBX (V11R1) - EN. Further language versions may be available