Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Unity Connection Provisioning API Matt Penning Unity Data Team Lead, UCBU Session Number Presentation_ID © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 1 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 Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 2 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 Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 3 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) Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 4 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. Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 5 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. Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 6 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. Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 7 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). Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 8 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) Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 9 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. Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 10 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 Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 11 Example – Connecting import java.net.URL; import com.cisco.unity.cual.*; … CiscoUnityDbServiceLocator sl = new CiscoUnityDbServiceLocator(); URL url = new URL("http://DefaultAdministrator:[email protected]/cuals/service s/CiscoUnityDb ); CiscoUnityDb db = sl.getCiscoUnityDb(url); … ** Exception handling omitted ** Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 12 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> Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 13 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”); } … Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 14 Unity Connection 1.1 Provisioning API © 2005 Cisco Systems, Inc. All rights reserved. Cisco Confidential 15