Overview

The User Data Services (UDS) API is a REST-based set of operations that provide authenticated access to user resources and entities, such as user’s devices, subscribed services, and speed dials, from the Unified Communications configuration database.

UDS provides Cisco clients with the ability to:

• Display the following information for the given Cisco Unified Communications Manager (Unified CM):
  
  • Version number
  • List of servers running UDS in the Cisco Unified CM cluster
    
  • Supported locales and time zones
    
  • System options for preferences and settings
    
  • Available IP Phone services
    
• Perform Directory Searches for users. Filters can be applied to the user search.
• Display and manage personal settings, such as:
  • Credentials
    
  • Speed dial information
  • Destination devices for call forwarding
  • Device settings
  • Manage subscriptions to IP Phone Services
  • Other personal settings

UDS is installed by default and activated on all Cisco Unified CM nodes.

Cisco Product Security Overview

This product contains cryptographic features and is subject to United States and local country laws governing import, export, transfer, and use. Delivery of Cisco cryptographic products does not imply third-party authority to import, export, distribute, or use encryption. Importers, exporters, distributors, and users are responsible for compliance with U.S. and local country laws. By using this product you agree to comply with applicable laws and regulations. If you are unable to comply with U.S. and local laws, return this product immediately.

A summary of U.S. laws governing Cisco cryptographic products may be found at: http://www.cisco.com/wwl/export/crypto/tool/stqrg.html. If you require further assistance please contact us by sending e-mail to export@cisco.com.

Development Guidelines

Cisco maintains a policy of interface backward compatibility for at least one previous major release of Cisco Unified CM. Cisco still requires Cisco Solution Partner Program member applications to be retested and updated as necessary to maintain compatibility with each new major release of Cisco Unified CM.

The following practices are recommended to all developers, including those in the Cisco Solution Partner Program, to reduce the number and extent of any updates that may be necessary:

• The order of events and/or messages may change. Developers should not depend on the order of events or messages. For example, where a feature invocation involves two or more independent transactions, the events or messages may be interleaved. Events related to the second transaction may precede messages related to the first. Additionally, events or messages can be delayed due to situations beyond control of the interface (for example, network or transport failures). Applications should be able to recover from out of order events or messages, even when the order is required for protocol operation.

• The order of elements within the interface event or message may change, within the constraints of the protocol specification. Developers must avoid unnecessary dependence on the order of elements to interpret information.

• New interface events, methods, responses, headers, parameters, attributes, other elements, or new values of existing elements may be introduced. Developers must disregard or provide generic treatments where necessary for any unknown elements or unknown values of known elements encountered.

• Previous interface events, methods, responses, headers, parameters, attributes, and other elements will remain, and will maintain their previous meaning and behavior to the extent possible and consistent with the need to correct defects.

• Applications must not be dependent on interface behavior resulting from defects (behavior not consistent with published interface specifications) since the behavior can change when the defect is fixed.

• Use of deprecated methods, handlers, events, responses, headers, parameters, attributes, or other elements must be removed from applications as soon as possible to avoid issues when those deprecated items are removed from Cisco Unified CM.

• Application Developers must be aware that not all new features and new supported devices (for example, phones) will be forward compatible. New features and devices may require application modifications to be compatible and/or to make use of the new features/devices.

New and Changed

New and Changed Information in Cisco Unified CM Release 11.0(1)

• conferencing resource added, including GET and PUT operations. This user-level resource allows users to access and update their Conference Now access codes.

• user and users resources now return the displayName attribute.

• groups resource added. For Unified CM systems integrated with Microsoft Active Directory (AD), this resource allows the user to query the list of AD groups available.

New and Changed Information in Cisco Unified CM Release 10.5(2)

• GET operation support added to the Credentials resource, allowing a user to obtain login information, such as successful time and IP, unsuccessful time and IP, and login failures.

New and Changed Information in Cisco Unified CM Release 10.5(1)

• Cross-Origin Resource Sharing (CORS) support added. See the Cross-Origin Resource Sharing section for more information.

• Single Sign-On (SSO) support added. See the Authentication section for more information.

• Users resource now includes the new numeric value return field selfServiceId.

• Devices and Device resources which return description now include a new field, source=, which can be set to either user or admin.

New and Changed Information in Cisco Unified CM Release 10.0(1)

The User Data Services are a new feature available in Unified Communications Manager Release 10.0.

Example Use Cases

UDS is primarily useful for integrating personal CUCM settings access into user-facing applications and web pages. Some examples include:

• Directory search - find other users both local and remote

  • search using first, last, name, number, numberLast, email, uri (directoryUri or msUri)

• Manage preferences and settings - configure a user’s speed dials, mobility and remote destinations, call forward all, and do not disturb

  • user settings can be queried from any server in any cluster in your network

• Create collaboration widgets - allow users to update their UC feature status and message waiting indicator (MWI) status

  • users can manage their settings in a user-centric way

In this mock-up of a collaboration widget, you can see that this application allows a user to manage their own personal settings, enable and disable features, and search users by name and number.

Cross-Origin Resource Sharing

What is CORS?

For security reasons, web browsers by default prevent Javascript served by one origin (web site) from accessing data served by another origin, where an origin is a combination of scheme (an example of a scheme is HTTPS), hostname, and port.

For example, Javascript on a page served from https://app.example.com cannot access data retrieved via XMLHttpRequest from https://ucmanager.example.com (for example, to make a UDS request.)

To allow these types of requests securely, the Cross-Origin Resource Sharing (CORS) standard was developed: http://www.w3.org/TR/cors.
CORS is supported in modern browsers.

CORS involves the use of special HTTP request headers and ‘pre-flight’ OPTIONS requests, and is generally handled transparently by browsers. However, it is necessary to configure the web server (in this case Cisco Unified CM) to allow Cross-Origin requests, on an origin-by-origin basis.

UCM supports configuration of CORS applications via the System/Cross-Origin Resource Sharing (CORS) menu:

For each browser-based application web site using an Unified CM CORS-supported API, an entry in the CORS configuration area will need to be created. Include the protocol scheme (such as HTTPS), domain, and port (if not the default port :80 or :443), for example https://app.example.com.

Hello World

To get started with using UDS, lets look at an API request for a simple example.

An API request consists of a HTTP method and a URI. The HTTP method designates the type of activity to perform. Operations use standard HTTP methods to retrieve, update, create, and delete resources or data. The URI identifies the resource or resources that the request targets, and can include various parameters to further refine the operation.

Most API requests require that a HTTP Accept header be included. In addition, PUT and POST requests require a HTTP Content-Type header. The Accept and Content-Type header can specify xml.

To invoke an API operation, you send a HTTP request from any client that supports the creation of such a request to a Cisco Unified CM server.

Example Scenario: To get a user’s settings and preferences.

For this task, we need to make one REST API request to the server. Visit Explore the UDS APIs to see exactly how this is done.

To get the list of servers in XML format, make a HTTP GET request with the Accept header set to “application/xml”. Refer to the Request sample code in the right-hand panel.

Request

GET https:­//{host}:8443/cucm-uds/user/{userId}
        Accept: application/xml
        

You’ll receive a Response in XML format similar to the example in the right-hand panel.

Response

<user version="{version}" uri="https:­//{host}:8443/cucm-uds/user/{userId}">
            <id>{userPkid}</id>
            <userName>{userId}</userName>
            <firstName>firstName</firstName>
            <lastName>lastName</lastName>
            <middleName>middleName</middleName>
            <nickName>nickName</nickName>
            <phoneNumber>8134567</phoneNumber>
            <homeNumber>8134455</homeNumber>
            <mobileNumber>8131111</mobileNumber>
            <mobileConnect>true|false</mobileConnect>
            <userLocale uri="https:­//{host}:8443/cucm-uds/installedLocales" value="0" appliesToAllDevices="true|false">English, United States</userLocale>
            <email>someone@example.com</email>
            <directoryUri>someone@example.com</directoryUri>
            <msUri>someone@example.com</msUri>
            <department>department</department>
            <manager>manager</manager>
            <title>title</title>
            <pager>8137777</pager>
            <primaryExtension uri="https:­//{host}:8443/cucm-uds/user/{userId}/userExtension/{extensionPkid}">
                <description>extensionDescription</description>
                <directoryNumber>81134953</directoryNumber>
                <callForwardAllDestination>
                    <sendToVoiceMailPilotNumber>true|false</sendToVoiceMailPilotNumber>
                    <destination>4352134</destination>
                </callForwardAllDestination>
                <messageWaitingVisualAlert>true|false</messageWaitingVisualAlert>
                <messageWaitingVisualAlertPreference appliesToAllLineAppearances="true|false" value="">Use System Default</messageWaitingVisualAlertPreference>
                <messageWaitingAudibleAlertPreference appliesToAllLineAppearances="true|false" value="1">On</messageWaitingAudibleAlertPreference>
                <onACallRingPreference appliesToAllLineAppearances="true|false" value="0" >Use System Default</onACallRingPreference>
                <notOnACallRingPreference appliesToAllLineAppearances="true|false" value="0" >Use System Default</notOnACallRingPrefence>
                <voiceMailPilotNumber>5555</voiceMailPilotNumber>
                <label appliesToAllLineAppearances="true|false">label</label>
                <logMissedCalls appliesToAllLineAppearances="true|false">true|false</logMissedCalls>
            </primaryExtension>
            <accountType useLdapAuth="true|false">ldap|local</accountType>
            <homeCluster enableCalendarPresence="true|false" enableImAndPresence="true|false">true|false</homeCluster>
            <devices uri="https:­//{host}:8443/cucm-uds/user/{userId}/devices"/>
            <credentials uri="https:­//{host}:8443/cucm-uds/user/{userId}/credentials"/>
            <userExtensions uri="https:­//{host}:8443/cucm-uds/user/{userId}/userExtensions"/>
            <enableDoNotDisturb appliesToAllDevices="true|false">true|false</enableDoNotDisturb>
            <callForwardAllDestination appliesToAllExtensions="true|false">
                <sendToVoiceMailPilotNumber>true|false</sendToVoiceMailPilotNumber>
                <destination>43521</destination>
            </callForwardAllDestination>
            <speedDials uri="https:­//{host}:8443/cucm-uds/user/{userId}/speedDials"/>
            <serviceProfile uri="http:­//{host}:6970/SPDefault.cnf.xml"/>
        </user>
        

API Reference

See Cisco User Data Services (UDS) API Reference.

Authentication

See UDS Authentication.

Response and Error Codes

HTTP status codes are returned by the API with the responses.

Success Status Codes

Function	Response
GET	Requests return a 200 response if the resource is successfully retrieved.
POST	Requests return a 201 response if successful. Certain resources return a response that can be used to confirm that the information was added.
PUT	Requests return a 200 response if successful. Certain resources return a response that can be used to confirm that the information was added.
DELETE	Requests return a 204 response if successful.

Error Status Codes

Function	Response
401	Unauthorized Access. The client must submit authorization credentials before the request can be carried out.
404	Resource does not exist. This error occurs when the URL used in the request does not match a UDS resource.
405	The resource does not support this HTTP method. The common cause of this error is when a POST or a PUT method is attempted with a resource that only supports a GET method.
409	A conflict has occurred when attempting to carry out the request. Once source of this error is when a POST method attempts to add information to the database that already exists.
500	An internal exception has occurred.
503	The server is temporarily overloaded. Please wait and try your request later.

Troubleshooting

If you have questions or need support, check the UDS Developer Forums and the UDS FAQs.

The following are some basic troubleshooting hints when using UDS.

Cannot connect to the server or the connection times out.

To safeguard user credentials and information, UDS requires a secure link when conducting transactions. Verify the client application is setting up an SSL session properly.

HTTP 401 error occurs when attempting to access a UDS resource.

Certain UDS resources require authentication credentials. Information on the authentication process and which resources require authorization can be found in the Authentication section of this Developer Guide. Confirm that the end user’s name and password are correct. Check that the client is producing an Authorization header with the proper credentials.

HTTP 404 error occurs when attempting to access a UDS resource.

Check that the URL is not misspelled or confirm that the resource exists in the API Reference.

HTTP 405 or 409 error occurs when attempting to access a UDS resource.

An incorrect HTTP method is being used in the request. Consult the API Reference as to the method(s) that the resource supports.

HTTP 415 error occurs when attempting to access a UDS resource.

The parameters in the resource link (GET method) or request body (POST, PUT, and DELETE methods) are missing or invalid. Check the API Reference to determine what parameters and values the resource requires.

HTTP 503 error occurs when attempting to access a UDS resource.

The service is experiencing a heavy load. Wait and try again later.

To further troubleshoot the HTTP transactions that occur between your application and UDS, we suggest using traffic monitoring tools.

If you need additional help with UDS, you can open a developer support case.

Enable and Gather UDS Logs

This article explains how to enable and gather UDS logs from Cisco Unified CM. UDS logs are useful for debugging service issues. They provide details on exactly what services were invoked, when they were invoked, and what they actually did, including any run time errors.

The system writes the UDS trace logs to the Tomcat logs directory accessible via RTMT. File names are cucm-uds####.log, where # represents a number from 0000 (zero) to the maximum number of files allowed. The maximum file size is 1 MB by default. The maximum number of stored files defaults to 10. You can change these settings through the Serviceability windows.

Enabling UDS Logs from the Serviceability Window

