This chapter describes how to start using the Cisco Prime Unified Provisioning Manager Northbound Interface (Provisioning Manager NBI) as part of the Provisioning Manager Software Development Kit (SDK) program. It also includes feature descriptions, sample applications, typical workflow steps, and other relevant information.
This chapter contains the following sections:
•Description of the Provisioning Manager NBI
•Provisioning Manager Web Services Resources
•How to Use the Provisioning Manager NBI SDK
Description of the Provisioning Manager NBI
The functions provided by the Provisioning Manager NBI enable a Provisioning Manager external command interface. The scope of the interface is to manage basic IPT devices; manage Provisioning Manager objects; submit work orders; and query the configured products, inventory manager, and subscriber services.
The Web Services architecture, using WSDL/SOAP over https, provides a standards-based request/response interaction with Provisioning Manager for submitting NBI requests. Following the WS-Notification standards, Provisioning Manager publishes a notification which is the asynchronous result of the NBI request.
Each NBI request the client sends to the server is a synchronous request message. If the Provisioning Manager server accepts the NBI request for execution, the server returns a synchronous response. The Provisioning Manager server executes the NBI request asynchronously. The client will receive an asynchronous notification with the NBI results when the Provisioning Manager server has completed execution of the NBI request.
This guide is intended to be a technical resource for application developers who want to use the Provisioning Manager NBI to provision Cisco Unified Communications deployments and implementations.
You should have an advanced level of understanding of Internet network design, operation, and terminology, and have a basic understanding of the Cisco Unified Provisioning Manager product.
Also, you should have an understanding of a high-level programming language such as Java, or an equivalent language. Additionally, you should have knowledge of the following:
•XML and XML Schema
•Web Services standards (for example, WS-Notification, WS-Enumeration, WS-Resources, and so on).
You should be familiar with the Provisioning Manager graphical user interface and how to use it to provision your network. In most cases, Provisioning Manager NBI operations correlate to Provisioning Manager operations.
Also, you should have a basic understanding of Cisco Unified Communications Manager.
The Provisioning Manager NBI provides the following:
•Management of Provisioning Manager infrastructure (devices, Domains, and Service Areas).
•The ability to submit work orders for infrastructure products.
•The ability to query Provisioning Manager inventory.
•The ability to submit a Provisioning Manager work order.
•The ability to configure products.
•Management of subscriber objects.
•The ability to configure subscriber services.
•The ability to submit work orders for subscribers.
•The ability to submit get list work orders.
•One entry point for client systems to issue commands to Provisioning Manager.
•The ability to use https or http for transport.
•The ability to retrieve list data using WS-Enumeration specification recommendations.
•The ability to query for status of any NBI request accepted by Provisioning Manager Server.
•The listProductAttributeChoice API.
The Provisioning Manager NBI functional architecture consists of the following:
•WSDL/XSD files with SOAP HTTP bindings exposing the NBI requests and XML-based data models for all northbound services.
•The Provisioning Manager NBI, which receives, tracks, and manages the results of all NBI requests.
•The following Web Services are supported as part of the Provisioning Manager NBI:
–WS-Notification and WS-ResourceFramework specifications are used to enable a client to receive the NBI request result notification asynchronously.
–WS-Security specifications are used to store credentials in the security token profile in the SOAP header. The AXIS2 interceptor is used to verify the credentials.
–WS-BaseFault specification is used to define the exceptions thrown during the synchronous submission of the NBI request. An exception is thrown if the request is not well formed or if NbiManager rejects the NBI request.
–WS-Enumeration specification concepts are used to retrieve data from list commands or any command capable of generating large amounts of data.
The Provisioning Manager NBI uses Web Services standards. The client must satisfy the following requirements:
•Client must be able to connect to the Provisioning Manager server with https.
•To only receive a notification, the client must either be a Web Services Consumer or have a Web Services Consumer installed. Notifications are sent using http.
To make a request, the client does not have to be Web Services based; it can be a plain Java client.
Provisioning Manager Web Services Resources
All services exposed by the Provisioning Manager NBI are defined using WSDL/XSD with SOAP HTTP bindings and exposed as Web Services.
The Provisioning Manager NBI Web Services are based on Axis 2.1.3 Web Services framework using XML Beans data binding.
The Provisioning Manager NBI client initiates a request and response transaction to the server. If the response does not complete the request, a WS-Notification is sent to a specified server or servlet when the request is completed.
Requested bulk data is retrieved by WS-Enumeration standard requests and responses.
The Provisioning Manager NBI SDK has been designed and tested to run on Windows XP.
It requires Java 1.6, and that the following Apache products be installed:
Note For installation information regarding these products, see the following:
•http://olex.openlogic.com/packages/axis2?show=versions&version=1645 or http://archive.apache.org/dist/ws/axis2/1_3/
If you are running the SDK on the system where Provisioning Manager is installed, Ant will already be installed and available to you. For CUPM clients that require an earlier version of Java, you must rebuild the CUPM NBI library. See "Sample Clients" for details.
How to Use the Provisioning Manager NBI SDK
The Provisioning Manager NBI SDK provides source code, libraries, and build files for a developer to generate two Provisioning Manager clients, and an NBI request parsing tool.
Following the information that is provided in "Sample Clients" you will be able to compile and build test clients and tools, and package them in a zip file that can be installed on any platform.
The SendXmlRequest client reads XML files and sends them to the server.
The RequestSignature Java class, described in Chapter 2 "Common Provisioning Manager NBIs," provides methods for you to create new Provisioning Manager clients.