Reference10:Concept myPBX

From innovaphone wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
There are also other versions of this article available: Reference9 | Reference10 (this version) | Reference11r1 | Reference12r1 | Reference12r2

Overview

myPBX is the UC client of the innovaphone PBX. It is intended for assisting typical phone users with their everyday tasks. It consists of two parts:

  • A web application that runs in any modern web browser. It provides the functionality needed for audio telephony, instant messaging, monitoring peoples statuses and more.
  • The myPBX launcher is a Windows application that integrates the myPBX web application into the Windows desktop and adds some interesting additional features like video telephony and Outlook integration.

Web application

The main user interface is an HTML5 application that runs in a web browser. It communicates with the PBX using HTTP-Requests (AJAX). The actual session logic is implemented inside the PBX.

The picture shows how call control is done. The myPBX session has access to the phone registration as they are both located in the same PBX. Thus it can monitor and create or modify calls.

Mypbx overview.png

myPBX launcher

The launcher is a tool for integrating myPBX into the Windows desktop. It is not needed in order to use myPBX but it adds some convenient functions that are not available otherwise.

  • Automatically open the myPBX web application on startup.
  • Desktop notifications.
  • Integrating external applications.
  • Video telephony
  • Office2010 Integration
  • Hotkey for dialing numbers out of any Windows application.
  • Set the status depending on user activity.
  • Switch to a standby PBX if the main PBX is down.
  • Write trace files.

Requirements

PBX

  • myPBX license
  • Reporting installation (for seeing recent calls in the history), although no reporting license is needed (as opposed to V9)

Web browser

  • Current version
  • JavaScript enabled
  • HTML5 XMLHttpRequest (AJAX) enabled
  • HTML5 Web Storage (DOMStorage) enabled
  • HTML5 Cross-document messaging (postMessage) enabled

If Microsoft's Internet Explorer is used, it must be IE9 or up. Note: The launcher always uses Microsoft Internet Explorer for opening the web application. It does not use the configured standard browser.

The chat does not work in Safari on iPhone/iPad. This is because the browser does not support applications running in multiple windows.

Launcher

  • Windows 7 or higher
  • .NET 4

Email addresses

myPBX builds an email address of a user using the Name (h323 LDAP attribute) of the user and the System Name of the PBX.
So if the System Name is innovaphone.com and the Name of the user is test, the resulting email address is test@innovaphone.com.
So for every user an email address with this combination should exist.
If your Name in the PBX does not match the user part of your email or the System Name does not match your email domain, then you must populate the E-Mail field in your User objects. You can do this manually or using LDAP replication (see below).
This email address should be the primary SMTP address in your Exchange Server.
If this can't be done, make sure, that there is a SIP address on your Exchange user, which matches this email address.

See Reference7:Configure_Active_Directory_Replication#Notes_on_replicating_the_new-in-V10_email_User_Attribute for details on replicating the email attribute from Active Directory.

Related technology

Configuration

PBX

Basic configuration

  • Make sure you have installed the appropriate licenses.
    • myPBX for the web application.
    • Video for video telephony.
  • Activate the licenses for the inidiviual user objects (License tab). This can also be done using config templates.
  • Enable myPBX on the page PBX/Config/myPBX.
  • To support the dynamic creation of 3rd party application sharing sessions, configure Application Sharing in PBX/Config/myPBX
  • To support call lists at the client, configure the Call List Service in PBX/Config/myPBX

Additional hints

  • Only users with a password can login to myPBX.
  • There should be a dedicated device configured at the user object for each phone registration.
  • To use mobile phones, the mobility device must have a name in the fork config at the user object.
  • The LDAP configuration is taken from the phone config at the user object.
  • The dialling location has to be configured at the phone config of the user object.
  • Phones should be registered using the PBX password so that user can change their login password without affecting the phone registrations.
  • If federation is used ("use as domain" checked), the user names and the PBX system name should match the email addresses of people.

Launcher

Basic configuration

