Introduction

Cisco Unified Communications Manager (Unified CM) provides reliable, secure, scalable, and manageable call control and session management. OpsRamp monitors UCM devices via the Cisco AXL/SOAP Performance Monitoring API (PerfMon) and the Control Center Services SOAP API, collecting performance counters, service status, and raising alerts through the gateway.

Supporting UCM Monitoring Models

• Call Manager (CUCM)
• Contact Center Express (UCCX / CCX)
• IM & Presence (Cisco Presence Server)
• Unity Server (Cisco Unity Connection)

Pre-requisites

• A gateway management profile mapped to the resource
• Create credentials with type as HTTP before assigning a template to a resource
• Default port: 8443 (HTTPS). Port 80 is supported for HTTP but HTTPS is strongly recommended
• Create a user with proper permissions: Steps to create a User with required permissions for Cisco UCM monitoring
• The gateway must have network connectivity to the UCM device on the configured port
• TLSv1.2 must be enabled on the UCM device (the gateway enforces TLSv1.2)

Credential Details

Discovery

Choose one of the following discovery mechanisms to discover the Cisco UCM resource:

• WMI
• SSH
• SNMP
• (Optional) Manually add the resource via Infrastructure > Settings > Resource > Add

Supporting UCM Monitoring Models, Templates, and Monitor Names

Authentication and Connection Behavior

Login Fallback Mechanism

The gateway implements a smart login fallback:

1. First attempts connection using the IP address
2. If IP-based login fails, falls back to hostname
3. The successful connection parameter is cached in CacheObjStore to avoid repeated fallback attempts

Troubleshooting

Gateway GCLI Flags

Log-level overrides:

loglevel set com.vistara.gateway.plugin.ucm.monitor.ccce.UcmCcceDataCollectorWorker DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.monitor.cus.UcmCusDataCollectorWorker DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.monitor.cprsncs.UcmCprsncsDataCollectorWorker DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.monitor.perfmon.UcmPerfMonDataCollectorWorker DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.monitor.service.UcmServiceDataCollectorWorker DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.collector.AbstractUcmCollector DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.collector.UcmCollector DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.collector.UcmPerfMonCollector DEBUG 60
loglevel set com.vistara.gateway.plugin.ucm.collector.UcmServiceCollector DEBUG 60

UCM API Detail

The device types Cisco UCM, Cisco Contact Center Express, Cisco Unity, Cisco IM & Presence Server support SOAP protocol to get the data. SOAP is an XML-based protocol for accessing web services over HTTP. We prepare XML request, query the device and will get the response that is also in XML.

Steps to Execute and Verify When the UCM Performance Monitor is Not Working

1. Replace “127.0.0.1” with device ip in the xml and save the following xml content in a “data.xml” file in the gateway console in the directory path example: /home/ruser/

<SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="http://schemas.cisco.com/ast/soap/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
       <ns1:PerfmonCollectCounterData>
           <Host xsi:type="xsd:string">127.0.0.1</Host>
           <Object xsi:type="ns1:ObjectNameType">Processor</Object>
       </ns1:PerfmonCollectCounterData>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

2. Run the following command (same directory where “data.xml” saved) after replacing the “user_name” with user name, “127.0.0.1” with device ip address and “port” with enabled port on the device

curl -X POST -d @data.xml -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction: http://schemas.cisco.com/ast/soap/#PerfmonCollectCounterData" -k -u <user_name> https://127.0.0.1:8443/perfmonservice/services/PerfmonPort -vvv

Expected response: You should get an XML response containing PerfmonCollectCounterDataResponse with counter items like \\127.0.0.1\Processor(0)\% CPU Time.

Response format:

\\<Target IP>\<Object>(<InstanceField>)\<Counter Name>

Steps to Execute and Verify When the UCM Services Status Monitor is Not Working

1. Save the following xml content in a “sdata.xml” file in the gateway console in the directory path example: /home/ruser/

   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
       <soap:soapGetServiceStatus>
           <soap:ServiceStatus/>
       </soap:soapGetServiceStatus>
   </soapenv:Body>
</soapenv:Envelope>

2. Run the following command (same directory where “sdata.xml” saved) after replacing the “user_name” with user name, “127.0.0.1” with device ip address and “port” with enabled port on the device.

curl -X POST -d @sdata.xml -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction: http://schemas.cisco.com/ast/soap/action/#ControlCenterServices" -k -u <user_name> https://127.0.0.1:8443/controlcenterservice/services/ControlCenterServicesPort -vvv >> output-sdata.xml

Authentication Alert Tracking

Authentication state is tracked per component via UcmAuthVerifier, persisted to the database using AuthStatePojo. Auth metrics include:

• ucm.cucm.auth.error — Call Manager auth failures
• ucm.ccce.auth.error — Contact Center Express auth failures
• ucm.cus.auth.error — Unity Server auth failures
• ucm.cprsncs.auth.error — IM & Presence auth failures
• uc.soap.monitor.error — General SOAP connectivity check alert

NAT and Hostname Considerations

Hostname-based Monitoring

Hostname-based monitoring is supported on both Classic and NextGen gateways. If hostname monitoring is not working on a NextGen gateway, ensure:

• DNS resolution is working from the gateway host
• The hostname resolves to the correct IP
• Gateway version is 18.1.0 or later

FAQ

Q: Which gateway version is required for UCM 14.0.0?

A: Gateway version 16.0.0 or later is required.

Q: What authentication method does UCM monitoring use?

A: HTTP Basic Authentication over HTTPS (TLSv1.2). Self-signed certificates are accepted.

Q: How often does service discovery refresh?

A: Every 6 hours (360 minutes) by default, controlled by the UC_COMP_COLLECTION_FREQ parameter.

Q: What happens if the PerfMon session expires?

A: The gateway automatically detects expired sessions (5-hour server-side idle timeout) and recreates them on the next collection cycle.

Q: Can I monitor UCM behind a NAT?

A: Yes, NAT support has been added. Ensure the gateway can reach the NAT address on port 8443.

Q: Why do I see uc.soap.monitor.error alerts?

A: This alert fires when the SOAP connectivity check fails. Common causes: incorrect credentials, network connectivity issues, or TLS version mismatch.

Q: I see SAAJMetaFactoryImpl not found errors. What should I do?

A: Upgrade the NextGen gateway to the latest version. This was a classpath issue fixed in later releases