1. 1 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Session Number Presentation_ID Unity Connection Provisioning API Matt Penning Unity Data Team Lead, UCBU

2. 2 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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. 3 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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. 4 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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. 5 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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. 6 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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. 7 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning API Documentation and Support Unified Communications Forum Support is available on the Cisco Unified Communications Forum at http://forums.cisco.com.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. 8 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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/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. 9 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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. 10 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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. 11 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning API Changes from Unity 4.05 (continued) Database objects similar but not identical Stored procedure naming is now csp_ throughout: sp_CreateSubscriber becomes csp_SubscriberCreate. New objects exist: User for example

12. 12 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning 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/service s/CiscoUnityDb ); CiscoUnityDb db = sl.getCiscoUnityDb(url); … ** Exception handling omitted **

13. 13 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning API Example – Fetching Subscriber Templates try { sql_response = db.query("select Alias from vw_SubscriberTemplate"); System.out.println("SubscriberTemplates:\n" + sql_response ); } SubscriberTemplates:

14. 14 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning API Example – Adding a Subscriber try { sp_response = db.executeProc( "csp_SubscriberCreate", "@Alias=NewSubscriber,@DtmfAccessId=77777,@TemplateAlia s=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. 15 © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential Unity Connection 1.1 Provisioning API