Transcript Unity Connection Provisioning API

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