How It Works

Extension Mobility API Functionality

This section describes what happens when an application sends a message to the Extension Mobility API service to use its functionality.

An E/M API login application submits an HTTP/HTTPS POST request containing the XML request to the E/M API service URL hosted on UCM:

The request is made using the HTML form pattern (for more info, refer to http://www.w3.org/TR/html401/interact/forms.html#h-17.13.3) where the HTTP Content-Type header must be application/x-www-form-urlencoded:

Content-Type: application/x-www-form-urlencoded

and the request body contains a single control-name xml with the value equal to the E/M API XML content, in URL-encoded/escaped format:

xml=%3cquery%3e%3cappInfo%3e%3cappID%3eemproxy%3c%2fappID%3e%3cappCertificate%3epassword%3c%2fappCertificate%3e%3c%2fappInfo%3e%3cdeviceUserQuery%3e%3cdeviceName%3eSEP010203040506%3c%2fdeviceName%3e%3c%2fdeviceUserQuery%3e%3c%2fquery%3e

Note the example request body above contains the URL encoded XML below:

<query>  
    <appInfo>  
        <appID>emproxy</appID>  
        <appCertificate>password</appCertificate>  
    </appInfo>  
    <deviceUserQuery>  
        <deviceName>SEP010203040506</deviceName>  
    </deviceUserQuery>  
</query>

The following is an example of a complete HTTP request to the E/M API service:

POST /emservice/EMServiceServlet HTTP/1.1  
Content-Type: application/x-www-form-urlencoded  
Host: ucmanager:8443  
Content-Length: 249

xml=%3cquery%3e%3cappInfo%3e%3cappID%3eemproxy%3c%2fappID%3e%3cappCertificate%3epassword%3c%2fappCertificate%3e%3c%2fappInfo%3e%3cdeviceUserQuery%3e%3cdeviceName%3eSEP010203040506%3c%2fdeviceName%3e%3c%2fdeviceUserQuery%3e%3c%2fquery%3e

The EMService checks the user credentials provided in the <appInfo> element where

  • appID is the user name
  • appCertificate is the password
    to ensure the corresponding UCM user has authorization to perform E/M API requests.

For example, either an individual end user with E/M feature enabled (in which case they can perform E/M API operations only on their own device profiles), or a user who is a member of the Standard EM Authentication Proxy Rights group (which allows the user to perform E/M API operations for any user.) Typically E/M API applications will use a UCM "Application User" account with proxy rights to access the service, performing E/M actions on-behalf-of individual end users.

In normal operation, the E/M API service returns an HTTP 200 OK response to all valid requests. If the requested E/M operation was successful, the response will contain a success XML response body:

<response>  
    <success/>  
</response>

If the operation was not successful, the response body will contain an appropriate error message:

<response>  
    <failure>  
        <error code="3">DB Query Error: Application Authentication Error: Could not authenticate"</error>  
    </failure>  
</response>

Character Encoding Support for the <userId> element

As CUCM supports creating user IDs which include extended characters (like '@'), E/M API requests/responses which include a <userId> element provide the content of the field as UTF-8 encoded text:

Note: the <userId> element value is the only part of a request/response that will be UTF-8 encoded

<response>
  <deviceUserResults>
    <device name="SEP402CF4915265">
      <userID>em%40cisco.com</userID>
      <lastlogin>em</lastlogin>
      <emccDevice>no</emccDevice>
    </device>
  </deviceUserResults>
</response>