EasyCall Gateway - Citrix Product Documentation

EasyCall Gateway - Citrix Product Documentation
EasyCall Gateway
© 2012 Citrix Systems, Inc. All rights reserved. Terms of Use | Trademarks | Privacy Statement
Contents
EasyCall Gateway
5
EasyCall Gateway 3.0.1
EasyCall Gateway 3.0.1
8
ReadMe for EasyCall Gateway 3.0.1
10
Overview
14
About EasyCall
15
Call Flow
19
Licensing
20
Capacity Guidelines
21
Telephone System Requirements and Integration
23
Getting Started
24
EasyCall Gateway Pre-Installation Checklist
25
Implementation Summary
32
To install the virtual appliance
33
To complete the initial configuration
35
About Firewall Configuration
36
Configuring and Testing Basic Settings
37
To define the properties of a trunk
38
To configure a directory source
39
To install the EasyCall plug-in
41
To test your EasyCall implementation
42
Configuration Task List
43
Configuring Network Settings
2
6
44
To open the administration tool
45
To configure the network interface
46
Configuring Name Service Information
47
Obtaining and Importing SSL Certificates
48
Working with a Certificate Authority
49
To obtain an SSL certificate
50
To import certificates
51
Configuring Authentication
52
About Authentication
53
About the Authentication Script
54
Changing and Testing the Script
56
Configuring Telephony Settings
To define the trunk type and connection
59
To configure call handling
60
To specify the caller ID defaults
62
To configure Call Forwarding
63
Configuring Net Call
64
Configuring EasyCall Voice Prompts
66
Customizing Telephone Number Recognition
68
About EasyCall Number Recognition
69
About EasyCall Number Manipulation
71
The Customization Process
72
Number Recognition Customization Options
73
Unsupported Number Patterns and Dialing Provisions
76
Configuring Directory Sources
78
To add a group
80
To configure an LDAP/AD directory source
81
Managing Directory Sources
85
Looking up Attributes in Your LDAP Directory
86
CSV File Requirements
88
To configure a CSV file as a directory source
90
To configure a custom script for directory sources
92
Viewing User Information
93
Clustering EasyCall Gateways
94
About Clusters
95
Pre-Requisites for Clustering
97
To connect a member node to a master node
98
Working with a Cluster
100
Working with a Member Node
101
To disconnect a member node from a cluster
102
To promote a member node to a master node
103
Delivering EasyCall to End Users
Deploying with Citrix Receiver
3
58
104
105
Deploying with Citrix Application Streaming
106
Deploying with Citrix XenApp Publishing or XenDesktop
108
Supporting Users Who Install from a Download Page
109
Deploying via Push Installation
110
Managing EasyCall Conferences
Controlling Access to Conference Creation
112
To specify the URL used for conference pages
113
To configure a conference dial-in number
114
To limit the conference activity per node
115
To delete conference calls
116
Maintaining and Monitoring the EasyCall Gateway
117
To change the root administrator password
118
To set the date and time
119
To back up or restore the configuration
120
To upgrade EasyCall
121
To restart or shut down the EasyCall Gateway
125
To export or delete CDRs
126
To get information about the EasyCall Gateway
129
To use network diagnostic tools
131
Working with the Call and System Logs
132
Using the Web Services API to Build Web Apps
4
111
133
EasyCall Web Services
134
Data Types Available to Web Services APIs
136
Versioning API
139
Authentication API
141
Telephony Client API
146
Call Detail Record (CDR) API
149
Directory API
152
Locations API
154
Global Properties API
157
WSDLs and Example Code
159
EasyCall Gateway
The Citrix EasyCall Gateway™ powers EasyCall Voice Services, enabling click-to-call
communications within Mac, PC, or Web-based applications from any telephone. The
EasyCall Gateway integrates with your telephone system and corporate directory to provide
the simplest and most intuitive way of enabling click-to-call in any application.
Product documentation is available for the following EasyCall Gateway releases:
●
EasyCall Gateway 3.0.1
Related Citrix Products
The EasyCall Gateway is related to the following Citrix products:
Communications Plug-ins
Receiver
Can’t find what you’re looking for? If you’re looking for documentation for previously
released versions of this product, go to the Citrix Knowledge Center. For a complete list of
links to all product documentation in the Knowledge Center, go to
http://support.citrix.com/productdocs/
5
EasyCall Gateway 3.0.1
The Citrix EasyCall Gateway™ powers EasyCall Voice Services, enabling click-to-call
communications within Mac, PC, or Web-based applications from any telephone. The
EasyCall Gateway integrates with your telephone system and corporate directory to provide
the simplest and most intuitive way of enabling click-to-call in any application.
What's New
EasyCall Gateway 3.0.1 includes the following new options and updates:
●
Different URL for accessing the administration tool: To open the administration tool
●
Different URL for accessing the user portal: To install the EasyCall plug-in
●
Root password restrictions: To change the root administrator password
●
Show caller ID option: To configure an LDAP/AD directory source
●
New client upgrade page: To upgrade EasyCall
●
Client version info on Dashboard: To get information about the EasyCall Gateway
●
SIP re-INVITEs option: To configure call handling
In This Section
Under this node, you will find the following resources for the EasyCall Gateway:
6
ReadMe for EasyCall Gateway
3.0.1
Get information about known issues
Overview
Review conceptual information about the EasyCall
Gateway and EasyCall (communications plug-in)
Getting Started
Install the EasyCall Gateway and perform the minimum
configuration
Configuring Network Settings
Configure the EasyCall Gateway virtual network
interface and name service settings
Obtaining and Importing SSL
Certificates
Obtain SSL certificates from a Certificate Authority and
import them into the EasyCall Gateway
Configuring Authentication
Learn about the authentication script and how to use
the administration tool to work with it
Configuring Telephony Settings
Define trunk connections and configure telephony
settings
EasyCall Gateway 3.0.1
Configuring Directory Sources
Add groups to associate directory sources with roles
and configure directory sources
Clustering EasyCall Gateways
Group EasyCall Gateways to provide high availability,
share resources, and to load-balance
Delivering EasyCall to End
Users
Read about various methods available to deliver the
EasyCall client to end users
Managing EasyCall Conferences
Specify the URLs and dial-in numbers for user access to
conferences and manage conference operation
Maintaining and Monitoring the
EasyCall Gateway
Perform maintenance tasks such as changing the root
password, backing up the configuration, exporting
CDRs, using network diagnostic tools, and viewing logs
Using the Web Services API to
Build Web Apps
Use the EasyCall Web Services APIs to build Web
applications that include click-to-call, conferencing,
and corporate directory searches
Can’t find what you’re looking for? If you’re looking for documentation for previously
released versions of this product, go to the Citrix Knowledge Center. For a complete list of
links to all product documentation in the Knowledge Center, go to
http://support.citrix.com/productdocs/
7
EasyCall Gateway 3.0.1
The Citrix EasyCall Gateway™ powers EasyCall Voice Services, enabling click-to-call
communications within Mac, PC, or Web-based applications from any telephone. The
EasyCall Gateway integrates with your telephone system and corporate directory to provide
the simplest and most intuitive way of enabling click-to-call in any application.
What's New
EasyCall Gateway 3.0.1 includes the following new options and updates:
●
Different URL for accessing the administration tool: To open the administration tool
●
Different URL for accessing the user portal: To install the EasyCall plug-in
●
Root password restrictions: To change the root administrator password
●
Show caller ID option: To configure an LDAP/AD directory source
●
New client upgrade page: To upgrade EasyCall
●
Client version info on Dashboard: To get information about the EasyCall Gateway
●
SIP re-INVITEs option: To configure call handling
In This Section
Under this node, you will find the following resources for the EasyCall Gateway:
8
ReadMe for EasyCall Gateway
3.0.1
Get information about known issues
Overview
Review conceptual information about the EasyCall
Gateway and EasyCall (communications plug-in)
Getting Started
Install the EasyCall Gateway and perform the minimum
configuration
Configuring Network Settings
Configure the EasyCall Gateway virtual network
interface and name service settings
Obtaining and Importing SSL
Certificates
Obtain SSL certificates from a Certificate Authority and
import them into the EasyCall Gateway
Configuring Authentication
Learn about the authentication script and how to use
the administration tool to work with it
Configuring Telephony Settings
Define trunk connections and configure telephony
settings
EasyCall Gateway 3.0.1
Configuring Directory Sources
Add groups to associate directory sources with roles
and configure directory sources
Clustering EasyCall Gateways
Group EasyCall Gateways to provide high availability,
share resources, and to load-balance
Delivering EasyCall to End
Users
Read about various methods available to deliver the
EasyCall client to end users
Managing EasyCall Conferences
Specify the URLs and dial-in numbers for user access to
conferences and manage conference operation
Maintaining and Monitoring the
EasyCall Gateway
Perform maintenance tasks such as changing the root
password, backing up the configuration, exporting
CDRs, using network diagnostic tools, and viewing logs
Using the Web Services API to
Build Web Apps
Use the EasyCall Web Services APIs to build Web
applications that include click-to-call, conferencing,
and corporate directory searches
Can’t find what you’re looking for? If you’re looking for documentation for previously
released versions of this product, go to the Citrix Knowledge Center. For a complete list of
links to all product documentation in the Knowledge Center, go to
http://support.citrix.com/productdocs/
9
ReadMe for EasyCall Gateway 3.0.1
Contents
●
Finding Documentation
●
Getting Support
●
Known Issues
●
Issues Fixed in this Release
Finding Documentation
To access complete and up-to-date product information, go to Citrix eDocs and expand
Technologies > EasyCall Gateway.
To view the EasyCall Gateway online help, click the Help link at the top of each
administration tool page.
Getting Support
Contact your supplier for first-line support. Citrix offers online technical support services on
the Citrix Support Web site. The EasyCall Support page includes links to downloads, the
Citrix Knowledge Center, Citrix Consulting Services, and other useful support pages. You
can also purchase Citrix EasyCall Preferred Support.
Our support forum also is a good source of information.
Deploying the communications plug-in for Windows
upgrade
If you do not use Citrix Receiver to deploy the communications plug-in for Windows, there
is an issue with the automatic upgrade that prevents the upgrade on user computers. To
avoid the issue, use the following steps to upload the communications plug-in for Windows
upgrade to the EasyCall Gateway:
1. Upgrade the EasyCall Gateway.
2. Go to the Maintenance > Clients page and browse to the upgrade file.
10
ReadMe for EasyCall Gateway 3.0.1
3. Enter "3.1" in the Client Version Number field. You must enter "3.1" for the upgrade to
work properly.
The next time users connect to the EasyCall Gateway, they will be prompted to
upgrade.
If your users need to upgrade EasyCall themselves, instructions are in the ReadMe for
Communications Plug-in 3.0.1 for Mac and ReadMe for Communications Plug-in 3.0.1 for
Windows.
Known Issues
Download page does not work in Windows Vista if UAC is enabled
When using Windows Vista, the EasyCall Download page does not work in Internet Explorer 7
if User Account Control (UAC) is enabled. [5817]
Cannot install EasyCall from a streamed browser
If you run Outlook via application streaming and click a link in an email to install EasyCall,
the Download page opens in a browser window that is streamed and does not allow you to
complete the installation. [6260]
EasyCall streaming requirement
To stream EasyCall using XenApp Plugin for Streamed Apps 1.2, you must first install the
Microsoft Visual C++ 2008 Redistributable Package on client devices. This redistributable is
available from the Microsoft Visual Studio Web site.
Must save before first test of an FTP CSV source connection
When you initially configure an FTP CSV source, you must click Save before testing the
connection. Otherwise, the source will not be automatically synchronized. [6893]
Cannot use multiple search filters to limit imported entries
On the Directory Source Configuration > Details Configuration page, entering multiple
search filters in the Search Filter field causes the synchronization to fail. When this occurs,
the system log will include the entry: "Missing attribute description (87) Filter Error". [7521]
Add/Edit Group interface does not catch all errors
The Add/Edit Group interface allows you to create a group with no name or that has no
roles. Neither of those conditions should be allowed. Also, if you press Return instead of
clicking Submit from the Add/Edit Roles page, it appears that your input was not submitted
(all fields are blank when the page refreshes), although the role was added or changed.
[7049]
Joining Conference page message always prompts to press 1 to continue call
Regardless of the Prompt to Complete Call checkbox setting, the Joining Conference page
that appears when you dial into a conference always prompts you to press 1 to join the call.
[7472]
11
ReadMe for EasyCall Gateway 3.0.1
User changes to locations are not applied to corresponding Call Forwarding rules
If a user creates a location, adds it to the Call Forwarding locations, and then changes the
location name, calls continue to be redirected to the old location and thus the call fails.
[7261]
Issue with locations created when master node is off-line
If you create multiple locations while the master node is off-line, only the first location
created is sent to the master when it comes back on-line. [6655]
Conferences created when master node is off-line are not submitted
If you create a conference while the master node is off-line, the new conference is not
submitted to the master node when it comes back on-line. [6633]
After logging out of or exiting from the User Portal, an immediate log-in attempt fails
After you exit from the User Portal, immediately attempting to log back in to the portal will
fail. Wait at least one minute before logging back in. [7369]
The Call Log shows "In progress" as the end time for some calls
If a trunk setting in the EasyCall Gateway configuration is incorrect, the end time for calls
is shown as "In progress". [6320]
When the EasyCall Gateway is restarted, any active calls will be shown as "In progress" from
that point on. [7487]
Node certificates are not included in backups
Certificates that you have uploaded to cluster nodes are not included in backups performed
from the master node. If you need to restore a node, you will need to reimport any custom
certificates from each node. [6862]
Time server configuration no longer necessary
Now that the EasyCall Gateway is delivered as a virtual appliance, it is no longer necessary
to manually configure the time server. Any manual configuration is overwritten when the
host server synchronizes its clock with the EasyCall Gateway. [7383]
Server uptime for master node is incorrect
The Dashboard page for the master node shows the server uptime for the last node to join
or rejoin the cluster, rather than for the master node. [6640]
Node version on Dashboard page is slow to refresh
The Dashboard might not show the correct node version for a couple of minutes after you
first display the page. During that time you will see a message: Unable to retrieve current
version. [6626]
Advancing the gateway time logs you out of the administration tool
Changing the gateway time too far into the future causes the session to expire and thus logs
you out of the administration tool. [5744]
12
ReadMe for EasyCall Gateway 3.0.1
Tabbing in online help moves focus to unused frames
The online Help for the administration tool and the Windows EasyCall client include unused
frames which, when you are tabbing around in Help, make it appear that the focus is not
moving. [7133]
Issues Fixed in this Release
The following issues were fixed since the last release.
13
●
Administration tool root password needs to be more restrictive [6819]
●
User Management page does not list users in alphabetical order [7240]
●
On the User Management page, clicking in the Last Name field does not cause the
Directory Search button to automatically select [7522]
●
Upload of NormalizerConfig.xml alone does not update database [7468]
●
Need SIP Re-INVITEs option in administration tool [7513]
●
Show the Caller ID of Restricted Users option is missing [7517]
●
Call log does not display calls in sequential order [7542]
●
User Portal URL is hard for users to remember (Note: The User Portal URL is now
https://gatewayAddress and the Administration Tool URL is now
https://gatewayAddress/admin.) [7545]
●
EasyCall is never automatically upgraded; the Check for Upgrade command does not
work [7548]
●
EasyCall download page does not show the correct Mac OS versions [7553]
Overview
EasyCall is an easy to implement and manage solution that communication-enables
enterprise applications. The EasyCall plug-in (also known as the communications plug-in) is
streamed to or installed on user desktops, providing communication features in Windows
and Macintosh applications. In addition, the EasyCall Web Services API can be used to
communication-enable Web applications.
These topics describe the EasyCall Gateway and EasyCall (communications) plug-in:
14
About EasyCall
How EasyCall works; its features
Call Flow
How a call is processed when a user initiates it using
EasyCall
Licensing
How EasyCall is licensed
Capacity Guidelines
Guidelines for implementing multiple EasyCall Gateways;
how capacity is impacted by usage
About EasyCall
The EasyCall Gateway is implemented as an adjunct to the corporate telephony system, as
shown in the following illustration. The EasyCall Gateway is provided as a virtual appliance
that installs on Citrix XenServer 5.
EasyCall enables a user to call any phone
number displayed in published, streamed, or
installed Windows or Macintosh applications
without dialing the number. The user simply
hovers the mouse pointer over telephone
numbers in application windows and then clicks
a button to start the call from any telephone (office, mobile, home, and so on).
The EasyCall Gateway calls the user’s telephone first, dials the clicked-on number, and
then connects the two calls. The EasyCall Directory feature provides access to corporate
directories and Outlook contacts, from which users can click-to-call their colleagues. The
EasyCall conference feature enables users to set up and join web-based conference calls
hosted on the EasyCall Gateway.
15
About EasyCall
EasyCall Gateway Features
16
●
Leverages your telephony system infrastructure and PSTN connectivity by integrating
with the telephony system via SIP trunking. SIP trunking is used with an IP-enabled
telephony system.
●
Originates calls from the company’s telephony system so that voice traffic remains
on-network and uses least-cost routing to reduce the costs of calls. This is especially
beneficial for international calls.
●
Reduces mobile phone bills because mobile calls are in-bound rather than out-bound.
●
Enables remote users to use home office or mobile phones instead of soft phones for
calls.
●
Customizable call confirmation and call disconnection prompts. Upload your .wav files
to the EasyCall Gateway as described in Configuring EasyCall Voice Prompts.
●
Maintains a record of call details including the originating and called telephone
numbers. You can export Call Detail Records (CDRs) for specified start and end dates
and you can delete all CDRs.
●
Provides an easy-to-use administration tool for configuring network settings, telephony
system integration parameters, and multiple directory sources for use with EasyCall.
Includes a Dashboard that provides usage, status, and system log information.
●
Uses SSL to protect communication with EasyCall and the EasyCall Web Services API.
You can optionally add security by not allowing clients to connect to the EasyCall
Gateway unless they have a signed certificates installed. By default, EasyCall clients
connect without alerts provided that the gateway has a signed certificate.
●
Can be clustered for high availability and load-balanced operation.
About EasyCall
EasyCall (communications) plug-in Features
17
●
Installs through Citrix Receiver, Citrix XenDesktop, or Citrix Application Streaming. Can
also be installed on a user desktop from a download page or via a software management
system.
●
User-friendly download page. End users (who do not obtain the plug-in from other
delivery mechanisms such as Citrix Receiver) can download and install EasyCall from a
download page located on the gateway. The EasyCall Gateway host name and port
number are automatically pre-populated in the configuration dialog box. The download
page also provides access to the EasyCall demo.
●
Makes calling easy by eliminating the need to mentally transfer numbers between a PC
and the phone. For example, there is no need for Contact Center Agents to look away
from sales force or customer relationship applications to dial a call or use a soft phone.
Instead, the Agents can quickly look up a user and click-to-call from the Directory.
●
Enables most telephone numbers that appear in Windows applications to be directly
called. This includes local, long distance, international numbers, and internal
extensions. For more information, see Customizing Telephone Number Recognition.
●
Support for multiple languages, with a fully translated interface and and help system.
Plus EasyCall operates on several international versions of Windows. The Windows
locale determines the language and customizable call prompts used.
●
Features a non-intrusive fade-in phonebar. When a user hovers the mouse pointer over
a phone number, the phonebar is dimmed. The phonebar grows brighter as the user
moves the mouse pointer closer to it. If the user does not want to call a number,
moving the mouse pointer away from the number closes the phonebar.
●
EasyCall also allows a user to type a phone number in the phonebar. This feature is
particularly valuable when calling internationally while away from the office.
●
Allows users to make calls from any phone. You can set up locations for users and also
optionally allow users to create their own locations.
●
Have calls to a user’s corporate extension forwarded to the phone numbers the user has
added to EasyCall. A user can enable/disable Call Forwarding and specify the order in
which phones are dialed.
●
The Net Call feature enables you to eliminate the cost of supporting toll-free numbers
by providing links on internal and external portals to frequently dialed numbers such as
sales and support. Net Call enables any web surfer to take advantage of EasyCall.
●
Enables a user to look up a previously called number and redial the number from a list
of Recent Calls.
●
Includes a Directory feature that displays the corporate directory and Outlook or
Address Book contacts when a user starts typing a name in the directory search bar.
●
Enables a user to change to a different EasyCall Gateway.
●
Optionally provides access to EasyCall Conference, a simple way to create and join
conference calls. Users click a URL to join the conference call, rather than having to
enter a phone number and access code.
About EasyCall
●
Works transparently with IPSec and SSL VPN clients, including the Citrix Access
Gateway.
EasyCall Web Services API Features
Enables web application designers to:
18
●
Make it easier for external users to contact corporate call centers or to provide reach
directory services that improve internal communication.
●
Build click-to-call functions into applications so that users can place calls from any
phone to any phone by clicking a telephone number listed on a web page.
●
Build directory functions into applications so that users can search a corporate
directory for contact information.
●
Develop a web service client that verifies domain/username against an authentication
mechanism.
Call Flow
The following illustration and steps describe the call flow when an EasyCall user initiates a
phone call via click-to-call.
1. When an EasyCall user hovers the mouse pointer over a telephone number displayed on
the desktop and clicks the button in the phonebar, EasyCall sends a click-to-call request
to the EasyCall Gateway. The request includes the caller’s and the destination phone
number.
2. The EasyCall Gateway places an outbound call to the user extension over the SIP trunk.
3. The caller’s phone rings. When the caller answers, the EasyCall Gateway prompts the
user to confirm by pressing “1” to connect. (The administrator can disable the prompt.)
4. The EasyCall Gateway places a call to the outbound number. Call status displays on the
caller’s desktop.
5. The called person answers the phone, thus establishing the talk path. The EasyCall
Gateway then releases itself from the media path by using SIP re-INVITEs to perform
direct media bridging.
19
Licensing
Citrix EasyCall is licensed for use with:
●
XenApp Standard, Advanced, and Platinum Editions
●
XenDesktop Standard, Advanced, and Platinum Editions
●
Netscaler Standard, Enterprise, and Platinum editions
You may install and use the EasyCall Gateway software on an unlimited number of
XenServer virtual appliances. You may install and use the EasyCall communications plug-in
for Windows or Macintosh on an unlimited number of client devices.
20
Capacity Guidelines
The number of EasyCall Gateways needed for a site is based on the user load. You can
cluster multiple EasyCall Gateways to support larger user bases.
Click-to-call originations, directory lookup requests, and conference sessions are the
primary drivers of EasyCall application performance. Based on simulated user traffic load
without conferencing enabled, each EasyCall Gateway instance supports 4,000 users
concurrently connected placing up to 4,000 busy hour calls, while initializing up to 3000
busy hour searches of a directory that can contain up to 200,000 entries with typical
directory searches requiring sub 500 millisecond response times.
With conferencing enabled, traffic capacity depends on the typical number of
simultaneously active conference sessions as follows.
Busy Hour
Conference Sessions
Concurrent Users
Busy Hour Calls
Busy Hour Directory
Searches
0
4000
4000
3000
50 (ten concurrent
conferences with 5
participants each)
4000
4000
3000
Call Capacity Calculations
The number of busy hour calls is further constrained by the number of primary rate SIP
channels configured, as described in this topic. These calculations use the Erlang B model
(service with rejections) to determine the call capacity of an EasyCall Gateway. The
calculation is based on assumptions of the time the EasyCall Gateway spends in the call
path (3 minutes per SIP call), the call arrival rate, and the call rejection rate.
In SIP environments, call capacity depends on the maximum number of SIP virtual channels
configured on the PBX for that trunk.
The calculations in the following table use the Erlang B model and assume a .1% call
rejection rate and a 3-minutes average time on the call per channel before path
replacement. Based on the number of SIP channels provisioned on the PBX, the table shows
the maximum service rate in calls per hour based on the above assumptions.
21
Number of channels
Calls per hour
Erlangs
35
200
20
71
500
50
128
1000
100
238
2000
200
450
4000
400
Capacity Guidelines
Call capacity may also be limited by the call capacity of your PBX system. Contact your PBX
vendor for traffic handling information.
22
Telephone System Requirements and
Integration
The EasyCall Gateway has the following requirements for the telephony system at the
customer site:
●
The telephony system must support SIP (RFC 3261) trunks for call redirection.
●
SIP trunks are virtual digital (IP-based) and require only compliant software.
●
You can configure an EasyCall Gateway with multiple telephony systems, if calls are
handled using round-robin scheduling.
●
In a private network with distributed multiple telephony systems, multiple EasyCall
Gateways can be installed at a central location to serve users at satellite locations.
Work with your telephony system specialist to ensure that the telephony system meets the
requirements and properly integrates with the EasyCall Gateway.
The EasyCall Gateway can be configured for operation with a variety of telephony systems
at the customer site. Each call made through EasyCall appears as two independent calls on
the telephony system, with the from numbers pointing to the opposite call leg, as follows:
●
An entry from the trunk to the call originator. The Caller ID is set to the number that
the call originator is trying to reach.
●
An entry from the trunk to the number the call originator is trying to reach. The Caller
ID is set to the call originator’s phone number. (Depending on configuration, the call
originator might be a default caller ID assigned by the administrator or the caller’s own
caller ID.)
For more information:
23
●
Refer to the EasyCall Gateway Pre-Installation Checklist for the telephony systems
supported by this release.
●
Refer to the Citrix EasyCall Gateway Telephony System Integrator’s Guides for details
on configuring a telephony system for use with the EasyCall Gateway. Go to
http://support.citrix.com/product/cg/ and then click the link for the release. The
integrator's guides are located on the Documentation tab for each release.
Getting Started
These topics describe how to install the EasyCall Gateway and perform the minimum
configuration needed to test its basic operation and connectivity to the communications
plug-in:
24
EasyCall Gateway
Pre-Installation Checklist
Collect the information you need to configure the EasyCall
Gateway; refer to information about inbound and
outbound port usage
Implementation Summary
Review the deployment sequence for the EasyCall Gateway
To install the virtual
appliance
Install the EasyCall Gateway using Citrix XenCenter
To complete the initial
configuration
Connect the EasyCall Gateway virtual appliance to your
network
About Firewall
Configuration
Get the information you need to configure your firewall
Configuring and Testing
Basic Settings
Perform the configuration needed to be able to place a
call using the communications plug-in
Configuration Task List
Refer to this task list to ensure you have fully configured
the EasyCall Gateway before putting it into production
EasyCall Gateway Pre-Installation
Checklist
Overview
This checklist is for EasyCall Gateway administrators. Information for telephony system
integrators is provided in the EasyCall Gateway Telephony System Integrator’s Guides.
Those guides are available from http://support.citrix.com/product/cg (follow the links to
the release and Documentation).
We recommend that you print this checklist and keep it updated and accessible to the
administrator.
Firewall Requirements
The firewall used for the EasyCall Gateway must allow TCP traffic over HTTPS port 443 for
communication with the EasyCall or Web Services API.
The telephony system and the EasyCall Gateway must not be separated by a firewall or
NAT.
Basic Network Connectivity
Interface 1 IP address: _________________________
Subnet mask: _________________________
Default gateway IP address: _________________________
External IP address: _________________________
External port: _________________________
SIP External IP address*: _________________________
SIP local network*: _________________________
DNS server(s): _________________________ _________________________
* Required only by some SIP carriers.
25
EasyCall Gateway Pre-Installation Checklist
EasyCall Gateway Port Usage
The following tables list all of the EasyCall Gateway inbound and outbound ports. These
ports must be open on the EasyCall Gateway’s gateway device (such as a firewall or router).
Gateway Inbound
Ports
Transport Application Purpose
Protocol Protocol
Configurable?
22
TCP
SSH
SSH service
No
123
UDP
NTP
Network Time Protocol
timer service
No
443
TCP
HTTPS
EasyCall to EasyCall
Gateway
No
5060
UDP
SIP
SIP Trunk
Yes
20000 - 20500
UDP
RTP
SIP Trunk
Yes
Gateway Outbound
Ports
Transport Application Purpose
Protocol Protocol
Configurable?
37
TCP
rdate
rdate service
No
43
TCP
whois
whois service
No
53
TCP/UDP
DNS
DNS service
No
123
UDP
NTP
Network Time Protocol
timer service
No
389
TCP
LDAP
LDAP Server connection
Yes
514
UDP
Syslog
Syslog service
No
(depends on the
telephony system)
UDP
SIP
SIP Trunk
Yes
Dynamic range
(depends on the
telephony system)
UDP
RTP
SIP Trunk
Yes
Telephony System
Select the telephony system used at the site:
__ Alcatel OmniPCX Enterprise Version 8.0
__ Alcatel OmniPCX Enterprise Version _____
__ Asterisk (including Trixbox) Version 1.2
__ Asterisk (including Trixbox) Version 1.4
__ Asterisk (including Trixbox) Version _____
__ Avaya S8300 /S87xx-Series with Media Gateway and SIP-Enablement Services (R4.1.31.2)
and Avaya Communication Manager Version 5.0
26
EasyCall Gateway Pre-Installation Checklist
__ Avaya S8300 /S87xx-Series with Media Gateway and SIP-Enablement Services (R4.1.31.2)
and Avaya Communication Manager Version _____
__ Avaya S8300 /S87xx-Series and Avaya Communication Manager Version 3.0
__ Avaya S8300 /S87xx-Series and Avaya Communication Manager Version 4.01
__ Avaya S8300 /S87xx-Series and Avaya Communication Manager Version _____
__ Bandwidth.com
__ Cisco Unified Communications Manager Version 4.1(3)
__ Cisco Unified Communications Manager Version 4.2(3)
__ Cisco Unified Communications Manager Version 5.1
__ Cisco Unified Communications Manager Version 6.0
__ Cisco Unified Communications Manager Version _____
CCM utilizes Call Search Spaces. If configured, use this call space:
_____________________________. For details, please refer to the Telephony System
Integrator’s Guide for Cisco.
__ Cisco CallManager Express Version 3.2
__ Cisco CallManager Express Version 4.0
__ Cisco CallManager Express Version _____
__ Nortel Meridian Series and Nortel Communication Server 1000 Version 5.0
__ Nortel Meridian Series and Nortel Communication Server 1000 Version _____
__ Media Gateway for non-SIP compatible telephony systems: AudioCodes Mediant 1000
__ Media Gateway for non-SIP compatible telephony systems: Other _______________
SIP audio codec is 711ulaw? __ Yes __ No
For SIP connections:
Trunk capacity: _________________________
SIP domain: _________________________
PBX SIP IP address: _________________________
PBX SIP port: (Defaults to 5060.) _________________________
User name and secret: _________________________
Voice mail extension: _________________________
27
EasyCall Gateway Pre-Installation Checklist
Note: SIP carriers have additional requirements. Refer to the Telephony System Integrator’s
Guide for your telephony platform for more information.
Cluster-wide call and conference settings:
External cluster address: _________________________
(The External Cluster Address must be forwarded to a static IP address of one of the cluster
nodes. The node which services the External Cluster Address must have a valid SSL
certificate to avoid certificate warnings from web browsers.)
Default Caller ID: _________________________
Conference Dial-in Number and Extension: _________________________
(The Conference Dial-in Number must be set up from your telephony system so that it
knows how to route all calls to the number to your EasyCall Gateway.)
Maximum Number Per Node of Conferences: _______________
Maximum Number Per Node of Conference Participants: _______________
To make EasyCall conferencing available to users outside of your firewall, configure a Web
proxy to:
__ Forward https requests for EasyCall from external parties to the EasyCall Gateway.
__ Route the client responses back to the external parties.
Call Setting Configuration
__ Use Diversion (Applies to Cisco only.)
__ Use E164 dialing (Applies to SIP carriers only. Remaining fields not used when this option
is selected.)
Country: _________________________
Domestic dial prefix: _______________ (Example "1" for U.S.)
International dial prefix: _______________ (Example "011" for U.S or "00" for U.K.)
Area code: _______________
Trunk access code: _______________ (Example "9" or "0")
Domestic cell prefix: _______________ (Applies to Mexico and Argentina only.)
Domestic carrier code: _______________
International carrier code: _______________
__ Use International carrier code instead of international prefix (Applies to Finland only.)
28
EasyCall Gateway Pre-Installation Checklist
__ Use Open Numbering Plan (Is on by default. In closed numbering plans, there is no
concept of local dialing vs. domestic dialing.)
Call Setting Customization
__ Use additional local area codes or overlays:
Area Code
Local dialing requires the area code?
Domestic prefix?
__ Yes __ No
__ Yes __ No
__ Yes __ No
__ Yes __ No
__ Yes __ No
__ Numbers to be recognized as extensions:
__ Yes __ No
Length of extensions: __ 3-digit __ 4-digit __ 5-digit
Extensions preceded by: __ # __ / __ Ext. __ Ext: __ Other __________
(“Ext” includes all variations of capitalization, such as EXT and ext, and with or without the
end punctuation.)
Extension prefix: __________
For numbers that include alphabetic characters:
__ Allow the following prefixes: _________________________
__ Block access to the following prefixes: _________________________
(By default, in the U.S. EasyCall recognizes numbers with alphabetic characters if they have
the prefixes 800, 866, 877, or 888.)
Dial private network numbers as an:
__ External (On-net number)
__ Internal (Extension)
Number pattern for private network numbers: _________________________
(For example, +NN.NN.NNNN.NNNN, ESN NNN-NNNN, (ESN) NNN-NNNN.)
Interpret a ten-digit number that does not include an international dial prefix as:
__ a domestic number based on the EasyCall Gateway locale
__ a U.S. number regardless of the EasyCall Gateway locale
(Ten-digit numbers can have any pattern defined by:
[punctuation]NNN[punctuation]NNN[punctuation]NNNN.)
__ Additional restricted phone number patterns: _________________________
29
EasyCall Gateway Pre-Installation Checklist
(Patterns already configured include those prefixed by “fax”, “tty”, and currency symbols;
numbers in date/time formats. Example: Service URL
https://server.domain.com/workplace/services/CallDirector)
Directory Source Configuration
You can use multiple sources for the directory information to appear in EasyCall. Print a
copy of this page for each directory source.
LDAP/AD Source
Use this directory as a source for EasyCall users:
__ User domain prefix: _________________________
__ Node name: _________________________
Group roles for this source: __ CALL __ CONFERENCE __ CALL_FORWARD __
CREATE_LOCATIONS
LDAP server IP address and port: _________________________
(LDAP server port defaults to 389. If you use an indexed database, using port 3268 will
significantly speed the LDAP queries.)
LDAP Bind DN and password: _________________________
Example syntax:
"cn=DirectoryManager,o=cisco.com" (Cisco DC Directory)
"ou=administrator,dc=ace,dc=com"
"username" (Active Directory User Principal Name; cannot be email address)
"cn=Administrator,cn=Users,dc=ace,dc=com" (Active Directory)
For Novell eDirectory, the Bind DN user must have access rights to see the properties of the
users.
LDAP Base DN: _________________________
Example syntax:
"ou=Users,o=cisco.com" (Cisco DC Directory)
"ou=Users,dc=ace,dc=com"
"cn=Users,dc=ace,dc=com" (Active Directory)
Search Filter: _________________________
(Defaults to "objectclass=person".)
30
EasyCall Gateway Pre-Installation Checklist
LDAP Attribute fields: (Defaults in parentheses.)
Email Address (mail) ____________________
Username (username) ____________________ Required.
Display Name (cn) ____________________
FirstName (givenName) ____________________
Extension (ipPhone) ____________________
Surname (sn) ____________________
Title (title) ____________________
Department (department) ____________________
Work Phone (telephoneNumber) ____________________
Mobile Phone (mobile) ____________________
Other Phone (homePhone) ____________________
CSV File Download Source
FTP server IP address: _________________________
FTP server username and password: _________________________
CSV file path and filename: _________________________
EasyCall Client Installation
EasyCall installation will be handled through:
__ Citrix Receiver
__ Citrix XenApp Publishing
__ Citrix Application Streaming
__ Citrix XenDesktop
__ User download
__ Microsoft System Management Server
31
Implementation Summary
The following steps summarize the implementation workflow for an EasyCall Gateway, from
initial installation through delivering and testing the communications plug-in. For a
post-implementation task list, see Configuration Task List.
1. Install the EasyCall Gateway using Citrix XenCenter: To install the virtual appliance.
2. Complete initial configuration: To complete the initial configuration.
3. Configure your firewall: About Firewall Configuration.
4. Integrate the telephony system and the EasyCall Gateway. This integration work is
performed by a telephony system specialist (your vendor or an internal resource)
according to the guidelines provided in the EasyCall Gateway Telephony System
Integrator’s Guide specific to your telephony system. The integration can be performed
in tandem with the previous step. Refer to the Citrix EasyCall Gateway Telephony
System Integrator’s Guides for details on configuring a telephony system for use with
the EasyCall Gateway. Go to http://support.citrix.com/product/cg/ and then click the
link for the release. The integrator's guides are located on the Documentation tab for
each release.
5. Configure the EasyCall Gateway using the EasyCall Gateway administration tool: To
define the properties of a trunk, Configuring Telephony Settings, and To configure a
directory source.
6. If needed, cluster the EasyCall Gateways: Clustering EasyCall Gateways.
7. Deliver the communications plug-in: To install the EasyCall plug-in and To test your
EasyCall implementation.
32
To install the virtual appliance
EasyCall Gateway is provided as a virtual appliance which you can install using Citrix
XenCenter for XenServer 5.0 (Express, Standard, Enterprise, or Platinum Edition).
1. The EasyCall Virtual Appliance (.xva) image is available for download from the Citrix
support site. The image name is citrix-ecg-releaseNumber.xva.bz2.
2. Unpack the zip file using 7Zip, WinZip, or another archive utility.
3. Start Citrix XenCenter.
4. In XenCenter, choose File > Import VM.
5. Click Browse, navigate to the .xva file, and click Open.
6. Select Exported VM as the Import Type and then click Next.
7. In the Home server screen of the wizard, select the XenServer instance where this VM
should be imported and then click Next.
8. In the Storage screen, select the XenServer where the storage repository resides and
then click Import. The import will begin and the Network screen appears.
9. In the Network screen, select Network n from Network and then click Next. n will be 0
unless XenServer is installed on a server with multiple networks.
10. In the Finish screen, remove the check mark from Start VM after Import and then click
Finish.
The import progress is displayed in the status bar at the bottom of the XenCenter
window and also on the Logs tab. The import process may take some time, depending
on the size of the VM and the speed and bandwidth of the network connection between
XenCenter and the server where you are installing the new VM.
After the import process completes, you can specify the amount of memory to be
allocated to this VM before starting the VM.
11. Allocate memory to the VM:
a. In the XenCenter window, right-click the VM and choose Properties.
b. Click the Memory and VCPUs tab and choose the amount of memory for the VM. We
recommend a minimum of 2Gb.
c. Optionally change the number of VCPUs.
d. Click OK.
12. Configure the VM for an auto-generated MAC address. (The VM will not function
properly without a unique MAC address.)
33
To install the virtual appliance
a. In the XenCenter window, select the VM and click the Network tab.
b. Click the Properties button and select Auto-generate.
c. Click OK.
13. In the XenCenter window, right-click the VM and choose Start. The VM starts and the
Network Configuration Utility appears.
14. Enter the IP address, netmask, default gateway, and a DNS server and then save those
settings as directed on the screen.
The utility will save network settings and reboot the virtual appliance.
You have now completed the installation and one-time configuration of the EasyCall
Gateway virtual appliance.
After the VM reboots, a message displays the URL you will need for further EasyCall
Gateway configuration.
34
To complete the initial configuration
The following steps describe the required initial configuration.
1. To access the EasyCall Gateway administration tool from your desktop, open a Web
browser and enter https://gatewayAddress/admin, where gatewayAddress is the one
you set in the Network Configuration Utility.
2. Log on to the EasyCall Gateway administration tool: The user name is root and the
default password is rootadmin.
3. Click Cluster Configuration. On the Nodes tab, click the Master node link in the Node
Name column.
4. On the Interfaces tab, set the External IP Address if you have geographically distributed
cluster nodes or if you want to allow individuals outside of your company firewall to
participate in EasyCall conferences.
5. Click Submit.
6. To apply the network settings, click Maintenance > Services and then click Restart.
7. On the Cluster Configuration > Nodes page, click the Activate Node link.
8. Follow these links for information about the next configuration steps:
●
About Firewall Configuration
●
Configuring and Testing Basic Settings
●
Configuration Task List
Note: For the additional configuration required for some SIP carriers, refer to the Citrix
EasyCall Gateway Telephony System Integrator’s Guide for your SIP carrier. Go to
http://support.citrix.com/product/cg/ and then click the link for the release. The
integrator's guides are located on the Documentation tab for each release.
35
About Firewall Configuration
The EasyCall Gateway is deployed inside your firewall. The EasyCall plug-in communicates
with the EasyCall Gateway over port 443. The firewall used for the EasyCall Gateway must
allow TCP traffic over port 443 for communication with EasyCall or the EasyCall Web
Services API. For additional information on port uses and requirements, refer to the
EasyCall Gateway Pre-Installation Checklist.
If SIP trunking is used, the telephony system and the EasyCall Gateway must not be
separated by a firewall.
36
Configuring and Testing Basic Settings
The following topics describe the minimum configuration needed to configure the basic
functionality of the EasyCall Gateway:
To define the properties of a trunk
To configure a directory source
To install the EasyCall plug-in
To test your EasyCall implementation
When you have completed the steps in those topics, you should be able to place a call using
EasyCall.
37
To define the properties of a trunk
If you have questions about the properties of the trunks configured at your site, please
contact the telephony specialist who performed the integration.
1. In the EasyCall Gateway administration tool, click Cluster Configuration and then click
Trunks.
2. Click Add Trunk.
3. On the Add/Edit Trunk page, enter a description in Trunk Name. This name identifies
this trunk in the list on the Trunks tab.
4. In Trunk Capacity, enter the number of channels available to EasyCall. For general
information about capacity, see Capacity Guidelines. Your telephony system specialist
can provide this value.
5. Enter the SIP Switch Settings provided by your telephony specialist. For more
information, see To define the trunk type and connection.
6. Configure call handling so that phone numbers will be dialed correctly from the locale
of the gateway. For details, see To configure call handling“Configuring Call Handling”
on page 55.
7. Click Submit.
38
To configure a directory source
You can configure an unlimited number of directory sources (LDAP/AD directory server, FTP
server, CSV file, or custom script) for display in the EasyCall Directory. Each source is
associated with one Group which defines the roles for users in that directory source. Roles
determine whether users can make calls from EasyCall, create EasyCall conferences, use
Call Forwarding, and create locations.
1. In the EasyCall Gateway administration tool, click Directory Source Configuration.
Notice that in the Groups tab the “All Roles” group is already created for you.
2. If you want to create a role that limits user access to EasyCall features:
a. Click Add Group.
b. Enter a name for the group.
c. Select each EasyCall feature that you want available to users in the group and then
click Submit. Repeat these steps for each role that you want to add.
3. In the Groups tab, specify how you want users handled if their group is deleted and
then click Submit.
4. Click the Directory Sources tab.
5. Under the Configured Directory Sources list, click Add.
6. A directory source is always used to populate the EasyCall Directory. If you also want
the directory source to be used as a source of EasyCall users, select the Use this
directory as a source for EasyCall users checkbox. When you select the checkbox, two
additional fields appear:
●
For User Domain Prefix, enter the domain associated with users in this directory
source. When a user logs in to EasyCall, the user must specify a domain, which is
validated against the domain prefix specified here.
For Node Name, specify the node for which this source is to be used. Defaults to
Any. You would select a specific node if you want this directory source to apply only
to that node and not be available to EasyCall users who are connected to other
nodes in the same cluster.
7. Select the Source Type that you will configure: Directory Server: Configure scheduled
downloads of user information from an LDAP or Active Directory server.
●
FTP Server: Configure scheduled downloads of user information from a CSV file located
on an FTP server.
Uploaded CSV File: Configure scheduled uploads of user information from a CSV file
located on a computer that can be reached from the EasyCall Gateway.
Custom Script: Configure uploads of user information from a custom script.
8. Enter a descriptive Source Name.
39
To configure a directory source
9. Select the Group to be associated with all users obtained from the configured source.
10. Specify the synchronization schedule.
11. Click Next Step and complete the configuration as described in Configuring Directory
Sources.
12. After you have created all of the directory sources, use the Up and Down links in the
Priority column to order the sources. The source at the top of the list has the highest
priority. Information for a user that appears in multiple sources will be handled
according to the Directory Source Setting that you specify (see next step).
13. Specify a Directory Source Setting to determine how users who appear in more than one
directory source are to be handled. You can choose to obtain user information from the
source with the highest priority (which will take precedence over other sources) or to
not overwrite user information during a synchronization so you can review conflicts.
14. To immediately synchronize the EasyCall Gateway with one or more sources, select
each source and click Sync. The EasyCall Gateway will be synchronized with the sources
in the order in which they appear in the Directory Sources tab.
40
To install the EasyCall plug-in
To test the EasyCall implementation, download and install the EasyCall plug-in on a
computer that has network access to the EasyCall Gateway. After you test the EasyCall
implementation and completed configuration, see Delivering EasyCall to End Users.
1. Open the following URL in a Web browser: https://gatewayAddress/download
where gatewayAddress is either the default IP address of the EasyCall Gateway
(10.20.30.40) or the one that you assigned during setup.
2. Click the Download Now button.
EasyCall is downloaded and installed on your computer. However, if you have disabled
JVM or the execution of embedded code, EasyCall is not installed automatically. You
must run the installer manually and respond to a prompt for the EasyCall Gateway host
name.
After EasyCall is installed, it starts automatically when you start Windows. EasyCall
commands are available from the EasyCall notification area icon. Some commands are
also available from the EasyCall User Portal, which you can reach through this address:
https://gatewayAddress. gatewayAddress is either the default IP address of the
EasyCall Gateway (10.20.30.40) or the one that you assigned during setup.
41
To test your EasyCall implementation
For information about using EasyCall, refer to the Help available from the EasyCall client.
1. In a Windows application, open an application or page that contains a phone number.
2. Hover over the phone number. In the phonebar, click the phone icon.
3. Complete the call on your phone. If the number is dialed, you have successfully
deployed EasyCall. Review the table in Configuration Task List for additional tasks that
you might need to complete.
42
Configuration Task List
After you complete the minimum steps needed to install the EasyCall Gateway and test
EasyCall, review the following table for additional configuration tasks.
Configuration Tasks
Change the root administrator password
Change the NTP server used by the gateway or enter a server date and time
Specify Domain Name Servers; add entries to the HOSTS file
Set up SSL certificates
Define additional trunks
Optionally customize EasyCall voice prompts
Customize telephone number recognition
Add groups and directory sources
Configure Call Forwarding
Configure the Net Call feature
Optionally cluster EasyCall Gateways
Back up the system configuration
Deliver EasyCall to end users
43
Configuring Network Settings
After installing the EasyCall Gateway, you can change its network settings provided it is not
part of a cluster.
Note: To apply changes to network settings, you must restart the EasyCall Gateway
(Maintenance > Services).
These topics describe the EasyCall Gateway network configuration settings:
44
To open the administration
tool
Access and log in to the gateway interface
To configure the network
interface
Configure settings such as IP address and net mask for the
virtual network interface
Configuring Name Service
Information
Specify DNS servers or add entries to the HOSTS file
To open the administration tool
The web-based EasyCall Gateway administration tool enables you to configure the gateway
and obtain information about its operation.
1. In a web browser, type https://gatewayAddress/admin. The gatewayAddress is either
the IP address or host name of the EasyCall Gateway.
2. Type the administrator root user name and password. The default credentials are root
and rootadmin. To change the password, see To change the root administrator
password. The EasyCall Gateway Dashboard page opens. For information on the
Dashboard, see To get information about the EasyCall Gateway.
45
To configure the network interface
You connect the EasyCall Gateway to your network using its virtual network interface.
1. In the administration tool, click Cluster Configuration and then click the Nodes tab.
2. Click the node name and complete the fields on the Interfaces tab as described in the
following table. If the fields are not editable, the EasyCall Gateway is part of a cluster.
You must remove it from the cluster to change its settings, as described in To
disconnect a member node from a cluster.
Setting
Description
IP Address
Defaults to 10.20.30.40.
Subnet Mask
Identifies the range of addresses that can be reached
without using a gateway device.
Default Gateway
The IP address of the default gateway device, such as
the main router or firewall. This should be the same as
the default gateway setting that is on computers on
the same subnet.
External IP Address
The external address if the EasyCall Gateway is behind
a Network Address Translation (NAT) device.
External Port
Note: The General tab available from Cluster Configuration > Nodes page applies
only to sites using SIP carriers for telephony services. For information, see the
http://support.citrix.com/product/cg/Citrix EasyCall Gateway Network Integrator’s
Guide for the SIP carrier. (After you follow the link, click the link for the release. The
integrator's guides are located on the Documentation tab for each release.)
3. To apply the network settings, click Maintenance > Services and then click Restart.
46
Configuring Name Service Information
You can specify up to three Domain Name Servers (DNSs) to be used by the EasyCall
Gateway for translation of fully-qualified domain names (FQDNs) to IP addresses. If your
network configuration prevents the EasyCall Gateway from connecting to DNS for address
translations, you can add entries to your HOSTS file via the EasyCall Gateway administration
tool.
When the EasyCall Gateway attempts to translate an FQDN to an IP address, it checks its
HOSTS file before connecting to DNS to perform the address translation. If the EasyCall
Gateway can translate the FQDN to an IP address using the information in the HOSTS file, it
does not use DNS to perform the address translation.
Note: Adding entries to the HOSTS file can optimize performance because the EasyCall
Gateway does not have to connect to a different server to perform the address
translations.
To specify DNS servers or add entries to the HOSTS
file
1. Click Cluster Configuration and then click the Nodes tab.
2. Click the node name, click the DNS/Hosts tab, and complete the fields as described in
the following table. If the fields are not editable, the EasyCall Gateway is part of a
cluster. You must remove it from the cluster to change its settings, as described in To
disconnect a member node from a cluster.
Setting
Description
DNS Server 1 - 3
The IP address of each server.
Host Name / Host IP
Click Add to enter the FQDN and IP address pair to be
added to the HOSTS file.
3. To apply the network settings, click Maintenance > Services and then click Restart.
To change or delete an entry from the HOSTS file
1. Click Cluster Configuration and then click the Nodes tab.
2. Click the node name, click the DNS/Hosts tab.
3. To change an entry, click its host name in the Static Hosts table, change the settings,
and click Submit. To delete an entry, select the checkbox beside its name and click
Delete.
4. To apply the network settings, click Maintenance > Services and then click Restart.
47
Obtaining and Importing SSL Certificates
EasyCall uses Secure Sockets Layer (SSL) certificates to create secure connections between
the EasyCall Gateway and the EasyCall (communications) plug-in. The EasyCall Gateway
includes a temporary certificate. You must replace the temporary certificate to enable
EasyCall to work without security alerts and other errors. You can use the EasyCall Gateway
administration tool to create and import a self-signed certificate, however, when the
EasyCall plug-in attempts to connect the server, the browser will issue certificate alerts.
These topics describe how to obtain and import certificates from a Certificate Authority
and import them into the EasyCall Gateway so that users do not receive certificate alerts:
48
Working with a
Certificate Authority
Learn about working with a Certificate Authority (CA) and what
an SSL certificate obtained from a CA includes
To obtain an SSL
certificate
Generate a self-signed certificate and its associated Certificate
Signing Request
To import certificates
Import the root, intermediate, and server certificates into the
EasyCall Gateway keystore
Working with a Certificate Authority
You can obtain an SSL certificate from either an internal or public Certificate Authority
(CA). Consult your security department to find out the CA required by your company and
the procedure for obtaining server certificates. Instructions for generating server
certificates using various Web server products are available from the Web sites of popular
CAs such as VeriSign.
Obtaining a digital certificate from a public CA involves a verification process in which:
●
Your organization provides corporate or organization information so the CA can verify
that your organization is who it claims to be. The verification process may involve other
departments in your organization, such as accounting, to provide letters of
incorporation or similar legal documents.
●
Individuals with the appropriate authority in your organization are required to sign legal
agreements provided by the CA.
●
The CA verifies your organization as a purchaser; therefore, your purchasing
department is likely to be involved.
●
You provide the CA with contact details of suitable individuals whom they can call if
there are queries.
What the CA Provides
The SSL certificate provided by a CA includes the following:
●
Server certificate
A server certificate certifies the identity of a server.
●
Root certificate
A root certificate identifies the CA that signed the server certificate. The root
certificate belongs to the CA. This type of digital certificate is required by a client
device to verify the server certificate. When establishing a secure connection with a
Web browser on a client device, the server sends its certificate to the client.
●
Intermediate certificate
An intermediate certificate is a certificate that goes between the EasyCall Gateway
(the server certificate) and a root certificate.
49
To obtain an SSL certificate
You must import the root and intermediate certificates into the EasyCall Gateway keystore
before the server certificate.
1. In the administration tool, click Maintenance > Certificates.
2. From the Select an Action list, select Import chain certificate from a certificate
authority.
3. In the Upload Certificate File section, click Browse to locate the chain1.cer file on
your local share.
4. Click Submit to upload the root certificate.
5. The Certificate Status text box displays the following on successful completion:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 5 entries
6. Repeat the process for the intermediate certificate (chain2.cer). Now you are ready to
import the server certificate.
7. From the Select an Action list, select Import certificate from a certificate authority.
8. In the Upload Certificate File section, click Browse to locate the certificate.cer file on
your local share.
9. Click Submit to upload the server certificate.
10. The Certificate Status text box displays the following on successful completion:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 5 entries
11. Restart the EasyCall Gateway.
12. Verify through your browser interface that the certificate installed on the EasyCall
Gateway is signed by the CA who issued it.
50
To import certificates
To obtain an SSL certificate from a certificate authority (CA), you must first use the
EasyCall Gateway administration tool to generate a self-signed certificate and its associated
Certificate Signing Request (CSR) required by the CA. You can then purchase a certificate
from the CA by providing some information including the CSR.
1. In the administration tool, click Maintenance > Certificates.
2. From the Select an Action list, select Generate self-signed certificate.
3. In Common Name, enter the host name for the EasyCall Gateway and complete the rest
of the fields. Use the on-screen hints to guide your input. If you have questions about
completing these fields, contact your company’s certificate expert.
4. Click Submit to generate a self-signed certificate for the specified EasyCall Gateway.
The certificate fingerprint appears in the Certificate Status area.
Note: Although you can use this self-signed certificate with the EasyCall Gateway,
EasyCall users will receive security alerts when attempting to connect to the EasyCall
Gateway.
5. Select Export certificate signing request to create the certificate signing request. The
CSR appears in a separate window. This is the document required by CAs. The CSR
begins with the text "BEGIN NEW CERTIFICATE REQUEST" and ends with "END NEW
CERTIFICATE REQUEST".
Note: If you have pop-ups blocked in your Web browser, you must temporarily enable
pop-ups to view the CSR.
6. Copy the text in a text editor and save the file.
7. Follow your company’s procedure for contacting the appropriate CA to obtain a
certificate. Have the following information available:
●
The CSR that you saved in the previous step.
Server platform information: The server platform is Apache and the certificate
usage is Web Server. Not all CAs require this information.
The CA will provide an SSL server certificate, a root certificate, and an intermediate
certificate.
●
8. Save the certificates in a text editor, using the following file names:
51
●
certificate.cer — server certificate
●
chain1.cer — root certificate
●
chain2.cer — intermediate certificate
Configuring Authentication
Authentication validates users before allowing access to EasyCall. The default
authentication for EasyCall allows any user to place calls through EasyCall provided that all
of the following conditions are met:
●
The EasyCall plug-in is installed on the user’s computer.
●
The EasyCall plug-in can connect to the EasyCall Gateway, which is usually installed
behind the corporate firewall.
●
The user’s login must match one on the list of users from a directory source.
These topics describe the authentication script and how to use the administration tool to
work with it:
52
About Authentication
Get an overview to authentication and the supported
authentication mechanisms
About the Authentication
Script
Learn about the script and its required functions:
authenticate and cleanup
Changing and Testing the
Script
Change the script, test it, and restore the default script
About Authentication
The EasyCall Gateway administration tool provides access to the default authentication
script so that you can integrate your existing authentication mechanism into the EasyCall
Gateway. The default authentication script does not validate the domain/username. Thus,
to verify domain/username against an authentication mechanism, you must develop a web
service client using the EasyCall Web Services APIs, as described in Using the Web Services
API to Build Web Apps.
The following steps describe what occurs when the EasyCall (communications) plug-in
attempts to log in to the EasyCall Gateway:
1. The EasyCall plug-in sends the login request to the EasyCall Gateway server.
2. The server verifies the validity of the plug-in. Login is denied if the server cannot verify
the plug-in.
3. The server verifies that the user’s login matches one on the list of users from a
directory source.
4. The server verifies the user’s domain/username (passed by the EasyCall plug-in) against
the authentication script. If the script rejects the user’s domain/username, login is
denied.
The EasyCall Gateway supports any authentication method that has an API, including the
following:
●
Active Directory
●
LDAP
The EasyCall Gateway supports the OpenLDAP library, provided by Novell. Those
resources are available at http://www.openldap.org/. It also supports the LDAP
provided with the Java Development Kit.
53
●
RADIUS
●
SmartCard
●
Client certificate
●
Third-party authentication (such as web server authentication)
●
Local file
●
And any other method with an API
About the Authentication Script
You can view and edit the default authentication script through the EasyCall Gateway
administration tool on the User Management > Authentication page.
Note: Knowledge of JavaScript is required to modify the script. Depending on your
authentication system, you might also need to know Java and other technologies. If your
site requires assistance, please contact your Citrix Reseller or Citrix Professional Services.
The authentication script is executed when the EasyCall Gateway starts and when you save
a change to the script on the Authentication page.
The script must export two functions, one used for authentication and one used to clean up
after the script is replaced. The global context of the script can be accessed from those
functions. The global context may carry global variables or additional functions as required.
The global context is executed when the script is installed.
For an example script, refer to http://support.citrix.com/article/CTX123674. For
information about the EasyCall Web Services API, refer to Using the Web Services API to
Build Web Apps.
authenticate() Function
The authenticate function takes a userInfo object as its input and returns an AuthInfo
object.
authenticate(userInfo)
Inputs
The userInfo object provides the following methods:
●
getUserName()
Returns a string with the username that was provided by the client. If the user was
logged in on a particular domain, the username will come in form of
(DOMAINNAME\USERNAME).
●
getCustomField(fieldName)
Returns a custom field string with the specified name string. These fields are read from
the client request to authenticate. The fields may have to be requested from the client
by using the NEED_MORE_INFO error code first, as described in Returns, next.
Returns
The AuthInfo object provides the following fields, described in the table:
●
54
ErrorCode
About the Authentication Script
The ErrorCode field is used to determine whether the authentication was successful,
unsuccessful, or if more data is required from the client.
●
requestField
●
requestValue
Error Codes
Must be used to indicate:
SUCCESS
Successful authentication.
NEED_MORE_INFO requestField
[requestValue]
The client needs to send more information
to the server for authentication to
succeed. (The EasyCall plug-in supports
only the username or username/domain
name. A custom Web service must be used
if additional information is required to log
in the user.)
requestField: Required. Indicates to the
client which property needs to be
provided.
requestValue: Required only if the
response value should be computed based
on some data. It can be used by the client
to calculate the response.
INVALID_ARGUMENT requestField
An invalid or missing value.
requestField: Required. Indicates to the
client which property had an invalid value.
ACCESS_DENIED
That the credentials are invalid.
SERVER_ERROR
A system error.
cleanup() Function
When the authentication script is removed from the system, for example, replaced with a
newer version, the cleanup() function is called. cleanup() should be used to close any
open files, sockets, or release any other system resources that have been allocated during
the initialization or execution of the authentication script.
When you use the test function on the User Management > Authentication page,
cleanup() is always performed as the last step of the test.
55
Changing and Testing the Script
Use the User Management > Authentication page to input changes to the authentication
script, test it, and save it. You can directly test the authenticate function. Although you
cannot directly test the cleanup function, it is called after the authenticate function
completes.
Note: Be sure to test your script before attempting to save it. If an attempt to save a
script fails because of a compilation error, the script will not be saved.
When the script is tested from the Authentication Script page, it undergoes all life cycles:
The global context is first executed, then the function being tested is executed, and then
the cleanup is performed, as shown in the following flow diagram.
To change and test the script
1. Go to the User Management > Authentication page and input your changes in the
script.
2. Click Show Test Dialog to display the test fields.
3. Enter a username to test.
4. If your script includes custom fields, click Add Data for each field and input each key
name and a test value for it. The following constants are defined for the key-value pairs
that the client can send to the server. Your script can define others.
Key
56
Description
Changing and Testing the Script
user_name
The username of the user connecting to
the EasyCall Gateway. The username
must come in the form or
"DOMAINNAME\USERNAME" or
"USERNAME". This field is required when
logging in.
client_type
Any web service client should specify the
value "GENERIC" for this key.
redirect_count
Redirection count. The client must
increase this count to “1” any time it is
following a redirection as a result of
encountering a REDIRECT result.
Otherwise, the count should never be
set.
5. Click Run Test to compile the current script and then execute the selected function.
The result returned by the tested function appears above the test area. If your script
throws any exceptions that you think should be ignored, be sure to change the script to
catch the exception manually.
6. When you are satisfied with the test results, click Save. (Click Cancel to remove
changes made to the script since it was last successfully saved.)
The EasyCall Gateway attempts to compile the script. If there are no compilation
errors, the script is saved and becomes effective immediately.
If the compilation fails, a description of the error displays below the script text area
and the script is not saved.
Note: To restore the default script, click Set Default.
57
Configuring Telephony Settings
These topics describe telephony system configuration:
58
To define the trunk
type and connection
Add, edit, activate, or deactivate trunks.
To configure call
handling
Configure settings so that calls are dialed correctly from the
locale of the EasyCall Gateway.
To specify the caller
ID defaults
Configure caller ID display defaults.
To configure Call
Forwarding
Read a summary of the tasks required to configure call
forwarding.
Configuring Net Call
Configure Net Call with or without a Web-based front-end.
Configuring EasyCall
Voice Prompts
Disable the voice prompt; create and upload custom voice
prompts.
Customizing
Telephone Number
Recognition
Learn how EasyCall recognizes and normalizes telephone
numbers and about the customization services available from
Citrix Technical Support.
To define the trunk type and connection
You must define each trunk that connects the telephony system to the EasyCall Gateway.
This configuration can be done in tandem with the configuration described in the EasyCall
Gateway Telephony System Integrator’s Guides available from
http://support.citrix.com/product/cg/. (Click the link for the release and then locate the
integrator's guides on the Documentation tab for the release.)
If you have questions about the properties of the trunks configured at your site, please
contact the telephony specialist who configured your telephony system. For a list of the
trunks supported by the EasyCall Gateway, refer to the Pre-Installation Checklist.
1. In the administration tool, click Cluster Configuration > Trunks.
2. To add a trunk to the node, click Add Trunk. To change an existing trunk, click the
trunk name in the list.
3. Enter a descriptive Trunk Name and select the node to be configured for the trunk.
4. Complete the Switch Settings as described in the following table.
Setting
Description
SIP Domain
The FQDN of the telephony system server.
PBX IP Address
The IP address or host name of the telephony system.
Defaults to 0.0.0.0.
PBX Port
The port on which the telephony system receives SIP
calls. Defaults to 5060 for SIP.
User Name
If you are using a SIP carrier, complete the additional
settings as described in the EasyCall Gateway
Telephony System Integrator’s Guide for the SIP
carrier.
Secret
Voice Mail Extension
Used to forward a call to voice mail when an EasyCall
user with Call Forwarding enabled does not answer any
of the configured phone locations. For example,
“2345”.
Call Configuration
See To configure call handling.
5. To immediately activate the trunk, click the Activate Trunk link for the trunk.
59
To configure call handling
Before the EasyCall Gateway sends a phone number to the telephony system for dialing, it
modifies the number so that it is dialed correctly from the locale of the appliance. For
more information on phone number handling, see Customizing Telephone Number
Recognition.
Note: When you change EasyCall configuration, you must let users know that they need
to restart EasyCall to update it with the changes.
1. In the administration tool, click Cluster Configuration > Trunks.
2. Click the trunk name in the list.
3. Complete the Call Configuration settings as described in the following table and then
click Submit.
60
Setting
Description
Use Diversion
Applies to Cisco telephony systems only. This checkbox
must be selected to support Call Forwarding.
Use E164 dialing
Applies to SIP carriers only. Refer to the EasyCall
Gateway Telephony System Integrator’s Guide for your
telephone system for information on this option and
how it affects other call settings. The guides are
available from http://support.citrix.com/product/cg/.
(Click the link for the release and then locate the
integrator's guides on the Documentation tab for the
release.)
Country
The Country name of the trunk connected to the
EasyCall Gateway. The EasyCall Gateway uses the
country name and area codes to determine if a phone
number should be dialed as a local, domestic, or
international number from the locale of the telephony
system associated with the EasyCall Gateway. For more
information about how the EasyCall Gateway handles
phone numbers, see About EasyCall Number
Manipulation.
Domestic Dial Prefix
The prefix needed to dial a domestic long distance
number from the locale of the EasyCall Gateway.
Populated based on the Country selected.
International Dial Prefix
The prefix needed to dial from the locale of the
EasyCall Gateway to another country. Populated based
on the Country selected.
Area Code
The local area code of the trunk connected to the
EasyCall Gateway. For some locations in Europe, the
area code is the geographic area code without the
domestic dialing prefix.
To configure call handling
61
Trunk Access Code
The prefix that must be dialed to access an outside line
from the corporate telephony system. Defaults to 9.
Domestic Cell Prefix
Applies to Mexico and Argentina only. The prefix that
must be dialed when calling a cell phone in Mexico (or
Argentina) from within that country. Optional.
Domestic Carrier Code
The domestic carrier code to be used when dialing a
domestic number. Optional.
International Carrier Code
The international carrier code to be used when dialing
an international number. Optional.
Use International Carrier
Code instead of
International Prefix
Applies to Finland only. When this option is selected,
the International Dial Prefix will not be added to
numbers that include an international carrier code.
Optional.
Use Open Numbering Plan
If your country has a closed numbering plan, clear this
option. Closed numbering plans have the same phone
number length throughout the country and there is no
concept of local dialing vs. domestic dialing. That is,
you dial a number the same way whether you are
calling next door or to a different area code.
Can Send SIP Re-INVITEs
When enabled, this setting allows the telephony
system to make the two calls (to the caller and the
callee), bridge them, and then drop out of the call. If
your telephony system does not allow re-INVITEs to be
sent, disable this setting to avoid one-way audio.
To specify the caller ID defaults
By default, EasyCall users can choose to have their caller ID shown or hidden when making
calls with EasyCall. You can supply the default caller ID to appear when users block display
of their caller ID.
1. In the administration tool, click Cluster Configuration > Cluster.
2. Enter the Default Caller ID.
62
To configure Call Forwarding
Call Forwarding enables EasyCall users to forward their office phones to any phone. Thus,
remote workers gain the benefits of making and receiving calls through EasyCall regardless
of where they are.
To use this feature, EasyCall users:
●
Add to EasyCall the phone numbers (locations) where they want calls redirected.
●
Specify the order in which phones are dialed.
●
Enable/disable Call Forwarding at any time.
Those tasks are covered in the.
1. Determine if your telephony system supports redirection. For example, SIP carriers do
not support this feature.
2. Refer to the EasyCall Gateway Telephony System Integrator’s Guide for your telephony
system for any configuration needed to support Call Forwarding. Those guides are
available from http://support.citrix.com/product/cg/. (Click the link for the release
and then locate the integrator's guides on the Documentation tab for the release.)
3. Verify that the Extension attribute is defined on the LDAP Directory Source
Configuration - Details Configuration page. (If the extension is provided in the work
phone field only, Call Forwarding will not work.)
4. Enable the Use Diversion option on the Add/Edit Trunk page, as described in To
configure call handling.
63
Configuring Net Call
The Net Call feature enables you to configure links on web pages that any web surfer can
dial. By using Net Call, you can eliminate the cost of supporting toll-free numbers by
providing links on internal and external portals to frequently dialed numbers such as sales
and support.
There are two methods for configuring Net Call:
●
Simplest Web site configuration. More steps for a user to make a call.
With this configuration, users who click a Net Call link are prompted to enter their
phone number. After their phone rings, they must enter "1" to confirm the call (if
Prompt to Complete Call is enabled). Then, the Net Call number they are calling rings
and the users are connected to the Net Call number.
●
More involved Web site configuration. Fewer steps for a user to make a call.
With this configuration, users who click a Net Call link are connected to the Net Call
number with no additional action on their part. The Web-based front-end collects the
user’s phone number and country code and uses that to build the required URL.
To configure Net Call without a Web-based front-end
This is the simplest configuration. However, users who click a Net Call enabled link must
enter their phone number before the call can be completed.
1. Specify the numbers you want to use with Net Call: In the administration tool, go to Net
Call Configuration.
2. Specify an alias and phone number for each Net Call number you want to include on
your Web site. To add a Net Call number, click Add Phone Number. The alias is used
behind the scenes to identify a phone number. The alias for a phone number must be
unique.
3. After you have completed adding phone numbers, click Submit. The links that need to
be added to your Web site appear beside the numbers that you added.
4. Provide to your company Web designer the URLs the links that are on the Net Call
Configuration page.
To configure Net Call with a Web-based front-end
This more involved configuration uses a Web-based method to collect user phone numbers
so that users do not have to enter a phone number to complete a call.
1. Specify the numbers you want to use with Net Call: In the administration tool, go to Net
Call Configuration.
64
Configuring Net Call
2. Specify an alias and phone number for each Net Call number you want to include on
your Web site. To add a Net Call number, click Add Phone Number. The alias is used
behind the scenes to identify a phone number. The alias for a phone number must be
unique.
3. After you have completed adding phone numbers, click Submit.
4. Provide to your company Web developer the following URL format. The Web developer
will need to build a Web-based front end that collects a caller’s phone number and
country code.
https://ipAddress/netcall?phonealias=alias&countrycode=code&callerphone=number
For example:
https://10.10.100.10/netcall?phonealias=Sales&countrycode=1&callerphone=4085551212
65
Configuring EasyCall Voice Prompts
Voice prompts assist EasyCall and Easy Conference users during a call. By default, EasyCall
users must press “1” before being connected to the number being called. You can disable
that prompt and the requirement to press 1.
You can also customize some voice prompts for each supported locale and upload them to
the gateway through the Maintenance > Upgrades page. If you need to return to a default
.wav file and do not have a backup file, please contact Citrix support.
To disable the voice prompt and requirement to press
1
1. In the administration tool, click Cluster Configuration > Cluster.
2. Clear the checkbox for Prompt to Complete Call. This option does not apply to EasyCall
Conference.
To create and upload custom voice prompts
You can customize the following voice prompts.
Action
Default voice prompt and filename
EasyCall confirmation, played
when the caller connects to the
gateway.
For Citrix to complete your call, press 1. To skip this
message in the future, you may press 1 at any time.
locale_ConfirmCall.wav
EasyCall disconnection, played
when the gateway cannot
complete the call.
We are unable to complete your call at this time.
Disconnecting.
locale_Disconnecting.wav
Conference confirmation, played
when the caller connects to the
gateway.
For Citrix to add you to your conference, press 1. To
skip this message in the future, you may press 1 at
any time.
locale_ConfirmConference.wav
Conference disconnection, played
when the gateway cannot
complete the call due to an
invalid confirmation code.
A valid confirmation code was not received. We are
unable to add you to your conference at this time.
Please contact your conference chairperson.
Disconnecting.
locale_DisconnectConference.wav
66
Configuring EasyCall Voice Prompts
Conference PIN reminder, played
during the call initiated when the
user clicks the Forgot Your PIN
link.
In response to your request for a reminder
locale_EasyConferencePinReminder.wav
this message will repeat three times.
locale_EasyConferencePinRepeat.wav
Your conference Pin is
locale_EasyConferenceYourPin.wav
1. Use a sound recording program to record the prompts. To use a sound recording
program, your computer must have a sound card and a microphone. The sound
recording program provided with Windows is located at Start > Programs > Accessories
> Entertainment > Sound Recorder.
2. Save the recordings to the appropriate filenames. locale is DEU, ENG, ESP, or FRA.
3. Put the WAV files in a location that is reachable from the EasyCall Gateway.
4. To upload the WAV files, click Maintenance > Upgrades.
5. Click Browse, locate the WAV file, and then click Open.
6. Click Upgrade to upload the WAV file.
67
Customizing Telephone Number
Recognition
When a user hovers the mouse pointer over an area of the screen, EasyCall looks for
possible telephone numbers. If EasyCall recognizes a series of digits as a probable
telephone number, it displays the number in a fade-in phonebar. The user can edit any
discrepancy in the number before calling it. After the user clicks to call the number,
EasyCall sends the number to the EasyCall Gateway. The EasyCall Gateway applies dial rules
to the number, dials the caller’s specified phone, and then dials the clicked number.
The following topics describe how EasyCall recognizes and normalizes telephone numbers
and provides an overview to the customization services available from Citrix Technical
Support.
About EasyCall Number Recognition
About EasyCall Number Manipulation
Number Recognition Customization Options
Unsupported Number Patterns and Dialing Provisions
68
About EasyCall Number Recognition
EasyCall supports local, long distance, and international telephone numbers as well as
internal extensions and phone numbers that include alphabetic characters.
Note: International telephone numbers must be E.164-compliant. E.164 is a standard for
phone numbers recommended by the International Telecommunication Union’s
Telecommunication Standardization Sector (ITU-T). The majority of the world’s
telephone numbers conform to the E.164 format, which is typically + or ++ (plus sign),
followed by a maximum of fifteen digits consisting of country code, area code, and
subscriber number.
To enable EasyCall to recognize numbers appropriately for a particular locale, EasyCall
obtains a user’s country code from the Windows locale setting. If the user has configured
the Phone and Modem Options (available from the Windows Control Panel) with a country
code and area code, EasyCall will use them. EasyCall users can change their current country
code and area code through the EasyCall interface.
While EasyCall can find telephone numbers in many contexts, it may not find the following
numbers:
●
Numbers that are hyphenated at the end of a line.
●
Numbers located in tables, including those that are word-wrapped in a cell.
●
Numbers in scanned documents.
●
Numbers that include an extension, such as "020-7946-0555 Ext. 200".
●
Internal or private network telephone numbers (configurable).
●
Numbers that appear within a series of other numbers.
●
Numbers that contain unusual characters such as brackets or slashes. The valid
delimiters in phone numbers are:
Square brackets: [ ]
Parentheses: ( )
Forward slash: /
Hyphen: Period: .
Single quotation mark: '
Space
●
69
Numbers in very large or very small fonts.
About EasyCall Number Recognition
●
Numbers that contain double spaces, such as "201 555 2368".
●
Numbers that include a period followed by a space, such as "303 . 555 . 4578".
EasyCall does not recognize numbers that are in unusual formats as detailed in Unsupported
Number Patterns and Dialing Provisions
EasyCall number handling can be customized as described in Number Recognition
Customization Options.
70
About EasyCall Number Manipulation
After EasyCall determines that a number is a telephone number, it normalizes the number
into the E.164 format (the universal format for telephone numbers) and then applies
built-in dial rules.
●
EasyCall uses the country code and area code that users configure in the EasyCall plugin
to determine whether the normalized number should be dialed as a local, domestic, or
international number.
●
After determining how to dial the number, EasyCall applies built-in digit manipulation
rules to create a locally dialable number.
●
Based on the country code and area code of the EasyCall Gateway, EasyCall
appends the appropriate international prefix (such as 011 or 00) or domestic prefix
(such as 1 or 0). It may shorten local numbers if that is possible, such as by
removing the area code (if permitted in the locale).
If an outside line prefix is configured, it is added to the number. The outside line
prefix is configured in the EasyCall Gateway administration tool on the Cluster
Configuration - Add/Edit Trunk page. This prefix and others are described in To
configure call handling.
The following table shows how EasyCall normalizes and manipulates variously formatted
phone numbers when the EasyCall Gateway is configured for the United Kingdom and area
code 1753. Note that normalization results in the addition of country code and area code (if
missing).
●
71
Number displayed on the
Web site
Result of EasyCall
normalization
Number sent for dialing
+44-1953-276200
+44.1953.276200
01953 276200
+44-1753-276200
+44.1753.276200
01753 276200
+44 (0)1753 276200
+44.1753.276200
01753 276200
01753-276200
+44.1753.276200
01753 276200
0175327 6200
+44.1753.276200
01753 276200
276200
+44.1753.276200
01753 276200
The Customization Process
If your site needs customized number recognition, follow these general steps:
1. Refer to the customization tech note at http://support.citrix.com/product/cg/.
Contact Citrix Technical Support if you need to discuss the customization required.
Technical Support can work with you to determine customization needs and will create
a patch file.
2. Upload the patch file to the EasyCall Gateway.
3. Restart the EasyCall Gateway.
4. After the EasyCall Gateway restarts, close all open Web browser windows and log out of
EasyCall.
5. Log back in to EasyCall to see the effects of the customization.
72
Number Recognition Customization
Options
EasyCall number recognition can be customized for your locale. The customization must be
performed by Citrix Technical Support. If your site needs customized number recognition,
follow these general steps:
1. Refer to the customization article at http://support.citrix.com/article/CTX119944.
Contact Citrix Technical Support to discuss the customization required. (The sections
following these steps describe customization options.) Technical Support can work with
you to determine customization needs and will create a patch file.
2. Upload the patch file to the EasyCall Gateway.
3. Restart the EasyCall Gateway.
4. After the EasyCall Gateway restarts, close all open Web browser windows and log out of
EasyCall.
5. Log back in to EasyCall to see the effects of the customization.
Specifying Numbers to be Recognized as Extensions
EasyCall recognizes as extensions one- to five-digit numbers that are preceded by the
following prefixes:
Ext. (and other forms such as EXT., ext., Ext, EXT)
Ext: (and other forms such as EXT:, ext:, Ext, EXT)
x
X
#
/
If your site has Web applications that include extensions as a stand-alone number or as a
number with some other prefix such as “x” or some digits, you can specify the pattern(s) to
be considered phone extensions. For example, if you have a directory application with
four-digit extensions, EasyCall can be customized so that any four-digit number series is
recognized as an extension.
73
Number Recognition Customization Options
Changing the Recognition of Numbers that Include
Alphabetic Characters
By default, EasyCall recognizes some phone numbers that contain alphabetic characters,
such as 1-800-Flowers. For example, in the U.S, numbers that include alphabetic characters
are recognized by EasyCall if they have the prefixes 800, 866, 877, or 888.
That behavior can be customized as follows:
●
Add prefixes that can be used with alphabetic characters. For example, this would be
needed if your users frequently make calls to a number on your Web site that is
prefixed with your area code and contains alphabetic characters (such as
404-GET-DATA).
●
Remove any of the default prefixes that can be used with alphabetic characters. For
example, you can block access to all phone numbers containing alphabetic characters
by not including any predefined prefixes for phone numbers.
Defining the Format for Private Network Numbers
Corporate phone books and directories might include private network phone numbers, such
as the following:
+NN.NN.NNNN.NNNN
ESN NNN-NNNN
(ESN) NNN-NNNN
Customization can define the private network number patterns to be recognized as dialable
numbers. For example, customization can enable EasyCall to:
●
Dial a private network number (such as +52.55.5905.1707) as an “on-net” number
(560-1707).
●
Dial a private network number (such as ESN 560-1700) as an extension (5601707).
EasyCall recognizes such numbers as in-network extensions rather than as local numbers
and does not add prefixes configured in the Configuration - Add/Edit Trunk page to the
dial strings.
Changing How Ten-Digit Numbers are Recognized
EasyCall uses the country code and area code that you configure in the EasyCall Gateway to
determine whether the number should be dialed as a local, domestic, or international
number. If EasyCall is unable to recognize a ten-digit phone number as international (the
number is not prefixed with a +, ++, 00, or other international dial prefix), EasyCall can be
customized to interpret the number as follows:
●
74
Interpret a ten-digit number as a domestic number, based on the locale of the EasyCall
Gateway. For example, if the EasyCall Gateway is in Germany and a user hovers over a
Number Recognition Customization Options
ten-digit number, the number is interpreted as a domestic number (rather than a U.S.
number).
●
Interpret a ten-digit number as a U.S. number, regardless of the locale of the EasyCall
Gateway.
Handling Overlay Area Codes
EasyCall identifies a phone number in locales served by a single area code. However, some
locales have more than one area code in their local dialing area. These multiple area codes
are referred to as overlays. In some locales, the domestic prefix is not required when
dialing a local number with an overlay; in other locales, the domestic prefix is required.
For example, in Denver, Colorado numbers beginning with area codes 303 and 720 are
considered local numbers. To dial a local number in Denver, you must always include the
area code, but you do not need to include the domestic prefix (1). However, some locales
with overlays do require the domestic prefix. EasyCall can handle such locales through
customization.
Restricting the Number Patterns Recognized as
Phone Numbers
EasyCall contains instructions that prevent certain number patterns in Web pages and
emails from being recognized as telephone numbers. For example, EasyCall ignores numbers
preceded by “fax”, “tty”, “P.O Box”, and currency symbols, as well as numbers that are in
date, time, and IP address formats.
EasyCall can be customized with additional character sequences to be ignored to handle
patterns specific to your applications or locale.
75
Unsupported Number Patterns and
Dialing Provisions
EasyCall does not support the following, either due to number recognition or dialing
limitations:
●
Recognition of multiple phone numbers for which only the subscriber number is
repeated. For example:
Tel: +20 02 7943194 - 7943195 – 7940658
where – separates the three subscriber numbers. In this case, +20 02 7943194 will dial
correctly, but the second and third partial numbers will not.
Similarly, in the following number formats, only the first number listed will dial
correctly:
+20 02 7943194 / 95
(662) 233-7060, 234-8060
+420 412 531164 , 412 531626
●
Recognition of phone numbers that include non-standard characters or formatting, such
as the following:
03-5812-6600(9:00~18:00)
+358-(0)9-701 2424, +358-(0)50-566 4527
+90 212 347 21 35-36-37-38
●
Recognition of both a phone number and its extension. When EasyCall encounters the
following patterns, it recognizes either the phone number or the extension, depending
on where the mouse is hovering:
13035551212 ext.112
13035551212, ext.112
13035551212 ext 112
●
Recognition of phone numbers that are delimited with a bullet character, if the page is
using the ISO-8859-1 encoding and uses the 0x95 character instead of the character
entity reference for a bullet (•), such as:
800.253.2224•707.944.0228
This is not an issue in pages that use UTF-8 encoding.
76
Unsupported Number Patterns and Dialing Provisions
●
77
Recognition of phone numbers that include a single quotation mark (').
Configuring Directory Sources
You can configure an unlimited number of directory sources for EasyCall. The EasyCall
Gateway supports LDAP directories, Microsoft Active Directory, directories saved in
Comma-Separated Value format (CSV), and directories provided by a custom script.
Information from the directory sources:
●
Appears in the EasyCall Directory.
Once a directory entry has been created for a user, that user can change the user
information. Any such changes are not overwritten by subsequent synchronizations with
directory sources.
A user’s name is not case-sensitive. EasyCall uniquely identifies a user by a combination
of the user name and the directory source from which the user was obtained.
●
Appears, by default, as the locations from which an EasyCall user can make phone calls.
EasyCall displays the labels "Work", "Mobile", and "Other" and the corresponding phone
numbers from the directory source.
A user can make calls from any of those telephone numbers when connected to the
EasyCall Gateway. The caller ID displayed for such calls will be the default caller ID
defined for the EasyCall Gateway (not the caller ID of the phone being used to make
the call).
Users can change their locations and create additional locations. You can prevent users
from creating locations: Define a Group that does not include the role for creating
locations and then associate that group to the directory source from which the users
are obtained.
These topics describe group and directory source configuration:
78
To add a group
Add a group to to associate a directory source with a set of
roles.
To configure an
LDAP/AD directory
source
Configure LDAP-based or Active Directory (AD) sources.
Managing Directory
Sources
Delete a directory source, force a synchronization, and specify
whether to overwrite user information.
Looking up Attributes
in Your LDAP Directory
Install, set up, and use LDAP Browser.
CSV File Requirements
Learn about the file requirements of directory information
saved in a CSV-formatted file.
To configure a CSV
file as a directory
source
Configure a CSV file as a directory source.
Configuring Directory Sources
79
To configure a custom
script for directory
sources
Configure a script to connect to external directory sources.
Viewing User
Information
View users by online status or directory source and view user
details.
To add a group
A group is used to associate a directory source with a set of roles. A group can include one
or more of the following roles:
●
CALL (can place calls through EasyCall)
●
CONFERENCE (can create conferences through EasyCall)
●
CALL_FORWARD (can forward calls placed to an office extension to other EasyCall
locations)
●
CREATE_LOCATIONS (can create locations in EasyCall)
The group All Roles is created for you. When you add a directory source, you must specify a
group for the source. Directory sources that existed before you upgraded to Release 3.0 are
automatically assigned to the All Roles group.
1. In the administration tool, click Directory Source Configuration.
2. In the Groups tab, click Add Group.
3. Enter a name for the group.
4. Select each EasyCall feature that you want available to users in the group and then
click Submit.
5. In the Groups tab, specify in the Group Policy area how you want users handled if their
group is deleted and then click Submit.
80
To configure an LDAP/AD directory
source
The EasyCall Gateway supports the following directory types and automatically detects the
version in use.
●
LDAP version 3
●
Microsoft Active Directory
●
Nortel Messaging LDAP version 2
●
OpenLDAP
If you are unfamiliar with the LDAP attributes for your site, see Looking up Attributes in
Your LDAP Directory for information about a free LDAP browser you can use to display the
structure of your LDAP directory and its attributes.
1. In the administration tool, click Directory Source Configuration.
2. In the Directory Source Settings section, which applies to all directory sources:
●
Select how you want to handle user accounts that are in multiple directory sources.
For users who are not in a group that has the CREATE_LOCATIONS role, use the
Show the Caller ID of Restricted Users checkbox to indicate whether the caller ID
for automatically created locations should be shown.
3. Click Submit.
●
4. To add a directory source, click Add. To change the settings of a configured directory
source, click its source name link. The Directory Source Configuration page appears.
5. A directory source is always used to populate the EasyCall Directory. If you also want
the directory source to be used as a source of EasyCall users, select the Use this
directory as a source for EasyCall users checkbox. When you select the checkbox,
additional fields appear:
81
●
For User Domain Prefix, enter the domain associated with users in this directory
source. When a user logs in to EasyCall, the user must specify a domain, which is
validated against the domain prefix specified here.
●
For Node Name, specify the node for which this source is to be used. Defaults to
Any. You would select a specific node if you want this directory source to apply only
to that node and not be available to EasyCall users who are connected to other
nodes in the same cluster.
●
For Trunk Name, specify the trunk for which this source is to be used. Defaults to
Any. You would select a specific trunk if you want this directory source to apply
only to that trunk and not be available to EasyCall users who are connected to
other trunks.
To configure an LDAP/AD directory source
6. Select the Source Type Directory Server and then enter a descriptive name for the
source.
7. Select the group to be associated with the source (to determine the roles each user in
the group will have).
8. Specify a synchronization schedule for the source.
9. Click Next Step.
10. Complete the other settings as described in the following table.
Setting
Description
Server Address
The IP address or host name and port for the LDAP
server to be used to import directory information. The
Cisco DC Directory port is usually 8404.
Server Port
The LDAP Server Port for some LDAP directories is
typically 389. If you are using an indexed database,
such as Microsoft Active Directory with a Global
Catalog, changing the LDAP Server Port to 3268 will
significantly speed the LDAP queries.
If your directory is not indexed, we recommend that
you use an administrative connection, rather than an
anonymous connection, from the EasyCall Gateway to
the database. Download performance improves when
you use an administrative connection.
82
To configure an LDAP/AD directory source
Bind DN
Bind Password
The Administrator Bind DN and password for queries to
your LDAP/AD directory. The EasyCall Gateway binds to
the directory server using the administrator credentials
and then searches for the user. After locating the user,
the EasyCall Gateway unbinds the administrator
credentials and rebinds with the user credentials.
Example syntax for Bind DN:
"cn=DirectoryManager,o=cisco.com" (Cisco DC
Directory)
"ou=administrator,dc=ace,dc=com"
"username" (Active Directory User Principal Name,
UPN)
"cn=Administrator,cn=Users,dc=ace,dc=com" (Active
Directory)
For Active Directory, if you do not use the UPN for the
Bind DN, the group name (specified as "cn=groupname")
is required. For other LDAP directories, the group
name either is not required or, if required, is specified
as "ou=groupname". For Active Directory, you cannot
use the email address as the Bind DN.
Note that most directories do not return useful
information on anonymous binds.
Base DN
The Base DN to be used as a starting point for directory
searches. Base DN is usually derived from the Bind DN
by removing the user name and specifying the group
where users are located.
Example syntax for Base DN:
"ou=Users,o=cisco.com" (Cisco DC Directory)
"ou=Users,dc=ace,dc=com"
"cn=Users,dc=ace,dc=com" (Active Directory)
Search Filter
The LDAP search filter used to limit the imported
entries. Defaults to objectclass=person.
You can specify multiple search filters using the syntax
for objectclass filters. for example:
(&(&(&(objectClass=top)(objectClass=person))(objectClas
Please contact support if you need assistance.
83
To configure an LDAP/AD directory source
Attributes:
Default values for these attributes:
Email address
mail
Username
username (This is the only required field.)
Display Name
cn
FirstName
givenName
Surname
sn
Title
title
Department
department
Work Phone
telephoneNumber
Extension
ipPhone
Mobile Phone
mobile
Other Phone
home
11. Click Save. The EasyCall Gateway synchronizes with the new directory source.
84
Managing Directory Sources
To delete a directory source
●
Click Directory Source Configuration, select the checkbox beside each source name
you want to delete, and then click Delete. To select all checkboxes at once, select the
checkbox in the table heading.
To force a synchronization
If your directory sources change and you want to synchronize with them before the next
scheduled synchronization, you can force a synchronization as follows.
●
Click Directory Source Configuration, select the checkbox beside each source name
you want to update with the directory source, and then click Sync. To select all
checkboxes at once, select the checkbox in the table heading.
To specify how to handle users that are defined in multiple directories
●
Click Directory Source Configuration, select one of the directory source settings, and
click Submit.
If you choose Never overwrite user information and only show conflicts that have
occurred, conflicts will be indicated by the addition of a Conflicts button to the Directory
Source Configuration page after a synchronization. Click the Conflicts button to view user
information that appeared in multiple sources (and therefore was not overwritten).
85
Looking up Attributes in Your LDAP
Directory
With the exception of the LDAP Base DN syntax, which is site-specific, the attributes used
for EasyCall are defaults common to widely used LDAP directory applications. If a default
attribute does not work for your site, you can easily look up the correct attribute with the
free LDAP Browser from Softerra.
To install and set up LDAP Browser
1. Download the free LDAP Browser application from www.ldapbrowser.com.
2. Install LDAP Browser and open it.
3. From the LDAP Browser window, choose File > New Profile and specify the following
settings:
●
Host: Host name or IP address of your LDAP server.
●
Port: Defaults to 389.
●
Base DN: You can leave this field blank. (The information provided by the LDAP
Browser will help you determine the Base DN needed on the Attribute
Configuration tab.)
Anonymous Bind: Select the checkbox if the LDAP server does not require
credentials to connect to it. If the LDAP server requires credentials, leave the
checkbox cleared, click Next, and enter the credentials.
4. Click Finish. The LDAP Browser displays the profile name that you just created in the
left pane of the LDAP Browser window and connects to the LDAP server.
●
86
Looking up Attributes in Your LDAP Directory
To look up LDAP attributes
1. In left pane of the LDAP Browser, select the profile name that you created.
2. To look up the Base DN, locate in the right pane the namingContexts attribute. The
value of that attribute is the Base DN for your site. The Base DN is typically
"dc=myDomain,dc=com" (if your directory tree is based on Internet domain names) or
"ou=domain,o=myOrg,c=country".
3. Note the objectClass entries. The LDAP Search Filter on the Attribute Configuration
tab defaults to objectClass=person which will search the person class. You do not need
to change that default unless you need to narrow the search.
4. To look up the attributes associated with people, such as name and phone numbers:
a. Double-click the folder at the top of the right pane. The right pane displays the
structure for the attribute that you clicked. For example, you might see a "cn" entry
for each individual in the LDAP directory or "ou" entries under which you will find
individuals or groups. Click through the structure until you locate a list of
individuals.
b. Double-click the folder for an individual to view the attribute names and compare
them to the attributes in the EasyCall Gateway Attribute Configuration tab.
87
CSV File Requirements
CSV files uploaded to the EasyCall Gateway must meet the following general requirements:
●
A CSV file used as a directory source can have any filename. The fields must appear in
the following order:
userName
displayName
firstName
lastName
title
department
workTelephone
mobileTelephone
otherTelephone
email
PBX_extension
The three telephone numbers will appear under the headings Work, Mobile, and Other
in the EasyCall Directory. Here is a sample record:
tranga,Thai Ranga,Thai,Ranga,Manager,Engr,408 555 6693,408 555
1234,408 555 2344,tranga@company.com,x4010
●
The first line of the CSV file is ignored (it can contain field headings). Each subsequent
row is a record with field values.
●
A record must appear on one line. A line can be terminated with a line feed (0xa) or
with the carriage return and the line feed characters (0xd 0xa).
●
Fields must be separated by commas (u002c). Two consecutive commas designate an
empty field.
●
All the fields must be specified on a line for the line to be considered valid. If a field
value is missing, empty space should be used. In other words, the number of field
separators should be constant on every line.
●
The username field must be non-empty and must contain characters other than white
space characters.
●
You must use UTF-8 encoding for non-ASCII characters (such as European characters).
●
Any whitespace characters at the beginning or the end of a field are discarded, unless
enclosed in quotation marks. A field consisting of whitespaces only will be considered
empty.
●
A whitespace character is defined as:
Unicode space character (Not non-breaking spaces: u00A0, u2007, u202f)
88
CSV File Requirements
Horizontal Tabulation (u0009)
Line Feed (u000a)
Vertical Tabulation (u000b)
Form Feed (u000c)
Carriage Return (u000d)
File Separator (u001c)
Group Separator (u001d)
Record Separator (u001e)
Unit Separator (u001f)
89
●
To prevent a single character from processing, escape the character by preceding it
with a backslash character (u005c). The backslash character itself should be escaped by
another backslash character. Escaped characters do not impact processing; thus, if a
comma is escaped, it is not considered a field separator.
●
Multiple characters can be escaped by enclosing them in double quotation marks
(u0022). The Backslash escape is recognized inside quotation marks, so that quotation
marks themselves can be escaped.
To configure a CSV file as a directory
source
For directories that can be saved in CSV format, you point the EasyCall Gateway to the
location on an FTP server where you have saved each directory file or to a network location
from which a CSV file can be uploaded. The CSV files used as directory sources for EasyCall
must conform to the CSV File Requirements.
1. In the administration tool, click Directory Source Configuration.
2. In the Directory Source Settings section, select how you want to handle user accounts
that are in multiple directory sources and click Submit. This setting applies to all
directory sources.
3. To add a directory source, click Add. To change the settings of a configured directory
source, click its source name.
4. A directory source is always used to populate the EasyCall Directory. If you also want
the directory source to be used as a source of EasyCall users, select the Use this
directory as a source for EasyCall users checkbox. When you select the checkbox, two
additional fields appear:
●
For User Domain Prefix, enter the domain associated with users in this directory
source. When a user logs in to EasyCall, the user must specify a domain, which is
validated against the domain prefix specified here.
For Node Name, specify the node for which this source is to be used. Defaults to
Any. You would select a specific node if you want this directory source to apply only
to that node and not be available to EasyCall users who are connected to other
nodes in the same cluster.
5. Select the Source Type, either FTP Server or Uploaded CSV File, and then enter a
descriptive name for the source.
●
6. Select the group to be associated with the source (to determine the roles each user in
the group will have).
7. Specify a synchronization schedule for the source.
8. Click Next Step.
9. For FTP Server configuration, enter:
●
The IP address of the FTP server where the CSV file is located.
●
The credentials required to access the FTP server.
The full path and filename of the CSV file on the FTP server.
10. For Uploaded CSV File configuration, enter the location of the CSV file on your network.
●
11. Click Save.
90
To configure a CSV file as a directory source
91
To configure a custom script for directory
sources
You can also use a script to connect to external directory sources. If you need assistance
with developing a custom script, please open a Citrix support case.
1. In the administration tool, click Directory Source Configuration.
2. In the Directory Source Settings section, select how you want to handle user accounts
that are in multiple directory sources and click Submit. This setting applies to all
directory sources.
3. To add a directory source, click Add. To change the settings of a configured directory
source, click its source name link.
4. A directory source is always used to populate the EasyCall Directory. If you also want
the directory source to be used as a source of EasyCall users, select the Use this
directory as a source for EasyCall users checkbox. When you select the checkbox, two
additional fields appear:
●
For User Domain Prefix, enter the domain associated with users in this directory
source. When a user logs in to EasyCall, the user must specify a domain, which is
validated against the domain prefix specified here.
For Node Name, specify the node for which this source is to be used. Defaults to
Any. You would select a specific node if you want this directory source to apply only
to that node and not be available to EasyCall users who are connected to other
nodes in the same cluster.
5. Select the Source Type Custom Script, and then enter a descriptive name for the
source.
●
6. Select the group to be associated with the source (to determine the roles each user in
the group will have).
7. Specify a synchronization schedule for the source.
8. Click Next Step.
9. Enter the script in the text box and click Save. The EasyCall Gateway automatically
synchronizes with the new directory source.
92
Viewing User Information
The User Management page provides the following information about the user accounts in
the EasyCall Gateway database:
●
User details such as name, email address, company extension, and other phone
numbers.
●
The name of the directory source containing the user account and the date the user
record was last updated.
●
The group to which the user belongs and the roles available to the user.
●
The user’s EasyCall configuration, such as the user’s configured locations and Call
Forwarding policies.
●
The user’s online status.
To view users by online status or directory source
●
In the administration tool, click User Management and then select Online Status or
select a directory source and click Search.
To view details about a user
●
93
Click the user’s name in the User Management page.
Clustering EasyCall Gateways
You can group up to four EasyCall Gateways (nodes) into a cluster to provide high
availability, share telephony and data resources, and to load-balance EasyCall traffic across
the nodes.
These topics describe how to work with clustered EasyCall Gateways:
94
About Clusters
Learn about stand-alone, master, and member nodes; the tasks
that can be performed on each node type; how load-balancing
is handled for clusters; and network considerations for clusters.
Pre-Requisites for
Clustering
Read about the setup required for master and member nodes.
To connect a member
node to a master node
Create a cluster.
Working with a Cluster
Back up, upgrade, get information about, activate, suspend,
and disconnect a node.
Working with a
Member Node
Restart, shut down, and use diagnostic tools on a member node.
To disconnect a
member node from a
cluster
Disconnect a member node from a cluster.
To promote a member
node to a master node
Promote a member node to a master node.
About Clusters
When you initially bring an EasyCall Gateway online, it is considered a stand-alone node.
When you log in to a stand-alone EasyCall Gateway and connect another gateway to it, the
gateway you are logged in to becomes the master node. The gateway you connect to the
master node is a member node.
After an EasyCall Gateway becomes a master or member node, you can view its network
interface settings but you cannot change them. To change a master or member node’s
network interface settings, you must disconnect the node from the cluster.
Note: Before creating a cluster, be sure to complete the configuration of each EasyCall
Gateway that will be a part of the cluster, as outlined in To connect a member node to a
master node.
The following table summarizes the tasks that you can perform when logged in to a master,
member, or stand-alone node.
95
Configuration,
Maintenance, and
Monitoring Tasks
Function available when logged in to this node type:
Master
Member
Stand-alone
Configure network
settings
No
No
Yes
View network
settings
Yes
Yes
Yes
Add static routes;
specify Domain
Name Servers; add
entries to the
HOSTS file
No
No
Yes
Configure trunk
settings
Yes, when logged in to the master node.
Yes
Change the root
administrator
password
Yes
No
Yes
Change the NTP
server used by the
gateway or enter a
server date and
time
Yes
No
Yes
Set up SSL
certificates
Yes
No
Yes
Configure telephony
settings directory
sources, and
locations
Yes
No
Yes
About Clusters
Delete conferences
Yes, when logged in to the master node.
Yes
Back up or restore
the system
configuration
Yes. When you back up or restore from the
master node, all connected member nodes
are also backed up or restored.
Yes
Upgrade the server
Yes. When you upgrade from the master
node, all connected member nodes are
also upgraded.
Yes
Shut down or
restart the server
Yes
Yes
Yes
Export or delete
CDRs
Yes
No
Yes
View the Dashboard
or call log
Yes, when logged in to the master node.
Yes
View System log
Yes
Yes
Yes
Perform network
diagnostic tests
Yes
Yes
Yes
Promote to master
node
No
Yes
No
Configure
cluster-wide and
node-wide settings;
activate/suspend a
node
Yes, when logged in to the master node.
Yes
Disconnect a node
Yes, when logged in to the master node.
No
Clustering and Load Balancing
The master node of a cluster handles the load balancing. If the master node becomes
unavailable, the other nodes handle the traffic although without the efficient load
balancing provided by the master node. If a member node becomes unavailable, the other
nodes handle the traffic so that EasyCall service remains available.
Network Considerations for Clustering
EasyCall Gateway clusters are intended as a site solution and not a cross-geographical
solution. All nodes in an EasyCall Gateway cluster must be located on the same local
network and on the same subnet. EasyCall clients can connect to a cluster from any
location which has IP routing to its nodes.
EasyCall Gateways can place calls through a variety of SIP providers, such as SIP PBXs, SIP
carriers, or SIP gateways. Easy node in a cluster can connect to multiple SIP providers or
share a common SIP provider. IP routing must exist between a node and SIP provider.
96
Pre-Requisites for Clustering
Before you can create a cluster, you must configure each EasyCall Gateway that will be in
the cluster. You cannot access network interface settings once a node is added to a cluster.
You can change network interface settings on stand-alone nodes only.
The configuration required differs for master and member nodes, as follows.
Pre-requisites for a master node:
1. Configure network interface settings.
2. Change the root administrator password.
3. If needed, add static routes and configure name service information.
4. Optionally, configure trunk and cluster-wide settings. They can be changed after a
cluster is created.
5. Install SSL certificates.
6. Configure the NTP server used by the gateway.
7. Configure telephony settings, directory sources, and locations.
Pre-requisites for a member node:
1. Configure network interface settings.
2. Change the root administrator password.
3. If needed, add static routes and configure name service information.
4. Optionally, configure trunk settings. They can be changed after a cluster is created.
5. Configure locations. Locations must be consistent across a cluster.
6. Install SSL certificates.
7. Synchronize the server time with the gateway to be the master node. Server time must
be synchronized between master and member nodes to avoid problems with logging and
replicating transactions.
97
To connect a member node to a master
node
After configuring the EasyCall Gateways as outlined in Pre-Requisites for Clustering, you can
connect the servers to form a cluster. When you add a member node to a cluster, the
master node database is replicated to the member node. If the master node subsequently
goes offline, the member node continues to provide EasyCall and EasyCall conference
services.
1. Log in to the EasyCall Gateway to be the master node.
2. Click Cluster Configuration.
3. Click Connect Node.
4. In the Add New Member Node page, enter a name and the IP address of the EasyCall
Gateway you want to connect as a member node.
5. Click Submit. The node is added, with a Node Type of “Member.”
Your cluster now includes a master node and one member node. Repeat this procedure
to add more member nodes.
Note: You can view, but not change, the network interface settings for each node in
a cluster. To view those settings, click the node name link in the Cluster
Configuration - Nodes page. To change the network interface settings of a node, see
To disconnect a member node from a cluster.
6. Go to the Cluster Configuration > Cluster page and complete the settings as described
in the following table.
98
Setting
Description
External Cluster Address
A public domain or public IP address used to create the
URL for the Join Conference pages. The External
Cluster Address must be forwarded to a static IP
address of one of the cluster nodes. Important: The
node which services the External Cluster Address must
have a valid SSL certificate to avoid certificate
warnings from web browsers.
Prompt to Complete Call
By default, EasyCall users must press “1” before being
connected to the number being called. You can disable
that prompt and the requirement to press 1 by clearing
this checkbox. For more information, see Configuring
EasyCall Voice Prompts“Configuring EasyCall Voice
Prompts” on page 61.
To connect a member node to a master node
Default Caller ID
By default, EasyCall users can choose to have their
caller ID shown or hidden when making calls with
EasyCall. You can supply the default caller ID to appear
when users block display of their caller ID.
Default Company Number
The phone number used for Net Call.
Conference Dial-in Number
and Extension
A number that an EasyCall user can dial to initiate a
conference call, as an alternative to using the user
portal to start a conference call. When the call
connects, the user is prompted for the conference ID
and PIN.
The Conference Dial-in Number must be set up from
your telephony system so that it knows how to route all
calls to the number to your EasyCall Gateway.
Maximum Number Per
Node of Conferences and
Conference Participants
99
Used to limit the conference activity per node. For
information on how conference activity impacts
EasyCall Gateway performance, see Capacity
Guidelines.
Working with a Cluster
You work with a cluster by logging in to the master node.
To back up a cluster configuration
●
Go to Maintenance > Backup/Restore. Configuration settings for each node will be
backed up.
To upgrade a cluster
●
Go to Maintenance > Upgrade. Each node will be upgraded.
To view status information for each node
●
Go to the Dashboard or the Cluster Configuration - Nodes page.
To access the system log for each node
●
Go to the Dashboard.
To activate or suspend a node
●
Go to the Cluster Configuration - Nodes page and click the Activate Node or Suspend
Node link.
To disconnect a node
●
100
Go to the Cluster Configuration - Nodes page, select the checkbox for the node, and
click Disconnect Node. For more information, see To disconnect a member node from a
cluster.
Working with a Member Node
You log in to a member node only if you need to perform the following tasks:
●
Restart or shut down a member node.
●
Use network diagnostic tools on a member node.
●
Promote a member node to a master node, as described in To promote a member node
to a master node.
To back up, restore, or upgrade a member node, see Working with a Cluster.
101
To disconnect a member node from a
cluster
You might need to disconnect a node from a cluster to perform maintenance on the server
or to change its network settings. When you disconnect a member node from a cluster, it
becomes a stand-alone node. To put a stand-alone node into service, it must meet the
requirements of a master node.
1. Log in to the master node.
2. On the Cluster Configuration - Nodes page, select the checkbox for the node, and click
Disconnect Node.
3. Wait about two minutes before logging in to the stand-alone node. If the Node
Configuration page appears when you log in, log out and wait about two more minutes
before logging in to the stand-alone node.
Note: If the member node is unreachable when you disconnect it, you will not be
able to access the administration tool from it. To reach the administration tool from
the disconnected node (to add it back to the cluster or to use it as a stand-alone
node), you must remove its database from /etc/commserver/ecgdb and then restart
the node.
102
To promote a member node to a master
node
If a master node fails, you can quickly recover by promoting one of the member nodes to
master node.
●
The node that you promote to master will inherit all of the connections of the previous
master node.
●
The previous master node goes out of service and any trunks that were associated with
it are deleted from the database.
●
Any transactions that were not replicated from the old master node to its member
nodes are lost.
●
To put the old master node back into service, you must add it as a member node to a
cluster.
You might need to reimage the old master node or reset its database before you can add it
as a member node. Once a master node is taken out of service (by promoting another node
to master), the old master node retains its configuration but can no longer operate as a
master node.
1. Log in to the member node that you want to become the master node.
2. Click Node Configuration.
3. Click Promote to Master.
4. Click OK in the confirmation window. When the Administration Tool refreshes, the
promoted node appears as the master node in the Cluster Configuration > Nodes page.
103
Delivering EasyCall to End Users
These topics describe the various methods available to deliver the EasyCall client to end
users.
104
Deploying with Citrix
Receiver
Deliver the Citrix communications plug-in with Citrix Receiver.
Deploying with Citrix
Application Streaming
Deploy EasyCall through Citrix XenApp streaming.
Deploying with Citrix
XenApp Publishing or
XenDesktop
Publish EasyCall via Citrix XenApp or XenDesktop.
Supporting Users Who
Install from a
Download Page
Learn about the information needed by users who download
EasyCall from the EasyCall Gateway download page.
Deploying via Push
Installation
Deploy EasyCall to users via a push installation method.
Deploying with Citrix Receiver
Note: When EasyCall is delivered with Citrix Receiver, it is known as the Citrix
communications plug-in.
Citrix Receiver simplifies application delivery for administrators by eliminating the need to
repeatedly install and update the Citrix communications plug-in on client devices.
Administrators use the web-based Citrix Merchandising Server Administrator Console to
configure plug-ins and schedule their delivery to devices. For information about configuring
Merchandising Server, go to http://support.citrix.com/proddocs/index.jsp and expand
Receiver and Plug-ins > Merchandising ServerAdministration.
Instead of installing the Citrix communications plug-in on the client device, the end user
installs Citrix Receiver, which then transparently installs and updates the Citrix
communications plug-in as scheduled by the administrator.
105
Deploying with Citrix Application
Streaming
You can deploy EasyCall through Citrix XenApp streaming. Application streaming enables
applications to be delivered to client devices and run in a protected, virtual environment.
Applications are managed in a centralized Application Hub, but are streamed to the client
device and run in an isolation environment. Applications become an on-demand service that
is always available and up to date.
Profiling the EasyCall Client
1. To start the Citrix Streaming Profiler, click the Windows Start menu and choose
Programs > Citrix > Streaming Profiler > Streaming Profiler.
2. Click the toolbar button to start the New Profile Wizard.
3. Enter the Profile Name (CitrixEasyCall in this example) and then click Next. When
naming a profile, choose a simple name. Do not include any criteria the client uses to
identify targets. For example, do not include a version number in the profile name.
4. Accept the default of Enhanced Security and then click Next.
5. Select each operating system on which EasyCall will run and select the target
language(s). Click Next. The target operating system should be the same as the one you
are using for profiling.
6. Select Advanced Install and then click Next.
7. Accept the default of Run install program or command line script and then click Next.
8. Click Browse, navigate to Citrix EasyCall Plug-in.msi, and click Next.
9. Click Launch Installer and follow the instructions in the InstallShield Wizard.
10. Enter the EasyCall Gateway host name or IP address and click Install.
11. After you click Install, a status message in the notification area indicates that EasyCall
is running. Right-click the EasyCall icon and select Exit.
12. In the New Profile Wizard, select Finish installation and then click Next.
13. On the Run Application page of the wizard you can run EasyCall in the profiler to verify
that it is working as expected. Select Next and then Finished.
14. On the Select Applications page, click Next.
15. On the Build Profile page, click Finish.
106
Deploying with Citrix Application Streaming
Adding a Pre-Launch Script
Next you will add a pre-launch script that installs the required 2008 Microsoft Visual C++
Redistributable. By using a pre-launch script in the profiler, the required redistributable
will be installed before EasyCall is run.
1. In the Streaming Profiler window, open the Edit menu and select Profile Properties.
2. In the navigation pane, click Pre-launch and Post-exit Scripts and then click Add Item.
3. In the Add Script dialog, click Do not isolate script to ensure that the redistributable is
installed to the client machine and not in the isolation environment.
4. In the Add Script dialog, click Browse, locate the script, and click Open. The script
name appears in the Pre-launch scripts list.
5. Click Apply and then click OK. Your profile is now complete.
6. Select File > Save As. In UNC Path, enter \\path and then click Save.
7. After you create a profile, make it available for publishing by saving it to a network file
share.
Saving the Profile to a File Share
When saving a profile to a file share, enter for UNC Path the path to the network file share
where you want to store the profile. Note that Save To displays the location where you are
saving the profile based on what you provide for the UNC path and the name you provide
for the profile. Here is an example of what might be entered for the UNC path:
\\citrixserver\profiles
Here is the actual storage location based on the values of UNC Path and Profile Name:
\\citrixserver\profiles\EasyCallGateway\EasyCallGateway.profile
You can also at this point change the name of the profile.
After you save your profile to a file share, you can use other workstations to add unique
targets to the profile.
System Drive Letter
For best practices, Citrix recommends that you install all applications on the primary
system drive. By packaging and executing using the primary system drive, you can define a
set of criteria that best associates a given target with a given client workstation.
The system drive letter must be a match between the target and the client system drive for
a target to be the correct match for executing an application. There is no provision for the
client drive to be variable. The system drive used on the profiler workstation must match
the system drive on the execution workstation.
107
Deploying with Citrix XenApp Publishing
or XenDesktop
You can publish EasyCall via Citrix XenApp or XenDesktop, just as you would any other
application.
1. Install EasyCall on the XenApp Server.
2. Set the user permissions for EasyCall.
108
Supporting Users Who Install from a
Download Page
End users can download and install the EasyCall client from a download page. The EasyCall
Gateway host name is automatically pre-populated in the configuration dialog box. The
download page also provides access to the EasyCall demo.
You must provide the following information to users so that they can access and use the
download page:
109
●
The download page is located at https://gatewayAddress/download. Users need to
know the gatewayAddress or host name of the EasyCall Gateway.
●
Users who have disabled JVM or the execution of embedded code can download the
installer but not run it from the download page. The EasyCall Gateway host name will
not be automatically pre-populated.
Deploying via Push Installation
You can deploy EasyCall by downloading the installer from the download page and then
pushing the client to users via a push installation method such as the Microsoft Systems
Management Server (SMS).
To update the MSI file with your EasyCall Gateway hostname, use the following
command:
msiexec /i path_to_MSI_file HOST="\hostname"
110
Managing EasyCall Conferences
The EasyCall conference feature enables EasyCall users to create and join conference calls
through simple web-based screens. To create a conference, the conference chair enters a
subject for the conference and then invites participants through an automatically
generated email which the conference chair can change.
To join a conference, a participant clicks the conference URL in the email and follows the
on-screen instructions.
For information about creating and joining conferences, refer to the Help available from
the EasyCall client.
EasyCall Conference has the following operating characteristics:
●
Requires that a browser's email client is configured.
●
After 2 hours, conference participants are prompted to continue. All participants can
choose to continue or leave the call.
●
A user can participate in an unlimited number of conferences.
●
Participant user names and phone numbers are saved to the CDR for billing and
monitoring purposes.
These topics describe conference operation and administration:
111
Controlling Access to
Conference Creation
Prevent users from creating conference calls.
To specify the URL
used for conference
pages
Specify a public domain or public IP address used to create URLs
to conference pages.
To configure a
conference dial-in
number
Configure a conference dial-in number, useful when a user does
not have web access.
To limit the
conference activity
per node
Change the conference activity maximums.
To delete conference
calls
Delete selected or all conferences.
Controlling Access to Conference
Creation
You can prevent a group of users from creating conference calls as follows.
Note: To make EasyCall conferencing available to users outside of your firewall, you must
configure a Web proxy to (1) forward https requests for EasyCall from external parties to
the EasyCall Gateway and (2) route the client responses back to the external parties.
1. Configure a group that does not include the CONFERENCE role, as described in To add a
group.
2. Associate that group with one or more directory sources, as described in To configure
an LDAP/AD directory source.
112
To specify the URL used for conference
pages
When you create a conference, EasyCall generates a conference URL used for the Join
Conference page. The conference URL is included in the email invitation automatically
composed by EasyCall. The conference URL includes an External Cluster Address, which you
must configure.
1. Log in to the master node and click Cluster Configuration.
2. Click Cluster.
3. Specify an External Cluster Address, which is a public domain or public IP address used
to create URLs to conference pages. The External Cluster Address must be forwarded to
a static IP address of one of the cluster nodes. Important: The node which services the
External Cluster Address must have a valid SSL certificate to avoid certificate warnings
from web browsers.
4. Click Submit.
113
To configure a conference dial-in number
EasyCall users typically initiate a conference call through the EasyCall user portal web
page. However, for cases in which an EasyCall user wants to start a conference but does not
have web access, you can configure a dial-in number. When an EasyCall user calls the
dial-in number, the user must enter a conference ID and PIN.
Note: The Conference Dial-in Number must be set up from your telephony system so that
it knows how to route all calls to the number to your EasyCall Gateway.
1. Log in to the master node and click Cluster Configuration.
2. Click Cluster.
3. Specify the Conference Dial-in Number and Conference Extension and click Submit.
114
To limit the conference activity per node
For information on how conference activity impacts EasyCall Gateway performance, see
Capacity Guidelines.
1. Log in to the master node and click Cluster Configuration.
2. Click Cluster.
3. Change the values for Maximum Number Per Node of Conferences and Maximum
Number Per Node of Conference Participants and click Submit.
115
To delete conference calls
The administration tool displays conferences by conference name. From that page you can
delete selected or all conferences.
1. In the administration tool, click Conferencing.
2. Select the checkbox beside each conference name you want to delete. To select all
conferences, click the checkbox at the top of the list.
3. Click Delete.
116
Maintaining and Monitoring the EasyCall
Gateway
These topics describe how to maintain and monitor the EasyCall Gateway:
117
To change the root
administrator
password
Change the default administrator password.
To set the date and
time
Change the default NTP server or enter the date and time
manually.
To back up or restore
the configuration
Save the gateway configuration and restore a saved
configuration.
To upgrade EasyCall
Read about the eligibility requirements for upgrading the
EasyCall Gateway and about upgrading the client if you do not
use Citrix Receiver.
To restart or shut
down the EasyCall
Gateway
Learn the proper way to shut down the gateway and an
alternate method for restarting.
To export or delete
CDRs
Learn about Call Detail Records and how to export and delete
them.
To get information
about the EasyCall
Gateway
Read about the information provided on the Dashboard.
To use network
diagnostic tools
Read about the ping, traceroute, and tcpdump tools available
from the administration tool.
Working with the Call
and System Logs
View recent call activity; view, open, download, and interpret
the system log.
To change the root administrator
password
The default user name for the EasyCall Gateway is "root" and the default password is
"rootadmin". We recommend that you change the root password during the installation
process by using the Maintenance > Password page.
The password, which can contain special characters, must have:
118
●
At least eight characters.
●
At least one capitalized letter.
●
At least one number.
To set the date and time
By default, the EasyCall Gateway uses the time.nist.gov NTP (Network Time Protocol)
server. Use the Maintenance > Date/Time page to specify a different NTP server or enter
the date and time manually if the EasyCall Gateway cannot reach a time server.
Note: The EasyCall Gateway defaults to the GMT0 time zone. The EasyCall Gateway
stores all time stamps in UTC (Coordinated Universal Time) format, regardless of the
Time Zone setting.
Complete the settings on the Date/Time page as described in the following table.
119
Setting
Description
Time Zone
Needed only if you choose Manually from the Set Time
list.
Set Time
Specifies the method for updating the date and time on
the appliance, either via an NTP server or manually.
Time Server
The fully qualified domain name of an NTP server. For a
list of time servers, see
http://ntp.isc.org/bin/view/Servers/WebHome. This
field is initialized to the time.nist.gov time server.
Use Privileged Port
Appears if you select Use Time Server from the Set Time
list. Select if you have opened a port in your firewall for
NTP.
Update Schedule
The frequency with which the appliance synchronizes
with the time server.
Local Date/Time
Appears if you select Manually from the Set Time list.
The on-screen example shows the required syntax.
To back up or restore the configuration
Before upgrading or reinstalling the EasyCall Gateway software, save your configuration.
Upgrading and reinstalling the software returns the appliance to its pre-configured state. If
you have saved your configuration settings, you can easily restore them.
To back up the configuration
1. Click Maintenance > Backup/Restore.
2. Click Backup to create the backup file.
3. Click Download to download the backup file. You will be prompted to open or save the
file. Click Save. The default filename is backup.tar.gz. You can change the name,
provided that you retain the extension tar.gz.
4. Choose a download location and click Save.
To restore a saved configuration
1. Click Maintenance > Backup/Restore.
2. Click Browse, locate the backup file, and then click Open.
3. Click Restore to upload the file. After the configuration file is uploaded, the EasyCall
Gateway restarts.
120
To upgrade EasyCall
The server software that resides on the EasyCall Gateway can be upgraded when new
releases are made available. You will be notified about server software upgrades. You can
upgrade to a new release only if you have a current Citrix Subscription Advantage
membership when the update is released. Subscription Advantage can be renewed at any
time. For more information, see the Citrix Support Web site at
http://support.citrix.com/licensing/ under the “Top Licensing Resources” title.
If you do not use Citrix Receiver to deploy the communications plug-in, you must upgrade
the client software that resides on the EasyCall Gateway. This topic covers both server and
client upgrades.
To upgrade the EasyCall Gateway from Release 3.0 to
3.0.1
Note: When you upload a server upgrade, the EasyCall Gateway drops the active sessions,
so it is best to upgrade the appliance when you know that traffic is at a minimum.
1. Download the RPM files from the Citrix support site.
2. Log in to the EasyCall Gateway Administration Tool.
3. Go to Maintenance > Upgrades.
4. Click Browse, navigate to the downloaded files, choose one of the upgrade RPM files,
and click Open. We recommend upgrading with the RPMs in the following order:
a. citrix-base-ecg-3.0.1-xxx.i386.rpm
b. citrix-apps-ecg-3.0.1-xxx.i386.rpm
5. Click Upgrade to upload the file.
6. Repeat Steps 4, 5 and 6 for both of the files.
After upgrading from Release 3.0 to 3.0.1:
121
●
To log in to the administration tool, use the new URL https://gatewayAddress/admin.
To log in to the EasyCall user portal, use the new URL https://gatewayAddress. (The
URL https://gatewayAddress/userPortal also still works.)
●
If your site does not use Citrix Receiver, use the new Maintenance > Clients page to
upgrade the EasyCall client on the EasyCall Gateway. Use the force upgrade option to
ensure that all users are upgraded to the latest EasyCall. The Dashboard page shows the
Mac and Windows client versions loaded on the EasyCall Gateway.
●
If your telephony system does not allow re-INVITEs to be sent, use the new Can Send SIP
Re-INVITEs setting on the Cluster Configuration > Trunks page to allow the telephony
system to drop out of the call after bridging it.
To upgrade EasyCall
To upgrade the EasyCall Gateway from Release
2.1/2.2.x to 3.0.1
Note: When you upload a server upgrade, the EasyCall Gateway drops the active sessions,
so it is best to upgrade the appliance when you know that traffic is at a minimum.
Verify that your EasyCall Gateway is running release 2.1 or 2.2.x before proceeding. The
following instructions apply only to upgrades from release 2.1/2.2.x to 3.0.1. Contact
support before upgrading older releases.
1. If there were any customization done to the configuration XML files (such as special
recognition rules), make sure that you have a backup copy. You will need to upload
those files again after the upgrade.
2. Download the RPM files from the Citrix support site.
3. Log in to the EasyCall Gateway Administration Tool.
4. Go to Maintenance > Upgrades.
5. Click Browse, navigate to the downloaded files, choose one of the upgrade RPM files,
and click Open. We recommend upgrading with the RPMs in the following order:
a. citrix-base-ecg-3.0.1-xxx.i386.rpm
b. citrix-apps-ecg-3.0.1-xxx.i386.rpm
6. Click Upgrade to upload the file.
7. Repeat Steps 4, 5 and 6 for both of the files.
8. Go to Maintenance > Upgrades and click Restart.
Tasks to Perform After Upgrading from Release
2.1/2.2.x
After you upgrade the EasyCall Gateway from Release 2.1/2.2.x, log in to the
Administration Tool and perform the following tasks.
1. Specify the Conference Dial-in Number and Conference Extension on the Cluster
Configuration > Cluster page. The Conference number and extension can be used by
EasyCall users who want to start a conference but do not have Web access. Note: The
Conference Dial-in Number must be set up from your telephony system so that it knows
how to route all calls from that number to your EasyCall Gateway.
2. Add Groups and set the Group Policy on the Directory Source Configuration > Groups
page.
3. Update your directory sources on the Directory Source Configuration > Directory
Sources page. Specify the priority of directory sources by using the Up and Down links.
If you prefer to review the results of a synchronization without having user information
overwritten, change the Directory Source Setting to Never overwrite.
122
To upgrade EasyCall
4. For each directory source, do the following:
a. Specify the User Domain Prefix for users in the directory source.
b. If you want the directory source to apply to a specific node or trunk, make a
selection from the Node Name or Trunk Name menus.
c. Specify a Group for the directory source.
5. Configure Call Forwarding:
a. Determine if your telephony system supports redirection. For example, SIP carriers
do not support this feature.
b. Refer to the EasyCall Gateway Telephony System Integrator's Guide for your
telephony system for any configuration needed to support Call Forwarding. Those
guides are available from http://support.citrix.com/product/cg (follow the links to
the release and Documentation).
c. Verify that the Extension attribute is defined on the LDAP Directory Source
Configuration - Details Configuration page. (If the extension is provided in the
work phone field only, Call Forwarding will not work.)
d. Enable the Use Diversion option on the Add/Edit Trunk page.
e. Specify the Voice Mail Extension on the Cluster Configuration > Trunks tab. The
Voice Mail Extension is used to forward a call to voice mail when an EasyCall user
with Call Forwarding enabled does not answer any of the configured phone
locations.
6. Configure Net Call: Specify the alias and phone number for any numbers that you want
to include on your Web site on the Net Call Configuration page.
7. Also, refer above to the items in "After upgrading from Release 3.0 to 3.0.1."
Upgrading the EasyCall Plugin
Make sure that your users are aware of what they need to do to upgrade EasyCall, as
follows.
●
Although Citrix Receiver users do not have to do anything to receive upgrades, they
must quit the previous EasyCall client for the upgrade to take effect.
●
Users who self-installed can upgrade EasyCall by going to the download page at
https://EasyCallServer/download/win.jsp or
https://EasyCallServer/download/mac.jsp. To look up the EasyCallServer, Windows
users can choose Edit Settings from the EasyCall menu. Mac users can choose
Preferences and then click Login Settings.
Note: Windows users who have disabled JVM or the execution of embedded code can
download the installer but not run it from the download page. The EasyCall Gateway
host name will not be automatically pre-populated.
●
123
To support your EasyCall users, also be aware of this issue: In Windows XP Service Packs
2 and 3 and Windows Server 2003, overlapping layered windows are not displayed in the
correct order and can cause display problems when using EasyCall. A hotfix released by
To upgrade EasyCall
Microsoft resolves this issue. The hotfix and more information about this issue are
available from http://support.microsoft.com/kb/943326/en-us
●
Users obtaining the Setup.exe installer from the Citrix support site can perform an
attended or silent install as follows:
●
To install EasyCall by running an attended installation program, double-click the
Setup.exe file to launch the installation program.
●
To install EasyCall silently (unattended), open the Command Prompt window,
navigate to the directory where you copied Setup.exe, and enter:
setup.exe /S /v"/qn HOST=EasyCall_Gateway_Host_Name
For example, if the host name is easycall.net, you would enter:
setup.exe /S /v"/qn HOST=easycall.net
If you do not use Citrix Receiver to deploy the communications plug-in, update the client
version that resides on the EasyCall Gateway as follows:
1. Download the client upgrade files (for Mac and Windows) from the Citrix support site.
2. Log in to the EasyCall Gateway Administration Tool.
3. Go to Maintenance > Clients.
4. Following the instructions on the Windows and Mac tabs, complete the fields, navigate
to the upgrade files, and then click Upgrade.
124
To restart or shut down the EasyCall
Gateway
To restart the EasyCall Gateway
After making changes to the EasyCall Gateway, you might need to restart the server.
1. Click Maintenance > Services.
2. Under Server Control, click Restart. You can also use the Reset button on the front of
the EasyCall Gateway to perform a soft reboot.
To shut down the EasyCall Gateway
Never shut down the EasyCall Gateway by powering it off. Use the administration tool to
shut down the device. Use the power switch only to power on the device.
1. Click Maintenance > Services.
2. Under Server Control, click Shut Down.
125
To export or delete CDRs
A Call Detail Record (CDR) is a file that contains information about calls placed through the
EasyCall Gateway. Information provided in the CDRs can be used for billing calls to cost
centers and for auditing potential abuse.
When the CDR table reaches 10 million records, the oldest record in the table is deleted
each time a new record is created. You can also delete all CDRs through the administration
tool.
You can export CDRs to a comma-separated values (CSV) format from the administration
tool. The default filename is cdr.csv; it contains the following columns:
Column Name
Description
Max.
Length
CALL_START_TIME
String. The date and time that the call
originated. Formatted as mmm dd yyyy
hh:mm:ss zzz. For example, Sep 3 2008 15:54:03
PDT.
24
CALL_END_TIME
String. The date and time that the phone call
was ended. Formatted as mmm dd yyyy
hh:mm:ss zzz. For example, Sep 3 2008 15:54:03
PDT.
24
CALL_DURATION_SEC
String. The length, in seconds, of the call
connection.
24
Call duration begins when the call is connected
to the call originator’s phone. Thus a call that
fails in waiting for caller input will have a
non-zero duration.
126
FROM_NUMBER
String. The phone number from which the call is
dialed.
64
TO_CALL_ID
String. The phone number displayed on the
target phone. This is the caller’s phone number
Call ID.
128
TO_NUMBER
String. The telephone number that was called
(as dialed).
64
FROM_CALL_ID
String. The call ID seen on the target phone as
the number called. Also referred to as the
“fromCallID.” Call IDs do not represent the
actual number dialed. That is, they would not
show the trunk access code 9, for example.
128
USERNAME
String. The domain logon name of the user who
made the call. Required for the Call Detail
Record associated with the call.
515
CLIENT_IP_ADDRESS
String. The caller’s IP Address.
64
To export or delete CDRs
TERM_CAUSE_CODE
The call termination reason from the ISDN cause
code.
24
TERM_CAUSE_STATE
String. The last call state (provided by the
EasyCall Gateway):
24
NEW_CALL
CALLER_PARTY_RINGING
WAITING_FOR_CALLER_INPUT
CALLED_PARTY_RINGING
CALL_CONNECTED
CALL_DESCRIPTION
String. Allows a client to record any information
related to the call in the click-to-call request.
This information will be stored in the CDR for
that call. If the CDR is for a conference
participant, the conference name will be stored
in the call description.
CALL_GUID
String. A unique ID number assigned to a call.
Sample entries from a cdr.csv file follow:
256
128
CALL_START_TIME,CALL_END_TIME,CALL_DURATION_SEC,FROM_NUMBER,TO_CALL_ID,TO_NUMBER,
FROM_CALL_ID,USERNAME,CLIENT_IP_ADDRESS,TERM_CAUSE_CODE,TERM_CAUSE_STATE,
CALL_DESCRIPTION,CALL_GUID
Jan 17 2008 17:39:25 PDT,Jan 17 2008 17:39:40 PDT,15.183,95558950,14085558950,919257882620,192578826
Jan 13 2008 15:20:05 PDT,Jan 13 2008 15:20:12 PDT,6.712,95558948,14085558948,912092679100,1209267910
Jan 13 2008 14:17:44 PDT,Jan 13 2008 14:18:09 PDT,25.195,912345678901,12345678901,91234567890,123456
Jan 13 2008 10:36:20 PDT,Jan 13 2008 10:37:42 PDT,81.818,912147707954,12147707954,912145031688,12145
Jan 11 2008 12:44:01 PDT,Jan 11 2008 12:44:17 PDT,15.575,95558948,14085558948,21950,21950,,CN=Mandy
To export CDRs
1. In the administration tool, click Maintenance > CDR.
2. Specify the start and end dates for the records to be exported.
3. Click Export.
4. Specify an export location and click Save.
Note: Excel displays a FROM_NUMBER or TO_NUMBER that exceeds eight digits as long
numbers (for example, 919257851234 displays as 9.19258E+11). To correct the display
in Excel, select the column, right-click it, and choose Format Cells. In the Number
tab, change the Category to Number, with 0 decimal places.
127
To export or delete CDRs
To delete all CDRs
1. In the administration tool, click Maintenance > CDR.
2. Click Delete All and then respond to the prompt to verify the deletion. All CDRs are
deleted.
128
To get information about the EasyCall
Gateway
The EasyCall Gateway Dashboard page displays the information described in the following
table.
Setting
Click-to-Call Usage
Conference Usage
User Information
Client Version Information
129
Description
●
The number of click-to-call requests received by the
EasyCall Gateway since it was started.
●
The number of calls successfully connected (including
calls answered by voice mail) since the Gateway was
started.
●
Total number of Click2Call call legs. Note that two
Click-to-Call call legs count as one phone call. For SIP
trunks, the count includes both calls in progress and
connected calls.
●
The number of conference call requests received by
the EasyCall Gateway since it was started.
●
The number of conference calls successfully
connected since the Gateway was started.
●
The number of conference calls in progress.
●
The number of conference participants on in progress
conference calls.
●
The number of logged in users.
For the Windows and the Mac plug-ins:
●
The client version loaded on the EasyCall Gateway.
●
Whether the client on user computers will be
automatically upgraded. To change the related
setting, go to the Maintenance > Clients page, select
the Force client to upgrade setting, and upload the
client upgrade file again.
●
When a new client was last uploaded to the EasyCall
Gateway.
To get information about the EasyCall Gateway
Telephony Service Status:
Node Status
Telephony Service Status:
Trunk Status
Server Uptime
130
●
The node name, IP address, and type. Click the node
name to view its system log.
●
The node capacity.
●
The node status: ACTIVE or SUSPENDED.
●
The EasyCall Gateway software version running on the
node.
●
The trunk and node names. Click the trunk name to
view its status.
●
Protocol being used.
●
The trunk capacity.
●
The IP address of the telephony system.
●
The trunk status: ACTIVE or SUSPENDED. When the
telephony service is stopped, dialing from EasyCall
and EasyCall Web Services is unavailable.
●
The number of seconds since the service was started.
To use network diagnostic tools
The Monitoring > Network Tools page provides the following tools:
●
Ping
Ping tests the network connection between the EasyCall Gateway and the device that
you specify.
If the two devices are successfully communicating, messages indicate that the same
number of packets were transmitted and received, and zero packets were lost.
If the two devices are not successfully communicating, messages indicate that zero
packets were received and all the packets were lost.
●
Traceroute
Traceroute checks the network connection between the EasyCall Gateway and the
destination host that you specify. After it determines the address of each network hop
between the devices, traceroute sends a sequence ICMP ECHO request to each one to
determine the quality of the link to each device. Traceroute prints running statistics
about each device.
●
Network Capture
Network Capture logs network activity using tcpdump. Network Capture is available
only if the Trunk Type on the Trunk Configuration page is set to SIP. After you start
the Network Capture, you can perform needed tests, stop the capture, download the
file, and then use third-party tools to analyze the data.
131
Working with the Call and System Logs
To view the most recent call activity
●
In the administration tool, click Monitoring > Call Log.
To view the system log
●
In the administration tool, click Monitoring > System Log. Click Refresh to update the
display.
System message logs contain information that can help technical support personnel
assist you with troubleshooting. The EasyCall Gateway uses syslog to generate log files,
enabling you to manage and view the system logs with familiar third-party tools. The
log levels included are warning, error, and critical.
Much of the information in the system log is informational and can be ignored. Errors at
the beginning of the log do not necessarily indicate problems with the EasyCall
Gateway. However, a log of only a few lines upon startup of the EasyCall Gateway
indicates a possible problem with the logging service. If the initial log does not include
at least 50 or so entries, restart the server. If that does not correct the problem,
contact your support representative.
To open or download the system log
●
In the administration tool, click Monitoring > System Log, click Download, and then
click Open (to open the log in Notepad) or Save.
The EasyCall Gateway displays the most recent activity when the entire log is too large
to display.
132
Using the Web Services API to Build Web
Apps
You can use the EasyCall Web Services APIs to build Web applications that enable users to:
●
Place calls by clicking a telephone number displayed in a Windows application. Clients
use the Telephony Web Service to manage click-to-call requests and responses.
●
Set up and join ad-hoc conference calls. Clients use the Telephony Web Service to
manage conference call setup and initiation.
●
Search a corporate directory for contact information by clicking a directory entry on a
web page. The phone number returned in the contact information could then be used
to initiate a call. Clients use the Directory Web Service to acquire directory information
used to look up user phone numbers or telephony system extensions. Clients use the
Directory Web Service to load a directory on the EasyCall Gateway and enable directory
searches.
The web services APIs are published via the XML-based Web Services Description Language
(WSDL) so that external clients can access the web services via standard Simple Object
Access Protocol (SOAP) requests.
These topics provide the information you need to use the EasyCall Web Services APIs.
EasyCall Web Services
Learn about the telephony and directory web services, including
the APIs that they use and how they handle requests.
Data Types Available
to Web Services APIs
Get information about the data types available to the Web
Services APIs.
Versioning API
Look up details about the methods available for each API, along
with the request and response parameters for each method.
Authentication API
Telephony Client API
Call Detail Record
(CDR) API
Directory API
Locations API
Global Properties API
WSDLs and Example
Code
133
Access links that open WSDL files and sample Java code for the
web services.
EasyCall Web Services
Telephony Web Service
The Telephony Web Service leverages a site’s telephony system and its Public Switched
Telephone Network (PSTN) connectivity. The Citrix EasyCall Gateway uses a QSIG or SIP
trunk connection to the telephony system to initiate calls to the calling and called parties.
A Telephony Web Service client uses these APIs:
●
Telephony client: manages phone calls and conference calls.
●
Call Data Records (required): stores and retrieves call data; returns call cause code.
●
Locations (required): used to maintain the locations from which a user can make calls.
Location information includes an array of location names and phone numbers.
●
Directory (optional): manages directory searches.
●
Versioning (required): provides a method for the client to dynamically discover API
versions supported by the server.
●
Login (required): used to generate a login handle. (Previously referred to as the
Licensing API.)
Click-to-call requests are handled by Telephony Web Services as follows:
1. A telephony client gets a login handle and then passes a click-to-call request to the
EasyCall Gateway.
2. The directory information is used by the Telephony Web Service to resolve user identity
to a phone number or telephony system extension.
3. The EasyCall Gateway then places an outbound call to the user extension.
4. After the user picks up the phone, the EasyCall Gateway places a call to the external
number.
5. After both parties are connected the EasyCall Gateway is released from the call path.
6. The client, optionally, can store/retrieve Call Data Records.
Directory Web Service
A Directory Web Service client enables a user to search a corporate directory for contact
information by clicking a directory entry on a web page. The phone number returned in the
contact information can then be clicked to initiate a call. A Directory Web Service client
uses these APIs:
134
EasyCall Web Services
●
Directory (required): manages directory searches
●
Versioning (required): provides a method for the client to dynamically discover API
versions supported by the server.
●
Login (required): used to grant access to the Web Services. (Previously referred to as
the Licensing API.)
Directory requests are handled by Directory Web Services as follows:
1. A directory client gets a login handle and then passes a directory search request to the
EasyCall Gateway.
2. The EasyCall Gateway performs the search and returns results.
135
Data Types Available to Web Services
APIs
All data types are defined in the WSDLs. The data types available to the Web Services APIs
are described in the following topics.
Call Detail Record (CDR)
A Call Detail Record (CDR) object contains the following information about a call. These
parameters are provided by the Click2Call request and are returned by the
getCDREntriesByIndex and getCDREntryByCall requests.
Name
Description
Max.
Length
StartDateTime
Long; signed 64-bit value. The date and time that the
call originated. Formatted as mmm dd yyyy hh:mm:ss
zzz. For example, Sep 3 2008 15:54:03 PDT.
EndDateTime
Long; signed 64-bit value. The date and time that the
phone call was ended. Formatted as mmm dd yyyy
hh:mm:ss zzz. For example, Sep 3 2008 15:54:03 PDT.
FromNumber
String. The phone number of the caller (the first leg of
the call).
64
FromCallID
String. The caller ID of the caller (first leg of the call).
Call IDs do not represent the actual number dialed.
That is, they would not show the trunk access code 9,
for example.
127
TermCauseCode
String. Either CANCELLED if the call was cancelled by
the user or a standard ISDN termination cause code.
(Your switch vendor can provide a list of code
translations.)
127
TermCauseState
String. State the call was in when it ended. One of the
following:
127
NEW_CALL
CALLER_PARTY_RINGING
WAITING_FOR_CALLER_INPUT
CALLED_PARTY_RINGING
CALL_CONNECTED
136
Data Types Available to Web Services APIs
UserName
String. The domain login name of the user who made
the call. Required for the Call Detail Record associated
with the call.
511
CallGUID
String. A unique ID number assigned to a call.
64
ClientIPAddress
String. The IP address of the caller. Required for the
Call Detail Record associated with the call.
64
ToNumber
String. The telephone number that was called (as
dialed).
64
ToCallID
String. The phone number displayed on the target
phone. This is the caller’s phone number Call ID.
127
CallDescription
String. Allows a client to record any information related
to the call in C2C request. This information will be
stored in the CDR for that call. If the CDR is for a
conference participant, conference name will be stored
in the call description.
255
DirectoryEntry
A DirectoryEntry object contains the following information. These parameters are returned
with the getDirectoryEntriesByIndex request.
Name
Description
Max.
Length
userName
String. The user’s domain logon name. Must be unique.
511
displayName
String. User information.
100
firstName
50
lastName
50
title
127
department
127
telephone1
String. These are telephone number and label pairs.
64
telephone2
64
telephone3
64
UserLocations
A UserLocations object contains the following information. These parameters are returned
with the getUserLocations, getUserNameLocations and updateUserLocations
requests.
137
Name
Description
Max.
Length
defaultProfileName
String. Default location for this user.
127
Data Types Available to Web Services APIs
restricted
Boolean. Controls whether this user is allowed to
update locations. (A user can always update the default
location.)
defaultCountryCode
String. Can be updated through
updateDefaultCountryCode.
127
defaultAreaCode
String. Can be updated through
updateDefaultAreaCode.
127
defaultLocationName String.
locations
Array of location entries (LocationEntry).
userName
String.
LocationEntry
A ProfileEntry object contains the following information for a user. These parameters are
provided with the AddProfileEntry request and are returned with the
GetProfileEntries request.
138
Name
Description
Max.
Length
locationName
String. A label for the location, such as “office” or
“mobile”.
127
phoneNumber
String. The number to dial to reach this location.
64
enableCallerID
Boolean. Controls whether this location phone number
is displayed in the caller ID when dialed.
Versioning API
The Versioning API provides a method for the client to dynamically discover API versions
supported by the EasyCall Gateway. In addition, the Authentication API also provides
methods for advertising API versions supported by the clients. This allows both the client
and the server to check compatibility with the other side. The recommended flow of events
is:
1. Prior to login, the client discovers the API versions supported by the server by issuing a
GetAPIVersion() request. If none of the API versions supported by the server is
supported by the client, it does not proceed with the login.
2. When the client performs login, it advertises in the apiVersion parameter of the
Login() request the version of the web services API it will use. If the client does not
pass the apiVersion, the server assumes that the client uses version 1.0 of the web
services API. If the server does not support the API version advertised by the client, it
may respond with a INCOMPATIBLE_API_VERSION error and not issue a login handle to
the client.
GetAPIVersion method
GetAPIVersion returns a comma-delimited list of the client API versions supported by the
EasyCall Gateway. There are no request parameters.
Response Parameters
Description
apiVersion
String. For example, “3.0”. Note that the response
parameter is now “out.” “apiVersion” is for backward
compatibility.
GetClientVersion method
GetClientVersion returns the client version for a given operating system.
139
Request Parameters
Description
ClientOS
String. Either “WINDOWS” or “MAC”.
Response Parameters
Description
currentClientVersion
String. The client version, in the form of n.n.nnnn,
where the last four digits are the client build number.
forceUpgrade
Boolean. For future use. Indicates to the client
whether to perform a forced upgrade. Defaults to
false.
Versioning API
errorCode
String. One of the following:
●
SUCCESS
A client for the requested OS exists on the server.
The client version is returned.
●
SERVER_ERROR
No client is on the server for the requested OS.
140
Authentication API
Web service clients are not required to not present credentials. However, client requests
must include a login handle. A client does not look at the contents of a login handle. If a
client fails to properly renew the login handle, the session will eventually expire.
The additional objects used by the API, described next, include generic key/value pairs
which are useful for integrating the EasyCall with your authentication mechanism, as
described in Configuring Authentication.
Additional Objects Used by the API
Object class: KeyValue
Field name: key
Description: String. Generally used as a request parameter. Can also be used anywhere
that a generic key/value pair is needed.
Field name: value
Description: String. Generic value that corresponds to the key. Any object value must be
converted to a string.
Object class: NodeAddress
Field name: hostname
Description: String. The node’s hostname; returned by the Login request.
Field name: port
Description: Integer. The node’s port number; returned by the Login request.
Login method
Login is the general method called when a client negotiates its login to the EasyCall
Gateway.
A client should specify the apiVersion and KeyValue pairs when calling Login for the first
time. Subsequent processing mostly depends on the error code returned by the server.
Request parameters and descriptions:
apiVersion
String returned by GetAPIVersion.
141
Authentication API
handle
String. Unique identifier for the request. The login handle object should be used by all
subsequent communications with the server, until the Logout request is called.
KeyValue
Array of key/value pairs. The following constants are defined for the key/value pairs that
clients may send to the server:
●
user_name
The username of the user logging in to the gateway. The username must be in the
form of DOMAIN\USERNAME or USERNAME. This field is required when logging in. The
default authentication script does not validate the domain/username. If you want to
verify domain/username against an authentication mechanism, you must customize
the authentication script and implement a web services client. For information about
the script, refer to Configuring Authentication.
●
password
The MD5-encrypted password. The client can omit the password from the initial login
attempt (and send only user_name). If the server needs a password, it will return the
NEED_MORE_INFO error code.
●
plain_password
The plain text password. If the authentication server does not support MD5 password
authentication, the server may request that the password is provided in plain text.
●
redirect_count
The client must increase the redirection count to “1” any time it is following a
redirection as a result of encountering a REDIRECT result. This count should never be
set otherwise.
Response parameters and descriptions:
result
Note: Response is in the form:
loginResponse =
{
handle : string
nodeList : NodeAddress[ ]
requests : KeyValue[ ]
result : string
roles : string[ ]
}
String. One of the following:
●
SUCCESS
The client has successfully logged in to the EasyCall Gateway.
142
Authentication API
If the API version is 3.0 or over, the server will send a property back in the response,
with name `login_expire_period’, and value of the time period, in seconds, in which
the server will retire this client’s login session if it is not renewed.
●
ACCESS_DENIED
The credentials specified by the client caused the server to reject the login. This
decision is final; the client must restart login negotiations.
●
INCOMPATIBLE_API_VERSION
The client has attempted to use a version protocol that is incompatible with the
client. No further action can be taken.
●
INVALID_ARGUMENT
The client specified a value in “values” that cannot be understood by the server. The
name of the value is returned in the requests[0] key. Login negotiations must be
restarted after this, however this result code usually indicates an error in the client
logic.
●
INVALID_HANDLE
The server did not recognize the client-specified “handle” parameter in the request.
The handle might be expired. The client must restart login negotiations.
●
NEED_MORE_INFO
The server needs more information from the client to be able to log in the client.
Once the client receives this result code, it should always use the “handle” value
returned by the server along with that code in any further Login calls. The server
will send the list of required parameter names in the “requests” field. If any
parameter needs a value to be able to calculate the response, the “value” field will
be filled in for the corresponding key-value pair. The client should fill in all the
missing fields in the “values” array. The client does not need to re-transmit the
fields it has already transmitted.
●
REDIRECT
The server will not log in the client locally; the client must execute the request
elsewhere. The server will return the nodeList array consisting of a single element.
That element will contain the node address for the client to connect instead.
●
SERVER_ERROR
There was an internal unrecognized server failure attempting to log in the client.
This error usually indicates a transient error in the server, or a problem in the server
software.
●
TEMPORARILY_UNAVAILABLE
The server can not log you in at the moment. The “nodeList” structure will contain
all the nodes that are currently available in the cluster. The current node will not be
in that list. The client should pick a different node from the list and attempt to log
in to that node.
143
Authentication API
handle
String. The login handle.
requests
Array of KeyValue pairs. The following key-value pair may be in the server response:
●
login_expire_period
The login expiration period in seconds. The login handle must be renewed by the
client before this period expires.
●
cluster_external_address
The external IP address (such as 1.2.3.4:433) or domain name to use for the cluster
when directing the user to the user portal.
nodeList
Array of the latest list of known node addresses for this cluster. The list includes the
node to which the client is connected.
roles
An array of the operations that are allowed for the client. The following roles are
currently defined for the client:
●
CALL
The client is allowed to place calls.
●
CONFERENCE
The client is allowed to create conferences.
●
CREATE_LOCATIONS
The client is allowed to add/edit locations.
●
FIND_ME
The client is allowed to redirect a telephony system extension to a sequence of
locations which are tried sequentially.
●
VOIP
Not supported in this release. The client is allowed to create, register, and manage
unlimited mobile SIP or IAX locations (extensions) per user with this role.
The CALL and CONFERENCE values provide the following permissions:
CALL
Full EasyCall capabilities; cannot create conferences.
CALL and CONFERENCE
144
Authentication API
Full EasyCall capabilities; can create conferences.
None
EasyCall will not start.
Renew20 method
The Renew20 call renews the login handle. Client login handles expire after a maximum of
60 seconds, thus they must be renewed.
Request parameter and description:
handle
String. The login handle.
Response parameter and description:
result
String. One of the following:
●
SUCCESS
The handle has been successfully renewed. The client can continue to use it.
●
INVALID_HANDLE
The specified handle was invalid, or was declared invalid during execution of this
call. The client should attempt to log in again.
●
SERVER_ERROR
There was an internal error executing this call. The client could trying logging in to
the server again.
Logout method
The Logout call logs out the specified handle. There are no response parameters.
Request parameter and description:
handle
String. After logout, this login handle cannot be used for any other call.
145
Telephony Client API
Click2Call method
Click2Call passes a phone call request from a client to the EasyCall Gateway.
Click2Call returns a call handle that is valid while the call is on the EasyCall Gateway.
During that time, the call handle can be used to return real-time call status or to cancel the
call. When the call ends, the call handle becomes invalid and the call termination cause
can be retrieved from the Call Detail Record in the database, via GetCDREntryByCall.
Request Parameters
Description
handle
String. The login handle.
location
String.
phone
String. The phone number being called.
locale
One of the following three-letter codes:
ENG: International English
ESP: Spanish
DEU: German
FRA: French
Locale value defaults to ENG.
146
description
String.
Response Parameters
Description
callHandle
String. Is returned if the call is successful and Is empty
if the call fails. The callHandle is required to get call
status or to cancel the call.
errorCode
String. One of the following:
●
INVALID_USER
●
TELEPHONY_SERVER_ERROR
Telephony Client API
GetCallStatus method
GetCallStatus reports the status of a call. An invalid call handle may be an indication
that the call has ended or that the EasyCall Gateway has been removed from call path due
to path replacement. Status of the ended call is available after the telephony system has
returned the call handle; use the CDR web service call GetCDREntryByCall.
Request Parameters
Description
callHandle
String.
Response Parameters
Description
callStatus
String. One of the following if the errorCode is
SUCCESS:
errorCode
●
NEW_CALL
●
CALLER_PARTY_RINGING
●
WAITING_FOR_CALLER_INPUT
●
CALLED_PARTY_RINGING
●
CALL_CONNECTED
String. One of the following:
●
SUCCESS
●
INVALID_CALL_HANDLE
●
TELEPHONY_SERVER_ERROR
CancelCall method
CancelCall terminates a call request.
147
Request Parameters
Description
callHandle
String.
Response Parameters
Description
Telephony Client API
errorCode
148
String. One of the following:
●
SUCCESS
●
INVALID_CALL_HANDLE
●
TELEPHONY_SERVER_ERROR
Call Detail Record (CDR) API
findCDREntries method
findCDREntries returns the number of CDRs for a particular user. You can optionally
filter the results by specifing a start and/or stop date/time.
Request Parameters
Description
licenseHandle
String.
startDateTime
(Optional) Integer.
endDateTime
(Optional) Integer.
Response Parameters
Description
numberOfMatches
Integer. Returned if the errorCode is SUCCESS. Use
getCDREntriesByIndex to obtain a subset of the
matches.
CDRSearchHandle
String. Returned if the errorCode is SUCCESS.
errorCode
String. One of the following:
●
SUCCESS
●
NO_MATCHES_FOUND
●
DB_SERVER_ERROR
●
INVALID_HANDLE
●
INVALID_DATE
getCDREntriesByIndex method
getCDREntriesByIndex returns an array of Call Detail Records.
149
Request Parameters
Description
searchHandle
String.
startIndex
Integer.
endIndex
Integer.
Call Detail Record (CDR) API
Response Parameters
Description
CDR[ ]
Array of CDR records is returned if the errorCode is
SUCCESS.
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_SEARCH_HANDLE
●
INVALID_INDEX
●
DB_SERVER_ERROR
releaseSearchHandle method
releaseSearchHandle checks in the search handle, indicating that the client is finished
with the directory search.
Request Parameters
Description
searchHandle
String.
Response Parameters
Description
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_SEARCH_HANDLE
getCDREntryByCall method
getCDREntryByCall returns the detailed call status of the ended call. If
GetCallStatus returns an invalid call handle (meaning that the call is no longer on the
telephony server), the client can use getCDREntryByCall for the cause of the call
termination.
150
Request Parameters
Description
licenseHandle
String.
callHandle
String.
Response Parameters
Description
CDR
Complex type. One CDR is returned if the errorCode is
SUCCESS.
Call Detail Record (CDR) API
errorCode
151
String. One of the following:
●
SUCCESS
●
INVALID_CALL_HANDLE
●
DB_SERVER_ERROR
Directory API
findDirectoryEntries method
findDirectoryEntries returns the number of search string matches in the directory
uploaded to the EasyCall Gateway directory.
Request Parameters
Description
searchText
String. The search text entered by the user. Required.
licenseHandle
String.
Response Parameters
Description
numberOfMatches
Integer. Returned if the search string is found in the
directory. Use getDirectoryEntriesByIndex to obtain a
subset of the matches.
directorySearchHandle
String. Returned if the search string is found in the
directory.
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_ENTRY
●
INVALID_LICENSE
●
NO_MATCHES_FOUND
●
DB_SERVER_ERROR
●
INVALID_SEARCH_HANDLE
●
INVALID_INDEX
●
SERVER_ERROR
getDirectoryEntriesByIndex method
getDirectoryEntriesByIndex returns returns an array of Directory entries.
152
Request Parameters
Description
searchHandle
String. Returned by findDirectoryEntries.
Directory API
startIndex
endIndex
Integer. Directory entries from startIndex (min 0) to
endIndex (max NUM_ENTRIES-1).
Response Parameters
Description
DirectoryEntry[ ]
Array of directory entries for the requested indexes.
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_INDEX
●
DB_SERVER_ERROR
●
INVALID_SEARCH_HANDLE
releaseSearchHandle method
releaseSearchHandle checks in the search handle, indicating that the client is finished
with the Directory search.
153
Request Parameters
Description
searchHandle
String.
Response Parameters
Description
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_SEARCH_HANDLE
●
DB_SERVER_ERROR
Locations API
getUserLocations method
getUserLocations returns the UserLocations object for the logged in user.
Request Parameters
Description
licenseHandle
String.
Response Parameters
Description
locations
The UserLocations entry for the user.
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_LICENSE
●
INVALID_USER
●
DEFAULTS_ONLY
●
BAD_AUTH
●
DB_SERVER_ERROR
getUserNameLocations method
getUserNameLocations returns the UserLocations object for the requested user.
154
Request Parameters
Description
userName
String. The user for which locations are to be returned.
Response Parameters
Description
locations
The UserLocations entry for the user.
Locations API
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_LICENSE
●
INVALID_USER
●
DEFAULTS_ONLY
●
BAD_AUTH
●
DB_SERVER_ERROR
updateUserLocations method
updateUserLocations returns the new UserLocations structure when the update was
successful or when an update is not allowed (for restricted users).
Request Parameters
Description
licenseHandle
String.
locations
The UserLocations entry for the user.
Response Parameters
Description
locations
The UserLocations entry for the user, if the update was
successful.
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_LICENSE
●
INVALID_USER
●
DEFAULTS_ONLY
●
BAD_AUTH
●
DB_SERVER_ERROR
updateDefaultAreaCode method
updateDefaultAreaCode updates the default area code in UserLocations.
155
Request Parameters
Description
licenseHandle
String.
Locations API
defaultAreaCode
String. Obtained from a user’s Windows configuration.
Response Parameters
Description
locations
The UserLocations entry for the user.
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_LICENSE
●
INVALID_USER
●
DEFAULTS_ONLY
●
BAD_AUTH
●
DB_SERVER_ERROR
updateDefaultCountryCode method
updateDefaultCountryCode updates the default country code in UserLocations.
156
Request Parameters
Description
licenseHandle
String.
defaultCountryCode
String. Obtained from a user’s Windows configuration.
Response Parameters
Description
locations
The UserLocations entry for the user.
errorCode
String. One of the following:
●
SUCCESS
●
INVALID_LICENSE
●
INVALID_USER
●
DEFAULTS_ONLY
●
BAD_AUTH
●
DB_SERVER_ERROR
Global Properties API
GetGlobalProperty method
GetGlobalProperty allows an EasyCall client to retrieve the following cluster-wide
properties:
●
CONFERENCE_DIAL_IN_NUMBER (the phone number that EasyCall conference users can
dial to access a conference)
●
CONFERENCE_EXTENSION (the extension that EasyCall conference users can dial to
access a conference)
●
NORMALIZER_DATA (an XML file that contains country-specific data)
●
NORMALIZER_DATA_LAST_UPDATE (the date/time of the last update of the normalizer
data XML file; shown as UNIX time)
●
NORMALIZER_CONFIG (an XML file that contains normalizer rules for telephone number
recognition, formatting, and restrictions)
●
NORMALIZER_CONFIG_LAST_UPDATE (the date/time of the last update of the
normalizer config XML file; shown as UNIX time)
Request Parameters
Description
propertyName
String. One of the following (described above):
CONFERENCE_DIAL_IN_NUMBER
CONFERENCE_EXTENSION
NORMALIZER_DATA
NORMALIZER_DATA_LAST_UPDATE
NORMALIZER_CONFIG
NORMALIZER_CONFIG_LAST_UPDATE
157
Response Parameters
Description
propertyValue
String.
Global Properties API
errorCode
158
String. One of the following:
●
SUCCESS
●
DB_SERVER_ERROR
●
PROPERTY_NOT_FOUND
WSDLs and Example Code
The following table contains the URLs where the latest Web Services Description Language
(WSDL) and test code are located for each EasyCall Web Service. In the URLs, EasyCallGW is
a placeholder for the host name or IP address of your gateway.
The example test programs use the XFire library to access the Web Services. The URL for
XFire is http://xfire.codehaus.org/.
EasyCall Web
Services
EasyCall WSDL and Test Code File Locations
Call Detail
Record
https://EasyCallGW:443/services/CDR?wsdl
https://EasyCallGW:443/docs/guides/sampleTests/CDR.java
Directory
https://EasyCallGW:443/services/Directory?wsdl
https://EasyCallGW:443/docs/guides/sampleTests/Directory.java
GlobalProperties
https://EasyCallGW:443/services/GlobalProperties?wsdl
https://EasyCallGW:443/docs/guides/sampleTests/GlobalProperties.java
LicenseManager
https://EasyCallGW:443/services/LicenseManager?wsdl
Locations
https://EasyCallGW:443/services/Locations?wsdl
https://EasyCallGW:443/docs/guides/sampleTests/Locations.java
Telephony
https://EasyCallGW:443/services/Telephony?wsdl
https://EasyCallGW:443/docs/guides/sampleTests/Telephony.java
Version
https://EasyCallGW:443/services/Version?wsdl
Sample code is not available for the Version service.
159
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising