Guest

Cisco Unified Communications Manager (CallManager)

Cisco IP Manager Assistant - IPMA

Cisco - Cisco IP Manager Assistant

Document ID: 41984

Updated: Aug 29, 2011

   Print

Introduction

The Cisco IP Manager Assistant (IPMA) feature enables managers and their assistants to work together effectively. This feature comprises of a call routing service that enhances the phone capabilities for the manager, and the desktop interfaces for both the manager and the assistant. This service intercepts calls that are made to managers and routes them to selected assistants, managers, or other targets based on preconfigured call filters. The manager can change the call routing dynamically. For example, with a softkey press on the phone, the manager can instruct the service to route all calls to the assistant and can receive status on these calls.

Prerequisites

Requirements

Cisco recommends that you have knowledge of this topic:

  • Cisco CallManager administration

Components Used

The information in this document is based on these software versions.

  • Cisco CallManager version 3.3(2)

  • Cisco IP Manager Assistant Service

The information presented in this document is created from devices in a specific lab environment. All of these devices used in this document started with a clear (default) configuration. If you are to work in a live network, ensure that you understand the potential impact of any command before you use it.

Definitions

These definitions apply within this document:

Term Definition
Manager A manager is the user whose incoming calls are intercepted by the routing service and routed appropriately.
Assistant An assistant is a user who handles calls on behalf of a manager.
Proxy Line A proxy line specifies a phone line that appears on the assistant's Cisco IP Phone. You need to configure one proxy line for each manager who is associated with the assistant. Cisco IPMA uses proxy lines to manage calls intended for a manager. If the call-routing software determines that the call should be presented to the assistant because the manager cannot accept the call, the call routes to the proxy line configured for that manager on the assistant's Cisco IP Phone.
Intercom Line A line configured on the manager's and the assistants' phones to allow direct communication between the manager and his or her assistant.

Conventions

Refer to Cisco Technical Tips Conventions for more information on document conventions.

Theory of Operation

The Cisco IPMA route point is assigned a Directory Number (DN), which is then translated to match all Cisco IPMA managers DNs. The service intercepts calls made to the manager's DNs, applies filters configured by either the manager or the assistant, and then routes the call appropriately.

ipma_routing_A.gif

Cisco Tomcat Service

The Cisco Tomcat service loads the Cisco IPMA service. Cisco Tomcat is loaded at the time of Cisco CallManager installation. The Cisco IPMA service performs these tasks:

  • It hosts the HTTP services that run on the assistant and manager phones.

  • It hosts the web pages that the assistant and manager use for call control as well as the configuration pages.

  • It contains the routing logic that applies filters on an incoming call for a manager.

  • It communicates to a Cisco CallManager cluster through the Cisco CTIManager for Third party call control. Cisco CallManager requires only one Computer Telephony Integration (CTI) connection for all the users in a cluster.

  • It accesses data from the database and directory.

Configuration

This document is not intended to describe the configuration process required for Cisco IPMA. The configuration for Cisco IPMA has been well documented.

Refer to Configuring Cisco IPMA for configuration instructions.

Highlights of the configuration steps are listed here.

Partitions and Calling Search Spaces

  • Set up three partitions: Managers, Cisco IPMA, and Everyone.

  • Set up two Calling Search Spaces (CSS): CSS-M-E (Managers, Everyone) and CSS-I-E (Cisco IPMA, Everyone).

IPMA Route Point and Translation Pattern

  • The DN should be such that it matches the DNs of all managers (such as 50XX)

  • Partitions should be Cisco IPMA and Everyone

  • CSS should be CSS-M-E

Manager Phone

  • Softkey template = standard Cisco IPMA manager

  • Phone button template = standard 7960 (two lines)

  • Line 1, primary line. Partition = manager, CSS = CSS-I-E

  • Line 2, incoming intercom line with auto answer, with speaker phone or headset option. Partition = Everyone, CSS-I-E

  • Speed-dial for intercom line of each configured assistant

  • User needs to be configured as a manager in the global directory

Assistant Phone

  • Softkey template = Standard Cisco IPMA assistant

  • Phone button template = Cisco IPMA two-line phone button template

  • Expansion module 1 = Cisco IPMA 14-button template

  • Line 1, primary line. Partition = Everyone, CSS = CSS-I-E

  • Add Cisco 14-button extension module 7914 having six lines. Lines 2 to 6 stand as proxy lines for each associated manager

  • Partition = Everyone, CSS = CSS-M-E

  • Line 7 on expansion module is configured as the intercom line, with auto answer, with speaker phone or headset option

  • Partition = Everyone, CSS = CSS-I-E

  • Speed-dial is configured for the intercom line of each configured manager

  • Each user needs to be associated with the appropriate manager in the global directory

Directory Configuration for Active Directory/Netscape

If a directory search from the Cisco IPMA assistant console is required only on the Cisco CallManager directory, no configuration needs to be done. If another directory needs to be supported, the LDAPConfig.ini file located at C:\Program Files\Cisco\MA\LDAPConfig.ini needs to be modified as appropriate for the LDAP with which you work. Here is a copy of the LDAPConfig.ini file for DC Directory.

##Directory Attributes####

FIRST_NAME=givenname
MIDDLE_INITIALS=middleinitial
LAST_NAME=sn
COMMON_NAME=cn
TELEPHONE_NUMBER=telephonenumber
USERID=uid
DEPARTMENT=departmentNumber

##CONNECTION DETAILS##

MAX_DIR_CONNECTION=2
INITIAL_DIR_CONNECTION=2
SEARCHSIZE=25
MAX_TIME_LIMIT=0
SEARCH_CN=false
MANAGER_DN=cn=CCM SysUser,ou=Users,o=cisco.com 
MANAGER_PASSWORD=
LDAP_URL=ldap://localhost:8404
SEARCH_BASE=ou=Users,o=cisco.com

Cisco IPMA Service Redundancy

The IPMA service redundancy design is a simple active/standby redundancy design. At any point of time, only one server is active and provides service. The other server is in a standby mode that waits to take over if the active server should fail. The standby server monitors the health of the active server by periodically sending an HTTP request for the active state. If this HTTP request fails, the active server is determined to be down, and the standby server now becomes the active server.

The key characteristics of the design are:

  • There is no failback; once the backup server becomes the active server, it does not revert to become the backup server until it fails.

  • If a server determines that both servers were down at the same time, all managers and assistants that were logged in before the failure are logged out.

A monitor thread implements a state machine that periodically polls the peer server for its current server state. Based on the current state of this server and of the peer server, the monitor thread determines whether it should remain in its current state or change states.

Local Service/Peer Service INIT ACTIVE STANDBY DOWN/UNKNOWN
INIT If primaryServer goActive, otherwise goStandby goStandby doNothing (let peer goActive) goActive
ACTIVE doNothing (let peer goStandby) If primaryServer doNothing (let peer goStandby) else goStandby doNothing (this is a steady state) doNothing (this is a steady state)
STANDBY goActive doNothing (this is a steady state) If primaryServer goActive else doNothing (let peer go Active) doActive
DOWN/UNKNOWN Error (should never get here) Error (should never get here) Error (should never get here) Error (should never get here)

Primary Cisco IPMA Service on Publisher and Redundant Subscriber

Cisco IPMA stores various manager and assistant information in the Cisco CallManager SQL database. The purpose of storing data in the SQL database is to preserve the manager/assistant status across client sessions and Cisco IPMA server failovers. In other words, if a manager has set Do Not Disturb (DND) on, when Cisco IPMA fails over to another server, that server must log in the manager and set DND according to the DND status stored in the database. There is no option to set a phone within a hunt group to DND if the user is not available. However, you can use extension mobility in order to allow the user to log in or log off.

When the publisher is down, Cisco IPMA does not honor any requests to modify data maintained in the database. In other words, when the publisher is down, Cisco IPMA does not allow a manager to change his or her DND status.

With Cisco CallManager version 3.3.2, Cisco IPMA stores these informations in the database:

  • For the manager : WatchOn, DndOn, FilterOn, DivAllOn, FilterType, and SecretKey.

  • For the assistant : IsAvailable and SecretKey

As a consequence of this, when the publisher (with the primary Cisco IPMA service) goes down, the Cisco IPMA application and the Assistant Console fails over. However, the assistant cannot come online because the application fails to update IsAvailable. This is documented in Cisco bug ID CSCea33623 (registered customers only) - IPMA assistant unable to come online after failover.

With Cisco CallManager version 3.3.3, Cisco IPMA stores less information in the Cisco CallManager SQL database:

  • For the manager : WatchOn, DndOn, FilterOn, DivAllOn, and FilterType.

  • For the assistant : none.

As a consequence, the assistant is able to come online in this scenario. However, the manager cannot update any status maintained in the database.

Do Not Disturb (DND)

The Do Not Disturb (DND) feature allows you to set your phone to forward calls without ringing the phone. Enable the DND service with the DND soft key on Cisco Unified IP phones that support soft keys. When DND is enabled, inbound calls do not ring the phone, but they do provide visual alerts and call information. They can also be answered if desired

Note: DND is a part of IPMA in Cisco CallManager 4.x and 5.x. In Cisco CallManager 6.x, the DND feature can be used without IPMA. There are several workarounds to use DND in CallManager 4.x and 5.x without IPMA:

  1. In order to use the DND feature without the IPMA service, enable Call Forward All to your voice mail. This forwards all calls to your voice mail without the phone ringing.

  2. Similar to the first workaround, create Speed Dial to Voice Mail, and label it DND on the phone. Whenever you need to switch to the DND mode, press CFwdAll and then the DND speed dial button.

  3. Another simple workaround to implement DND is to use a silent ring tone for the phone.

Call States

State Meaning
0 Unknown
1 Idle
2 Offering
3 Accepted
4 Dialtone
5 Dialing
6 Ringback
7 Busy
8 Connected
9 Proceeding
10 Onhold
11 Onholdpending
12 Transferonhold
13 Transferonholdpending
14 Disconnected

Softkey Event IDs

The Cisco CallManager and Manager Assistant (MA) traces use these identifiers to indicate which softkeys are used. Presently, the softkey event seen in the Cisco CallManager traces differ from the softkey event IDs seen in the MA traces. Fortunately, the IDs in the MA traces correspond to the IDs configured in the softkey template. This is documented in Cisco bug ID CSCdz44718 (registered customers only) .

Softkey Call State Softkey Event ID CM traces Softkey Event ID CM Template/ MA traces
DivAll All States 786502 70
DND All States 786501 69
Intrcpt All States 786498 66
TrnsfVM Ringing, Connected, OnHold 786500 68
ImmDiv Ringing, Connected, OnHold 786497 65
SetWtch All States 786499 67

Troubleshooting

When troubleshooting problems with Cisco IPMA, there are checkpoints along the way to determine where a problem occurs. This table shows the steps and where to look for the problem:

Problem What to check
Services button returns invalid host or nothing. Check the Services URL entry in Enterprise Parameters.
Services button returns 'No services Configured...' Check that the services for the phone or user profile have been selected.
To set up speed dials and other services for your phones..." Check that the services for the phone or user profile have been selected.
Phone displays "Host not Found". Cisco Tomcat service may be stopped.
Phone displays "Initialization in progress. Please try again later". Cisco Tomcat is starting. Allow the service to fully start before trying to log into Cisco IPMA.
During the attempt to transfer to voicemail, the "That Key is not active error message is displayed. Check if these are configured correctly:
  • URL and the service parameters
  • Softkey template
  • Voicemail Profile and the CTI route point
