1© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialSession NumberPresentation_ID

Unity Connection Provisioning API

Matt Penning

Unity Data Team Lead, UCBU

2© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Web Service

• Standard SOAP, XML over HTTP/HTTPS

• Authentication required (authorization too)

• Implemented using Apache AXIS (Tomcat/Java)

http://ws.apache.org/axis/

• Installed and running by default

3© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Gateway to the Database

• The web service allows calling stored procedures and views

• These are the same stored procedures and views used internally, so they are “tried and true”.

• Gateway to Directory database

Does not include message or report database access

• Users and Distribution Lists are supported

More is available, but not supported

4© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Compatibility

• Only basic data types are used to provide wide SOAP compatibility

• C#, VB Script, and Java have been tried (although most testing done in Java and C#)

• Similar to 4.x but not identical

• OS independent (of course)

5© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Limitations

• No voice support

• 100 rows/query

• Query throttling to prevent large queries

• No direct table access (a feature!)

• Only the directory database (not messages or reports)

This is intentional, the API is not intended for mailbox management or reports.

6© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Error Handling

• SQL Exception codes (and messages) are returned by API

• CUC stored procedures have well defined user exception codes

• SQL exceptions will come back – constraint names are consistent

• csp_GetErrorText can be used to return localized error messages for some common situations.

7© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Documentation and Support

• Unified Communications Forum

Support is available on the Cisco Unified Communications Forum at http://forums.cisco.com.

• Database Help File

Comprehensive information about the database – structure, stored procedures, errors, etc. currently exists. This is installed in the Unity TechTools folder:TechTools\Docs\UnityDirDb.chm.

It includes a chapter on the web service API.

8© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Documentation and Support (continued)

• CUDLE (on box)

“Data Link Explorer” allows viewing data, executing queries, and includes descriptions of database objects.

CUDLE includes descriptions of the tables and columns.

• Apache Axis web site - http://ws.apache.org/axis/

The Apache Axis web site has good general information on their web service implementation and tools (such as WSDL2Java).

9© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Changes from Unity 4.05

• Dropped support for cual (the read only version)

All clients must authenticate now

• Dropped CiscoUnitySystemInformation

This existed to retrieve information that was not available in the database in 4.x (switch configuration, product version, licensing, etc.). This is all available in the database now (vw_LicenseCounts, vw_LocationVMS, csp_GetProductVersion, vw_MediaSwitch, vw_MediaPort, vw_MediaPortGroup)

10© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Changes from Unity 4.05 (continued)

• Authorization improvements

The Role(s) which a user is assigned will determine what procs/views are accessible (if any).

Access to only procs/views is enforced now (in 4.x it was discouraged but possible to go direct to tables)

Updates to views are not allowed

• Error handling improvements

The web service code does more error checking and returns more detail in general

The database itself is more error-proof due to the addition of constraints, keys, etc.

11© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Changes from Unity 4.05 (continued)

• Database objects similar but not identical

Stored procedure naming is now csp_<Object><Operation> throughout: sp_CreateSubscriber becomes csp_SubscriberCreate.

New objects exist: User for example

12© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Example – Connecting

import java.net.URL;

import com.cisco.unity.cual.*;

…

CiscoUnityDbServiceLocator sl = new CiscoUnityDbServiceLocator();

URL url = new URL("http://DefaultAdministrator:cisco123@10.93.249.82/cuals/services/CiscoUnityDb );

CiscoUnityDb db = sl.getCiscoUnityDb(url);

…

** Exception handling omitted **

13© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Example – Fetching Subscriber Templates

try {

sql_response = db.query("select Alias from vw_SubscriberTemplate");

System.out.println("SubscriberTemplates:\n" + sql_response );

}

SubscriberTemplates:

<?xml version="1.0" encoding="UTF-8"?>

<rows count="1" more="0">

<row Alias="defaultSubscriberTemplate"/>

</rows>

14© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API

Example – Adding a Subscriber

try {

sp_response = db.executeProc(

"csp_SubscriberCreate", "@Alias=NewSubscriber,@DtmfAccessId=77777,@TemplateAlias=defaultSubscriberTemplate,@ObjectId=NULL out");

System.out.println("csp_SubscriberCreate Response:\n" + sp_response );

}

catch(CuDbException e)

{

// EXCEPTION_LICENSE_VIOLATION

if( e.getCode() == 50025 )

System.out.println(“License violation”);

}

…

15© 2005 Cisco Systems, Inc. All rights reserved. Cisco ConfidentialUnity Connection 1.1Provisioning API