Deployment

  • Administrators can specify a default configuration using MSI parameters when deploying the software.
    • URL - The primary URL.
    • URL2 - The secondary URL (standby PBX).
    • TRACE - Write trace files (true or false).
    • OFFICETRACE - Enable Office Presence Logging (true or false).
    • AUTOSTART - Autostart myPBX (true or false).
    • AUTOAPPEAROFFLINE - Detect user activity on the computer in order to set the IM status (true or false, or the number of minutes).
    • APPNAME - The display name of the external application.
    • APPPATH - The path to the executable or the URI of the external application (may contain placeholders).
    • APPPARAMS - The command line parameters for the external application (may contain placeholders).
    • APPAUTOSTART - Start automatically on call.
  • Additional parameters from V10 SR3:
    • SHOWINTASKBAR - Show the myPBX launcher in the Windows Task Bar (true or false).
    • STARTMINIMIZED - Start the myPBX launcher minimized (true or false).
    • DOCKING - The docking mode of the launcher window (none or left or right).
    • HOTKEY - The hotkey number (see registry of configured launcher).
    • HOTKEYMOD - The hotkey modifier number (see registry of configured launcher).
    • HOTKEYACTION - (copy or show).
    • VIDEO - Enable video telephony(true or false).
    • VIDEOACTIVE - If active the default call type is Audio-video, otherwise it is Audio (true or false).
    • VIDEOPROXY - Proxy server for the video websocket connection.
    • NOTIFICATIONS - Turns desktop notification on or off (true or false).
    • SOUNDS - Turns notification sounds on or off (true or false).
    • LANG - A two-letter language code.
  • Additional parameters from V10 SR6:
    • OFFICEPROVIDER - Set office presence provider (default myPBX, empty string none, otherwise e.g. Communicator).
  • Additional parameters from V10 SR7:
    • OFFICEPRESENCE - false: removes the office presence provider feature from myPBX (default true, true or false).

Command line parameters

  • The following command line parameters can be used to specify special options for running the launcher. For example the parameters are useful for starting many instances on the same computer for demonstration purposes.
    • /url [URL] - Overrides the URL from the configuration
    • /user [USER NAME] - Starts the web application with the given user name
    • /password [PASSWORD] - Starts the web application with the given password
    • /multi - This parameter is for testing purposes, only. Do not use in a productive environment. It allows to start multiple instances of the launcher. You may want to combine this option with other configuration options such as /url to use different configurations without the need to re-configure. The parameter also disables saving the configuration to the registry. So changing the configuration in the configuration dialog does not work.

Type of Service (ToS)

Registry Paths

myPBX stores its settings at the following locations:

  • HKEY_LOCAL_MACHINE\Software\innovaphone\myPBX
  • HKEY_CURRENT_USER\Software\innovaphone\myPBX

Note: The acutal location where windows stores the settings may vary due to windows conventions and settings.

See also: Reference10:Concept_myPBX_Office2010_Integration#Outlook_doesn.27t_recognize_myPBX_as_presence_provider

Web application

When started in a web browser, the following URL parameters can be used to do a basic configuration.

  • lang=fr - Give a two-letter language code to change the language of the user interface
  • touch=false - Loads the version for use with mouse and keyboard.
  • touch=true - Loads the version for touch devices.

Details

Login

  • The short name (H.323-ID) of the user object is used as the login user name.
  • The password of the user object is used as the login password.
  • Users without a password cannot use myPBX.
  • The local session information is stored in the DOMStorage of the web browser. It is deleted when the user logs out.

In a multi PBX scenario myPBX must be connected to the same PBX as the phone. Therefore after login the user is redirected like follows:

  • PBXes accept the login if they are in charge.
  • Slaves redirect to the master if they are not in charge.
  • The master redirects to the slave that is in charge.
  • Inactive standby PBXes redirect to the master.
  • Active standby PBXes accept the login.

Additionally you can configure an alternative URL in the myPBX launcher that shall be used when myPBX can't connect to the primary URL.

Devices

The different phones of the user are addressed by the device of the user object where they are registered at. Therefore there should be no more than a single registration per device. Mobile phones can be integrated using the mobility object. It is mandatory that the mobility has a device name in the fork configuration.