When you try to add a second line to the intercom line space in the IPMA configuration, the Error Updating device and line(s) information. Unknown Error error message is received. Uncheck the Automatic Configuration and update the User Configuration.
After a restart of CTI and IPMA service on servers in the Cisco CallManager cluster, some of IPMA assistants lost their speed dials. Refer to Troubleshoot Missing Speed Dials Issue In IPMA for more information on how to resolve this issue.
Assistant Console displays the Cisco IPMA Error A system Failure was found, please contact your system administrator. error message. Under the Service Parameter for IPMA assistant, makes sure that the IP address for the CTI Manager is entered. Then, restart the Cisco Tomcat service and CTIManager service.
IPMA console hangs on login due to file version check. Make sure that the firewall does not block the port 8080.
IPMA assistant console issue, the users account does not open and the System error.Please contact administrator error message appears. Restart the Cisco Tomcat and IPMA service.

Filtering Down error message

The Filtering down error message appears in the IP Phone in which IPMA configuration is not used presently and this prevents you from making and receiving calls on the IP Phone.

This message appears because the IPMA was possibly misconfigured and later the configuration was not removed properly from the IP Phone. So, as a resolution to the problem, remove IPMA properly and modify the service parameters. Make sure that IPMA service is Stopped in the TomCat.

Receive the "SYSTEM ERROR PLEASE CONTACT ADMINISTRATOR" error message

When you access the IPMA application, the SYSTEM ERROR PLEASE CONTACT ADMINISTRATOR error message appears.

Complete these steps in order to resolve the issue:

  1. Make sure that The Manager and assistant phones are not associated with multiple users

  2. You need to restart these services out of production hours:

    • Cisco IP Manager Assistant

    • Cisco CTIManager

    Note: ChooseCisco Unified Serviceability > Tools > Control Center - Feature Services and choose the Subscriber. Then choose the previous services services and restart it one by one. Then choose the Publisher and choose the previous services and restart it one by one.

  3. Issue the utils service restart Cisco Tomcat command in order to restart Tomcat service from the CLI.

    Note: This command needs to be applied on the Subscriber only.

Unable to connect to IPMA service with the http 503 error

You are unable to connect to IPMA service from assistant console and the http 503 error appears. The HTTP 503 error indicates a web issue that is related to tomcat service.

When you attempt to restart the Tomcat service, this error message appears that indicated an issue with CTI Manager:

Message from syslogd@FAURDEFRA01VS02 at Wed Jun 29 20:52:23 2011 ...

FAURDEFRA01VS02 local7 0 : 4: Jun 29 18:52:23.20 UTC :
%CCM_TOMCAT_APPS-JAVAAPPLICATIONS-0-IPMANotStarted: IPMA Application not
started Servlet Name:Cisco IP Manager Assistant Reason:Service failed to
go active. Provider is not a super provider App ID:Cisco Tomcat Cluster
ID: Node ID:FAURDEFRA01VS02

Solution

This issue occurs because the CTIManager is not configured on the IPMA service parameter. Choose Cisco Unified Serviceability > Tools > Control Center - Feature Services on CUCM and restart the Cisco CTIManager in order to resolve this issue.

IPMA Assistant Cannot Have Access to Voicemail

The user receives the voicemail prompt and enters the PIN to log on but nothing happens. The filtering screen window appears on the IP phone whenever the user calls the voicemail. This issue occurs after the CUCM upgrade.

This issues arises due to the phone service that does not run on the assistant IP phone.

Troubleshooting Tools for IP Phone

Submit Requests Through the Browser

If you submit HTTP Get requests through a windows browser by typing the specific URL in the address bar, the exact XML returned by the service may be examined. The URL is generally the URL defined for the IP phone service.

Note: The device name is a necessary parameter for all such requests.

The format for such a request is as follows:

http://172.16.240.150/ma/servlet/MAService?cmd=doPhoneService&Name=#DEVICENAME#&locale=English_United_States

Where #DEVICENAME# = SEPmac_address. This is an example:

http://172.16.240.150/ma/servlet/MAService?cmd=doPhoneService&Name=SEP003094C44A55
     &locale=English_United_States

Troubleshooting Tips from Cisco.com

Refer to Troubleshooting Features and Services for more troubleshooting information.

Trace Files

Cisco IPMA Server Trace Files