1. From the Cisco Unified CM Administration window, choose Navigation > Cisco Unified Serviceability.

2. Choose Trace > Configuration.

3. From the Servers selection box, select the server and click Go.

4. From the Service Group box, select CM Services and click Go.

5. From the Services box, select the Cisco User Data Services and click Go.

6. If you want the trace to apply to all Cisco Unified CM servers in the cluster, select the Apply to All Nodes check box.

7. Check the Trace On check box.

8. In the Debug Trace Level box, select Debug.

9. Check the Enable All Trace check box.

NOTE: When you change either the Maximum No. of Files or the Maximum File Size settings in the Trace Configuration window, the system deletes all service log files except for the current file, if the service is running. If the service has not been activated, the system deletes the files immediately after you activate the service. Before you change the Maximum No. of Files setting or the Maximum File Size setting, download and save the service log files to another server if you want to keep a record of the log files. To perform this task, use Trace and Log Central in RTMT.

Gathering UDS Logs through Real-time Monitoring Tool (RTMT)

To use this tool, you must download it from Cisco Unified CM.

1. Log into Cisco Unified CM Administration.

2. Click Application > Plugins.

3. Search and find the Cisco Unified Real-Time Monitoring Tool.

4. Click Download adjacent to:

   • Cisco Unified Real-Time Monitoring Tool-Linux, if your OS is Linux
   • Cisco Unified Real-Time Monitoring Tool-Windows, if your OS is Windows
     

5. Install the RTMT tool.

6. Start the RTMT tool.

7. In the Host IP Address box, enter the IP address of the Cisco Unified CM server you want to monitor.

8. In the User Name box, enter the user name for the Cisco Unified CM server you want to monitor

9. In the Password box, enter the password for the Cisco Unified CM server you want to monitor

10. To collect logs and traces, go to System, click Trace & Log Central, and double-click Collect Files.

11. Select the Cisco CallManager check boxes in both columns.

12. Select the Cisco User Data Services check boxes in both columns.

13. Click Next.

14. Click Next.

15. On the Collect File Options screen, select an Absolute Range approximately 30 minutes before and after your test run.

16. Click Finish.

17. For convenience, zip the resulting files.

If you need additional support you can open a developer support case.

FAQs

General

What type of applications can be integrated with the UDS API resources?

What security measures do the UDS APIs provide?

Why are some of the API names nearly identical? ‘Devices’ versus ‘device’ and ‘users’ versus ‘user’, for example?

Does the UDS API support XML and JSON requests and responses?

Error Responses

The client receives a 401 response when it attempts to access a UDS resource.

The client receives a 409 response when it attempts to add a service or a device.

The client receives a 415 response when it attempts to modify an item.

General

What type of applications can be integrated with the UDS API resources?

Because UDS is implemented via REST transactions over HTTP, any HTTP-savvy application can potentially access the API. A suitable application could be a native PC program, a mobile OS application with network/HTTP request capability, or a browser-based web application using Javascript.

What security measures do the UDS APIs provide?

UDS resources that manage user-specific information and device configuration require authentication prior to their use. UDS resources that provide general information, such as UDS server features, time zone, and supported locales, do not require authentication. Note that the restricted resources use HTTP Basic authentication, where the username and password information are sent essentially in the clear (base64 encoded). Cisco strongly recommends that all UDS transactions be performed through a secure session via HTTPS and/or within a secure intranet.

Why are some of the API names nearly identical? Devices versus device and users versus user, for example?

In general, a plural UDS resource name (ends with a s character) provides general information. This information can then be used with the singular API name to drill down for more detailed information. For example, a user might access the devices resource to obtain a list of the devices that can be managed. Then use the information on the list, along with the device resource, to manage the settings and configuration of a specific device.

Does the UDS API support XML and JSON requests and responses?

The Cisco UDS API supports only the XML format for all requests and responses.

Error Responses

The client receives a 401 response when it attempts to access a UDS resource.

An attempt was made to access a restricted resource with missing or invalid credentials. The resource might have been accessed by accident, or an invalid username and password may have been provided. The client should obtain the correct credentials and retry the request.

The client receives a 409 response when it attempts to add a service or a device.

An attempt was made to add an information item (for example, a service or device) that already exists in the UDS system. This message is possible when the POST method is used with a resource. Note, to update existing items in the UDS system, the PUT method must be used.

The client receives a 415 response when it attempts to modify an item.

There was an error in one of the parameters in the request body. Correct the parameter information and try again.

Please visit UDS FAQs online for the latest updates.