170 likes | 365 Views
Unity Connection Provisioning API. Matt Penning Unity Data Team Lead, UCBU. 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.
E N D
Unity Connection Provisioning API Matt Penning Unity Data Team Lead, UCBU
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
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
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)
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.
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.
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.
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).
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)
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.
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
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 **
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>
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”); } …