Cisco IPMA server trace files can be found on the IPMA server at these locations:

  • C:\Program Files\Cisco\Trace\MA\MAService*.txt

  • C:\Program Files\Cisco\Tomcat\jvm.stderr and jvm.stdout

Go to the service parameters for Cisco IPMA on the Cisco CallManager server to enable debug tracing.

Reading MA Traces

In MA traces, the string "accepted call" is the start of the call, as shown in this example:

306: Dec 19 07:22:17.464 EST %MA-SERVICE-7-UNK:[RoutingEndpoint:IPMARP] 
     NewCall() - accepted call
307: Dec 19 07:22:17.464 EST %MA-SERVICE-7-UNK:[RoutingEndpoint:IPMARP] 
     NewCall() - New Call on line: 72XX calledParty=7203
308: Dec 19 07:22:17.464 EST %MA-SERVICE-7-UNK:[RoutingEndpoint:IPMARP] 
     NewCall() - send the call to [ProxyLineManager:rfrome]
309: Dec 19 07:22:17.464 EST %MA-SERVICE-7-UNK:[ProxyLineManager:rfrome] 
     handleRoutePointNewCallEvent() - call=Call:[GCID=(86/1),CID=16777451] 
     callingParty=7201 calledParty=7203
310: Dec 19 07:22:17.464 EST %MA-SERVICE-7-UNK:[ProxyLineManager:rfrome] 
     handleRoutePointNewCallEvent() - redirecting it to [ProxyLineManager:rfrome] 
     at 7203
311: Dec 19 07:22:17.464 EST %MA-SERVICE-7-UNK:[ProxyLineManager:rfrome] 
     execute() -com.cisco.ma.service.cti.CTICallRedirectOperation@fdadcd starting
312: Dec 19 07:22:17.526 EST %MA-SERVICE-7-UNK:CTI EVENT -- [ProxyLineManager:rfrome] 
     NewCall() - line=7203 call=Call:[GCID=(86/1),CID=16777452] state=2
313: Dec 19 07:22:17.526 EST %MA-SERVICE-7-UNK:[ProxyLineAssistant:jj] 
     handleNewCallManager() - callID=SEP003094C44A55:1:16777452 line=7203
314: Dec 19 07:22:17.526 EST %MA-SERVICE-7-UNK:[Connection:171.69.85.47:1188] 
     sendMessage() - trying to put message into queue, messageID=26 for 
     [ProxyLineAssistant:jj]
315: Dec 19 07:22:17.526 EST %MA-SERVICE-7-UNK:[EventThread:EventThread0] 
     deliver() - Sent message, messageID=26 to client [ProxyLineAssistant:jj]

Cisco IPMA Client Trace Files

These can be found at the install location. By default, the location is as follows:

C:\Program Files\Cisco\IPMA Assistant Console\ACLog*.txt

Select Edit > Settings >Advanced Tab to enable debug tracing for the assistant console.

Reading Client Traces

The string "Going online" is the beginning of the login process.

35199: Tue Apr 08 09:04:33 PDT 2003 % Going online
35200: Tue Apr 08 09:04:33 PDT 2003 % ACMain: SetAssistantAvailableStatusRequest
35201: Tue Apr 08 09:04:33 PDT 2003 % sequence number: 7
35202: Tue Apr 08 09:04:33 PDT 2003 % userID: jj
35203: Tue Apr 08 09:04:33 PDT 2003 % available: true
35204: Tue Apr 08 09:04:33 PDT 2003 % ResponseList : Adding an element 
     to the response list
35205: Tue Apr 08 09:04:33 PDT 2003 % Node: 
35206: Tue Apr 08 09:04:33 PDT 2003 % sequenceNumber: 7
35207: Tue Apr 08 09:04:33 PDT 2003 % timeStamp: 1049817873827
35208: Tue Apr 08 09:04:33 PDT 2003 % responseWanted: true
35209: Tue Apr 08 09:04:33 PDT 2003 % responseClassExpected: 
     class com.cisco.ma.service.client.protocol.SetAssistantAvailableStatusResponse