SIP URIs

  • The use as domain checkmark on the page PBX/Config/General enables addressing users across PBXes using SIP URIs.
    • The system name of the PBX is used as the domain-part.
    • The short name (H.323-ID) of the user object is used as the local-part.
  • The constructed URI looks like an email address (user@example.com) and it should only contain characters that would also be allowed for email addresses.
  • In myPBX the URI can be used for telephony and instant messaging. For local users the domain-part can be omitted (user instead of user@example.com).

Presence

  • In the innovaphone PBX there are different possible sources of user presence, called contacts.
    • tel: - Phone presence
    • calendar: - Presence set by the Exchange Calendar Connector
  • myPBX sets the presence for the tel: contact.
  • The displayed user presence is a mixed presence that is derived from the indiviual presence sources by the PBX. It consists of the following information:
    • Acitivty (available, away, busy, lunch, vacation, dnd)
    • Note
    • Phone status (open or closed, sometimes displayed as online or offline)
    • IM status (open or closed, sometimes displayed as online or offline)
  • The activity dnd (do not distrurb) has a special meaning. If it is set, myPBX rejects all incoming chat messages. The phones can also be configured to reject incoming calls, if dnd is set.

Visibility

For presence and dialog monitoring access rights (visibility rules) have to be configured at the individual user objects. The admin can do that in the "Access" dialog. Templates can be used to configure rights at many user objects at a time. In myPBX users can change the values given by the administrator and add their own rules.


Rules refer to

  • A user (by name, alice or alice@example.com).
  • All users of a domain (by domain suffix, @example.com).
  • or all active users of a group (by group name). Group rules can only be added by the administrator.


Rules turn the following rights on or off

  • Online status (phone and IM status, see chapter Presence)
  • Presence (activity and note, see chapter Presence)
  • Busy state (if the user has phone calls or not)
  • IDs (the remote name and number of phone calls)


If a user is member of a group, all active members of that group have implicit access rights. These rights can be configured as the "Group Default Visibility" at the PBX. If there is no matching rule (implicit or explicit) the monitoring party does not see any information.

Administrators should configure default visibility rules that match the companies privacy policy. Typical users should not have to change the visibility settings. It is recommended to use a template that defines at least a rule for the local domain. If users shall be able to configure the visibility for certain groups, a default rule for each of that groups should also be added.

Favourites

The user can add up to 32 phone numbers or SIP URIs as favourites. The favourites appear in myPBX for quick access. Also the presence and the calls are monitored and displayed, if possible. The user can create multiple lists of favourites and switch between them.

Directory search

Users can search for phone numbers and other information in an internal and an external LDAP directory. The directories are configured in the phone config that is stored at the user object in the PBX. Templates can be used to share the same configuration across multiple users.

The directory is also used for resolving the names of external callers.

Some LDAP servers do not return any results if non-existing name or number attributes are configured. Attribute names are case sensitive.

The search results from the internal and external directory are merged by myPBX. The results that have the same phone numbers or H.323 IDs are grouped together to one entry/person.

Instant messaging

myPBX is a chat client that can handle live chats between users. The PBX does not store chat messages, so both users have to be online at the same time.

Chat conferences can be started by adding more people. In this case received text messages are relayed to the other participants. Also the list of participants is transmitted to each endpoint.

Application sharing

The user can start a meeting in an external application sharing solution from a chat session. myPBX connects to the application sharing service using an HTTP interface and creates the meeting. If that was successful it sends links for joining the meeting to the participants of the chat session.

Currently we support Microsoft Office LiveMeeting and WebEx. Alternatively you can configure static meeting URLs.

History

The history shows recent calls.

The calls are retrieved from an instance of the innovaphone Reporting service. The call details include the call flow before and after the user was connected. When a user calls someone back from the history, the call is marked as answered in the reporting database. As this is done using the conference ID of the call even other users can see who called back at what time.

Mypbx history.png

The web client gets the history directly from the innovaphone Reporting service using AJAX. If myPBX is connected to the PBX using HTTPS, also HTTPS is used for the connection to the reporting. Same for HTTP.

Tracing and logging

myPBX can write session information to the syslog of the PBX. Check the "myPBX" checkmark on the page Maintenance/Diagnostics/Logging in order to turn it on.

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

Interfaces for integration

