Reference12r2:Concept myPBX

From innovaphone-wiki

Revision as of 17:01, 11 July 2018 by Afi (Talk | contribs)
Jump to: navigation, search
There are other versions of this article: Reference9 | Reference10 | Reference11r1 | Reference12r1 | Reference12r2 (this version)

Contents

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.

Image:Mypbx_overview.png

The web application also includes a WebRTC Softwarephone that works with some browsers.

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
  • Application sharing
  • Office 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)

Launcher

  • Windows 7 32bit/64bit or higher
  • .NET 4.5.2
  • Microsoft Visual C++ 2013 Redistributable (x86)

Web browser

If the myPBX is started inside the launcher, an embedded browser is used, so there are no special requirements.

If myPBX is started in a web browser that is installed on the local system, the browser must fulfill the following requirements:

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

Note: For IE the minimum supported version is IE 10.

Email addresses

myPBX builds an email address of a user with the name (H323) and the System Name of the PBX.
So if the System Name is innovaphone.com and the name (H323) 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.

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 Reference12r2: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

Features

For a feature overview refer to myPBX derivates and features.

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 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

myPBX supports various MSI parameters which can be modified using Microsoft's Orca tool for individually tailored deployment (see the respective Microsoft Knowledge Base Article for details on using Orca). You can then roll-out myPBX using your favourite software deployment tool (or, if you don't have one, using Windows Policies, see this Microsoft Microsoft Knowledge Base Article on Group Policies for details).