35210: Tue Apr 08 09:04:33 PDT 2003 % ServerConnect: Sending a message/request 
     to MA Service
35211: Tue Apr 08 09:04:36 PDT 2003 % ServerConnect : Received a message from the 
     server
35212: Tue Apr 08 09:04:36 PDT 2003 % Added the event to the queue
35213: Tue Apr 08 09:04:36 PDT 2003 % EventTherad : Received an event
35214: Tue Apr 08 09:04:36 PDT 2003 % EventThread: LoginStatusChangedEvent
35215: Tue Apr 08 09:04:36 PDT 2003 % userID : rfrome
35216: Tue Apr 08 09:04:36 PDT 2003 % loggedInState: true
35217: Tue Apr 08 09:04:36 PDT 2003 % ACManagersList: got a login status changed 
     event for manager: rfrome
35218: Tue Apr 08 09:04:36 PDT 2003 % Setting logged in status for manager: 
     Robert Frome to: true

Example of assistant accepting call:

35281: Tue Apr 08 09:05:49 PDT 2003 % EventTherad : Received an event
35282: Tue Apr 08 09:05:49 PDT 2003 % EventThread: NewCallEvent
35283: Tue Apr 08 09:05:49 PDT 2003 % callId : SEP00082194D7C3:1:16793930
35284: Tue Apr 08 09:05:49 PDT 2003 % lineNumber: 8200
35285: Tue Apr 08 09:05:49 PDT 2003 % callingParty : 7202
35286: Tue Apr 08 09:05:49 PDT 2003 % callingPartyName: 
35287: Tue Apr 08 09:05:49 PDT 2003 % calledParty : 8200
35288: Tue Apr 08 09:05:49 PDT 2003 % calledPartyName : 
35289: Tue Apr 08 09:05:49 PDT 2003 % consult: false
35290: Tue Apr 08 09:05:49 PDT 2003 % Received a new call: SEP00082194D7C3:1:16793930 
     on Line :8200
35291: Tue Apr 08 09:05:49 PDT 2003 % ACProxyLine: adding a new call to the proxy 
     line: 8200SEP00082194D7C3
35292: Tue Apr 08 09:05:54 PDT 2003 % Sending an answer request to the server for 
     callID: SEP00082194D7C3:1:16793930
35293: Tue Apr 08 09:05:54 PDT 2003 % ResponseList : Adding an element to the 
     response list
35294: Tue Apr 08 09:05:54 PDT 2003 % Node: 
35295: Tue Apr 08 09:05:54 PDT 2003 % sequenceNumber: 8
35296: Tue Apr 08 09:05:54 PDT 2003 % timeStamp: 1049817954496
35297: Tue Apr 08 09:05:54 PDT 2003 % responseWanted: true
35298: Tue Apr 08 09:05:54 PDT 2003 % responseClassExpected: 
     class com.cisco.ma.service.client.protocol.CallAnswerResponse
35299: Tue Apr 08 09:05:54 PDT 2003 % ServerConnect: Sending a message/request to 
     MA Service
35300: Tue Apr 08 09:05:54 PDT 2003 % ServerConnect : Received a message from the 
     server
35301: Tue Apr 08 09:05:54 PDT 2003 % ServerConnect : Received a message from the 
     server
35302: Tue Apr 08 09:05:54 PDT 2003 % Added the event to the queue
35303: Tue Apr 08 09:05:54 PDT 2003 % EventTherad : Received an event
35304: Tue Apr 08 09:05:54 PDT 2003 % EventThread: CallConnectedEvent
35305: Tue Apr 08 09:05:54 PDT 2003 % callId : SEP00082194D7C3:1:16793930
35306: Tue Apr 08 09:05:54 PDT 2003 % lineNumber: 8200
35307: Tue Apr 08 09:05:54 PDT 2003 % Received a call connected event for call: 
     SEP00082194D7C3:1:16793930

Relevant Cisco bug IDs

These are Cisco bug IDs that might help your configuration efforts:

Related Information

Updated: Aug 29, 2011
Document ID: 41984