The myPBX launcher has a number of generic interfaces that can be used to integrate it with other applications.

Protocol handlers

myPBX supports the following protocol handlers:

  • tel
  • sip
  • sips
  • phone
  • im

im starts a chat session, the others a call.

The protocol handlers are registered on the installation of myPBX. They can be invoked by links in a browser or in Excel, as windows link or from a command line etc.
E.g. you can create a browser shortcut to im:test, which will start a chat session with test.
From the command line you can call start im:test, within excel, you simple use tel:012345 etc.

Hotkey

A hotkey can be configured that copies selected phone numbers from most applications to myPBX. This can be used for dialing, call transfer and so on.

Starting an external application for a call

myPBX can start an external application for a call. Both web applications and applications that are installed on the client PC can be configured. This configuration can be done in the launcher in the tab "External application" or using MSI parameters during installation.

The following settings can be done:

  • Name - The name of the application as it should appear in myPBX.
  • Path - The path of the applicaiton. This can be an URL (http://crm.example.com/customer-by-number/$n) or the path to a local application (C:\crm\application.exe).
  • Parameters - The command line parameters of the application. This field can be left empty for web applications.

The Path and the Parameters may contain placeholders that are replaced by phone call information.

  • $n - phone number of the remote party as seen
  • $N - phone number of the remote party, normalized to national number format, e.g. 070317300988 (from v10sr8)
  • $I - phone number of the remote party, normalized to international number format, e.g. +4970317300988 (from v10sr8)
  • $u - uri of the remote party
  • $d - display name of the remote party
  • $c - conference ID (a global ID for the call)

If Name and Path are configured, an additional button will appear in myPBX at phone calls that starts the application.

If we configure the flag "Start on call" the External Application will be triggered/open when the call it's connected (incoming or outgoing calls). If we don't check this flag then only when we push the additional button the External Application will be launched.

Troubleshooting

Connection problems / Refreshes

Symptom: When in idle state, the myPBX web application reloads every 30 seconds.
This might be a problem with the TCP/IP settings of the PC. You should set ReceiveTimeOut and KeepAliveTimeout to the default settings if they have been changed to smaller values. Please note that the values must be specified in milliseconds!

Loss of DOM Storage Information

Symptom: myPBX is asking for username and password each time it is started.
See Howto:MyPBX and roaming Profiles (e.g. Citrix) - myPBX forgetting login info for a possible resolution.

Appendix

Known Issues

Office application crashes

If you have Lync/Skype for Business installed and installed myPBX afterwards and you wanted to use Lync/Communicator as Office presence provider, an office application might have crashed.
The MSI parameter OFFICEPRESENCE allows you to disable all office presence related installation, so a Lync installation won't be broken. You can't use myPBX as presence provider anymore in this case, but Lync will still work correctly.
If your installation is already broken, you can simply repair your Lync installation and Office won't crash anymore.

If you want to use myPBX as presence provider, reinstall myPBX without the MSI parameter and uninstall Lync/Skype for Business.

Using the Hotkey while marking a number in a citrix application

If your myPBX Launcher is installed locally and you mark a number in an application in a terminal server client window (e.g. citrix), your myPBX will get into focus but the number won’t be transmitted. This is a known problem. You need to use CTRL+C & CTRL+V.

CPU usage

Connected myPBX sessions need additional resources on the PBX. When all extensions die myPBX, you can have approximately a 1/3 the amount of users per box than without using it.

Network traffic

In idle state the web application needs an empty message exchange every 30 seconds in order to keep the session alive. This messages take about 800 bytes. So per session the minimum network traffic is approximately:

  • 1600 B/min
  • 94 kB/h
  • 2.2 MB/d

Included open source software

The myPBX web application contains the following open source software:

rc4.js

  * RC4 symmetric cipher encryption/decryption
  * Copyright (c) 2006 by Ali Farhadi.
  * released under the terms of the Gnu Public License.
  * see the GPL for details.
  *
  * Email: ali[at]farhadi[dot]ir
  * Website: http://farhadi.ir/

sha1.js

  *  Secure Hash Algorithm (SHA1)
  *  http://www.webtoolkit.info/