Basic configuration

  • The configuration dialog is located in the context menu of the tray icon.
  • Configure the URL in the myPBX tab (e.g. http://x.x.x.x/PBX0/MY/client.htm).
  • From v10 beta1 to beta4 the URL was http://x.x.x.x/PBX0/MY/mypbx10.htm. From v10 beta5 the normal URL (client.htm) is used.

Deployment

  • Administrators can specify a default configuration using MSI parameters within the table Property 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 and application sharing (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).
  • Additional parameters from V11:
    • SOFTWAREPHONEAUTOSTART - If "true", the Softwarephone will be started and stopped together with myPBX. Also, the PBX and User Parameters (GK IP-Address, GK-ID, Username and Password) are copied from the myPBX Client into the SoftwarePhone (true or false).
  • Additional parameters from 12r2:
    • CONFIGHIDEMASK - With that parameter the administrator can hide certain parts of the configuration dialog. To calculate the hide mask add the desired values:
      • 1 - Tab "myPBX"
      • 4 - Tab "Office integration"
      • 8 - Tab "Video and application sharing"
      • 16 - Tab "External application"
      • 32 - Link "Open trace folder"
      • 64 - Tab "Softwarephone" (from 12r2 Service Release 14)
    • DEFAULTUSERNAME - The default username for the login
    • DEFAULTPASSWORD - The default password for the login
    • DEVTOOLS - If "true", the context menu of the browser will show the "Inspect element" function that opens the developer tools.
    • OUTLOOKCONTACTSEARCH - If "true", the search for outlook is set.
  • Additional parameters from 12r2 SR11:
    • SOFTWAREPHONEDEVICEPOSTFIX - This postfix will be appended to the user name to determine the registration device for the softwarephone (using the autostart softwarephone feature).

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.
  • phys=location - Forces the PBX to assume the physical location of the WebRTC client used in this instance has the specified physical location

Details

Login

PBX stored password

  • 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.
Note: redirection requires previous authentication. The user must be known to the redirecting slave PBX thus.
  • 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.

Netlogon

See Reference12r1:Concept_Netlogon_and_myPBX_Windows_Authentication

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.

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.

Smileys

myPBX displays emoticons in the text of chat messages as smileys. Here are the text codes that are supported.

 Image:Emo happy.png happy      :-)    :)    (-:    (:
 Image:Emo normal.png normal     :-|    :|    |-:    |:
 Image:Emo sad.png sad        :-(    :(    )-:    ):
 Image:Emo mixed.png mixed      :-/    :/    :-\    :\    \-:    \:
 Image:Emo twinkle.png twinkle    ;-)    ;)    (-;    (;
 Image:Emo lol.png lol        :-D    :D 
 Image:Emo tongue.png tongue     :-p    :p    :-P    :P    q:    q-:

Typing indications

myPBX transmits a notification when a user is typing a chat message. This can be seen by the other participants of the chat session.

Starting a related phone call

If there is a single other participant in a chat session, the chat windows shows a call button to start a phone call to the other person. The call button is hidden if the own phone is not registered.

Application sharing

Support for external application sharing is deprecated, since we now have integrated Application sharing in the myPBX launcher.

Apps

From v12r2 there is a new Home button. It opens a new third area (in addition to the buddies and call history) where is possible to start PBX apps.

PBX apps available in v12r2:

  • Boolean (activation, deactivation, timer)
  • Conference (caller list, mute, exclusive speakermode, disconnect participants)
  • User Settings for dynamic group membership

For configuration refer to object specific reference articles.

Activation

  • Restart myPBX
  • select home symbol at bottom
  • select right sided pen
  • select apps to be used & store settings

Image:Mypbx_activate_apps.png

History

The history shows recent calls. The calls are retrieved from an instance of the innovaphone Reporting service or alternatively the local call list 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.

When using innovaphone Reporting history shows the last 20 calls that were made and when we click in the "arrow" button the next 20 calls are appended to the list, if we use the local call list service the number calls displayed it's set on the configuration menu.

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

During installation myPBX registers protocol handlers for the following URI types:

tel
start a phone call
sip
start a phone call
sips
start a phone call
phone
start a phone call
im
start a chat

They can be used to start calls and chats in myPBX from external applications.

Dialing from the Windows command prompt

Execute the following command to dial the number 012345.

 start tel:012345

Execute the following command to call user@example.com.

 start sip:user@example.com

Execute the following command to start a chat with user@example.com

 start im:user@example.com

Dialing from a web page

This HTML link dials the number 012345, when clicked.

 <a href="tel:012345">012345</a>

This HTML link calls user@example.com, when clicked.

 <a href="sip:user@example.com">user@example.com</a>

This HTML link starts a chat with user@example.com, when clicked.

 <a href="im:user@example.com">user@example.com</a>

Hotkey

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

When the hotkey is pressed, myPBX will simulate a CTRL-C key which should instruct the current foreground application to copy whatever is selected in to the Windows clipboard. If the clipboard content changes due to this, myPBX will use it as number-to-dial.

Starting an external application for a call

myPBX can start an external application for an incoming 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 application. 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 caller as seen
  • $N - phone number of the caller, normalized to national number format, e.g. 070317300988
  • $I - phone number of the caller, normalized to international number format, e.g. +4970317300988
  • $u - uri of the caller
  • $d - display name of the caller
  • $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.

Handling 64-bit applications

Since myPBX Launcher itself is a 32-bit process, if executed on 64-bit Windows, it will run in a WOW64 emulator. This should be considered if a 64-bit application should be started by the launcher.

E.g. the cmd.exe referenced by %WINDIR%\system32 will be a 32-bit version. In case a 64-bit version should be started, a special path %windir%\sysnative should be used instead.

Some applications, like curl.exe which is delivered with windows are only available in 64-bit version, therefore can only be reached via the path %windir%\sysnative\curl.exe.

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 Limitations

WebRTC and Headset

Since V12r2, myPBX allow to use WebRTC technology as softwarephone client. In this case, audio and thus headset handling is done by the browser. Please note that headset physical buttons and its functions such as "onhook/offhook" will not be supported by the browser and hence not by myPBX running the WebRTC endpoint.

Softwarephone Autostart with long password will not work

If the "Start Softwarephone" function it's enabled, the use of passwords with length higher than 12 characters will result in failure to start the softwarephone application since the command used by the launcher to run the softwarephone application will be too long and not accepted.

Solution: If this feature it's enabled set password policy where passwords of myPBX passwords should not be longer than 12 characters.

Known Issues

Office application crashes

If you have Lync 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.

Update: Latest hotfix (November 2017) for SFB/Lync client fixes the issue of the crash with the Outlook-Plugin or issues with the search on the Lync client, so with this newer version both CTI clients could be installed on the same PC without problems.

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/

Related Documentation

Personal tools