Cisco Cisco Prime Collaboration 10.5 manuals

Developer's Guide

Preface
4
This manual describes the Cisco Prime Collaboration Provisioning northbound interfaces. It provides instructions for using and administering it.
4
Conventions
4
Chapter 1: Getting Started
5
Description of the Prime Collaboration Provisioning NBI
5
Audience
5
Feature Summary
6
Functional Architecture
6
Client Requirements
7
Prime Collaboration Provisioning Web Services Resources
7
General Prerequisites
7
How to Use the Prime Collaboration Provisioning NBI SDK
8
Chapter 2: Common Prime Collaboration Provisioning NBIs
9
Prime Collaboration Provisioning NBI Overview
9
Managed Objects
10
Object Keys
11
Overview of Request Names
11
Overview of Object Attributes
11
Create<Object>
12
Get<Object>
12
Delete<Object>
12
Update<Object>
12
List<Object>
12
Cancel<Object>
12
Configurable Properties
12
Prime Collaboration Provisioning NBI Objects
13
Device
13
Key attribute: deviceName
13
Domain
13
Key attribute: domainID
13
ServiceArea
13
Key attributes: serviceAreaID
13
InventoryItem
13
ServiceDetail
13
Order
13
Subscriber
14
Key attribute: subscriberID
14
CupmApiListValue
14
CupmApiResponseValue
14
CupmApiResultValue
14
CupmApiStatusValue
14
CupmApiFilterValue
15
Complete Object Definition File: Common.xsd
16
Infrastructure Product Key Attributes
16
Subscriber Product Key Attributes
17
Referencing Product Attributes from the Product Catalog
17
<item>
18
<attributeValue>
18
<productAttribute>
18
<<item>
18
Prime Collaboration Provisioning NBI Requests
19
Request Signature Class
19
Device Management Commands and Queries
19
createDevice Java Signature
19
getDevice Java Signature
20
updateDevice Java Signature
21
listDevice Java Signature
21
deleteDevice Java Signature
22
getConfiguredInfraProduct Java Signature
23
ASyncReturn:
24
listConfiguredInfraProduct Java Signature
24
Domain Management Commands and Queries
24
createDomain Java Signature
24
getDomain Java Signature
25
updateDomain Java Signature
26
listDomain Java Signature
26
deleteDomain Java Signature
27
Service Area String Management Commands and Queries
28
createServiceArea Java Signature
28
getServiceArea Java Signature
29
updateServiceArea Java Signature
30
listServiceArea Java Signature
30
deleteServiceArea Java Signature
32
Synchronization Management Commands
32
syncDevice Java Signature
33
syncDomain Java Signature
33
Subscriber Management Commands and Queries
34
createSubscriber Java Signature
34
createSubscribers Java Signature
35
getSubscriber Java Signature
36
updateSubscriber Java Signature
36
listSubscriber Java Signature
37
deleteSubscriber Java Signature
38
resetSubscriberServicePassword Java Signature
39
unlockVoiceMail Java Signature
40
listSubscriberService Java Signature
40
getSubscriberService Java Signature
41
moveService Java Signature
42
moveSubscriber Java Signature
43
cancelSubscriberWithServices Java Signature
43
Removes a subscriber along with the services associated with it.
43
Syntax:
43
public ResponseReturn cancelSubscriberWithServices (CUPMServiceStub stub, String subscriberID, String validateType, String rollback, String notificationEpr, String idPrefix, Map<String,String> sessionContext, String responseType);
43
Parameters:
43
 Subscriber—Specify the subscriberID to be removed along with the associated services.
43
 validationType—An ENUM indicating whether a work order should be validated before being submitted. Values are VALIDATE_ONLY, SUBMIT_ONLY, VALIDATE_AND_SUBMIT.
43
 rollbackType—An ENUM describing how the order should be rolled back if it fails. Value is PARTIAL.
43
 notificationEpr—String to convert to an EndpointReference object that the synchronous result notification will be sent to.
43
 idPrefix—String that is added to the beginning of the NBI ID returned to the client.
44
 responseType—String to specify that the API call should be synchronous. This API works only in synchronous mode.
44
Returns:
44
CupmApiResponseValue—Object with NBI ID.
44
Throws:
44
cancelSubscriberWithServicesException—If the server cannot execute the NBI request.
44
SyncReturn:
44
 CupmApiResultValue—Contains CupmApiStatus only.
44
 CupmApiFaultType—Included if the NBI request fails.
44
Directory Number Management Commands and Queries
44
cancelDNWithService Request Signature
44
Removes the Directory number and its associated parent and child services
44
Syntax:
44
public ResponseReturn cancelDNWithService (CUPMServiceStub stub, String directoryNumber, String serviceArea, String validateType, String rollback, String notificationEpr, String idPrefix, Map<String,String> sessionContext, String responseType);
44
Parameters:
44
 directoryNumber—Specify the directory number to be removed along with the services associated with it.
44
 validationType—An ENUM indicating whether a work order should be validated before being submitted. Values are VALIDATE_ONLY, SUBMIT_ONLY, VALIDATE_AND_SUBMIT.
44
 rollbackType—An ENUM describing how the order should be rolled back if it fails. Value is PARTIAL.
44
notificationEpr—String to convert to an EndpointReference object that the synchronous result notification will be sent to.
44
 idPrefix—String that is added to the beginning of the NBI ID returned to the client.
44
 responseType—String to specify that the API call should be synchronous. This API works only in synchronous mode.
44
Returns:
44
CupmApiResponseValue—Object with NBI ID.
44
Throws:
44
cancelDNWithServiceException—If the server cannot execute the NBI request.
44
SyncReturn:
45
 CupmApiResultValue—Contains CupmApiStatus only.
45
 CupmApiFaultType—Included if the NBI request fails.
45
Overview of NBI Object Metadata
45
Work Order Management Commands and Queries
45
submitOrder Java Signature
45
getOrder Java Signature
49
listOrder Java Signature
49
resetServices Java Signature
50
Submits a work order to apply the template values. Built-in Template (default values) will be applied if no template value is specified in the request. If the work order is accepted by Prime Collaboration Provisioning, and if it passes validation (if ...
50
Syntax:
50
public ResponseReturn resetServices (CUPMServiceStub stub, OrderValue order, String validateType , String rollback , String notificationEpr, String idPrefix , Map<String,String> sessionContext );
50
Parameters:
51
 order—Creates a work order that is submitted to Prime Collaboration Provisioning if the NBI request is accepted. The order is never a prospect work order in Prime Collaboration Provisioning.
51
 validationType—An ENUM indicating whether a work order should be validated before being submitted. Values are VALIDATE_ONLY, SUBMIT_ONLY, VALIDATE_AND_SUBMIT.
51
 rollbackType—An ENUM describing how the order should be rolled back if it fails. Value is PARTIAL.
51
 notificationEpr—String to convert to an EndpointReference object that the synchronous result notification will be sent to.
51
 idPrefix—String that is added to the beginning of the NBI ID returned to the client.
51
 responseType (optional)— String to identify whether the API call should be synchronous or not.
51
Returns:
51
CupmApiResponseValue—Object with NBI ID.
51
Throws:
51
resetServicesException—If the server cannot execute the NBI request.
51
SyncReturn:
51
• CupmApiResultValue—Contains CupmApiStatus only.
51
Check Connectivity Request
51
ping Java Signature
51
Syntax:
51
public ResponseReturn ping (CUPMServiceStub stub, String epr)
51
Returns:
51
Two strings, the Prime Collaboration Provisioning version and the Prime Collaboration Provisioning NBI version.
51
AsyncReturn:
51
A test string containing server status is sent to the specified notification consumer at the EPR provided.
51
getOrderabilityStatus Request Signature
51
Indicates whether Prime Collaboration Provisioning server is ready to accept any incoming request.
51
Syntax:
52
public static ResponseReturn getOrderabilityStatus (CUPMServiceStub stub, String serviceArea, String validateType , String rollback, String notificationEpr, String idPrefix, Map<String,String> sessionContext, String responseType)
52
parameters:
52
 serviceArea—Specify the serviceArea for which the order-ability status needs to be checked.
52
 validationType—An ENUM indicating whether a work order should be validated before being submitted. Values are VALIDATE_ONLY, SUBMIT_ONLY, VALIDATE_AND_SUBMIT.
52
 rollbackType—An ENUM describing how the order should be rolled back if it fails. Value is PARTIAL.
52
 notificationEpr—String to convert to an EndpointReference object that the synchronous result notification will be sent to.
52
 idPrefix—String that is added to the beginning of the NBI ID returned to the client.
52
 responseType—String to specify that the API call should be synchronous. This API works only in synchronous mode.
52
Returns:
52
CupmApiResponseValue—Object with NBI ID.
52
Throws:
52
getOrderabilityStatusException—If the server cannot execute the NBI request.
52
SyncReturn:
52
 CupmApiResultValue—Contains CupmApiStatus only.
52
 CupmApiFaultType—Included if the NBI request fails.
52
Inventory Queries
52
getInventoryItem Java Signature
52
Retrieves an inventory item. The getInventoryItem request requires only the attributes necessary to select a unique instance. Including nonkey attributes in this request is not an error, but it is not recommended as nonmatching values or incorrect att...
52
listInventoryItem Java Signature
53
Prepopulation
54
listProductAttributeChoice Java Signature
54
Returns a choice list for a specific attribute for a specific product. The choice list is dynamic, based on the Capabilityname, DeviceName, ServiceAreaID, and product attributes that have already been specified.
54
Syntax:
54
public ResponseReturn listProductAttributeChoice (CUPMServiceStub stub, String[] arrayOfAttributes, ProductValue product, CupmApiFilterValue filter, String endPointReference, String idPrefix);
54
Parameters:
54
 product—The product specified for the return choice list, containing all attributes that have already been set.
54
 arrayOfAttributes—Each attribute for which a choice list will be returned.
54
 filter—The selection criteria section of the filter specifies the device, the capability of the device, the ServiceArea, and any product attribute values that have been set. You must specify capabilityName and either DeviceName or ServiceAreaID or b...
54
 endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.
55
 idPrefix—String that is added to the beginning of the internally generated numeric to form the unique NBI identifier. A null or empty string is valid, resulting in an NBI identifier that is just the internally generated numeric.
55
Returns:
55
CupmApiResponseValue—Object with NBI ID.
55
Throws:
55
ListProductAttributeChoiceException—If the server cannot execute the NBI request.
55
ASyncReturn:
55
 CupmApiResultValue, containing CupmApiStatus and CupmApiList. CupmApiList contains the choice lists requested for the product attributes.
55
 CupmApiFaultType—Included if the NBI request fails.
55
Prime Collaboration Provisioning NBI Status Queries
55
getApiStatus Java Signature
55
Returns the status of a specific NBI request. If the execution of the command has been completed, an attached CupmApiResultValue is also returned.
55
Syntax:
55
public ResponseReturn getApiStatus (CUPMServiceStub stub, String apiId, String endPointReference, String idPrefix);
55
Parameters:
55
 apiId—The NBI ID of the command status to return.
55
 endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.
55
 idPrefix—String that is added to the beginning of the internally generated numeric to form the unique identifier. A null or empty string is valid, resulting in an NBI identifier that is just the internally generated numeric.
55
Returns:
55
CupmApiResponseValue—Object with NBI ID.
55
Throws:
56
GetApiStatusExcepton—If the server cannot execute the NBI request.
56
SyncReturn:
56
 CupmApiResponseValue—Contains CupmApiResultValue, which contains CupmApiStatus and CupmApiList. The list contains one object, the CupmApiStatus for the NBI request specified in the request.
56
 CupmApiFaultType—Included if the NBI request fails.
56
AsyncReturn:
56
None—The command is synchronous.
56
Note: The command will fail if the server has purged the NBI request.
56
listApiStatus Java Signature
56
Returns the status of all outstanding NBI requests this client has submitted.
56
Syntax:
56
public ResponseReturn listApiStatus (CUPMServiceStub stub, CupmApiFilterValue filter, String endPointReference, String idPrefix);
56
Parameters:
56
filter—Limited filtering of the NBI requests returned.
56
You can filter using the following attribute:
56
 status
56
 endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.
56
 idPrefix—String that is added to the beginning of the internally generated numeric to form the unique NBI identifier. A null or empty string is valid, resulting in an NBI identifier that is just the internally generated numeric.
56
Returns:
56
CupmApiResponseValue—Object with NBI ID.
56
Throws:
56
ListApiStatusExcepton—If the server cannot execute the NBI request.
56
SyncReturn:
57
 CupmApiResponseValue—Contains CupmApiResultValue which contains CupmApiStatus andCupmApiList. CupmApiList contains one object, the EnumerationContextType, which is used to retrieve the list using WS-Enumeration suggested standards.
57
 CupmApiFaultType—Included if the NBI request failed or had warnings.
57
Async return:
57
None—The command is synchronousSpecialized Requests
57
listSrstPhoneInfo Java Signature
57
Generates a list of PhoneInfo objects (each represents a Phone with its Users and Lines) that are associated with the given SRST IP address and Prime Collaboration Provisioning IP address. The list of phones generated will always be the set or a subse...
57
Syntax:
57
public ResponseReturn listSrstPhoneInfo (CUPMServiceStub stub, String cpIpAddr, String srstIpAddr, String queryOption, String endPointReference, String idPrefix);
57
Paramaters:
57
 cpIpAddr—IP address of the Call Processor.
57
 srstIpAddr—IP address of the SRST.
57
 queryOption—The data selection criteria, defined by the PhoneInfoqueryOption enumeration.
57
o ALL—(Default) all phones in Prime Collaboration Provisioning will be considered.
57
o IN_CUPM_SUBSCRIBER_RECORD—Only the phones that are in the Prime Collaboration Provisioning subscriber record will be selected.
57
o NOT_IN_CUPM_SUBSCRIBER_RECORD—Only the phones that exist in Prime Collaboration Provisioning and do not exist in the Prime Collaboration Provisioning subscriber record are selected.
57
 endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.
57
 idPrefix—String that is added to the beginning of the internally generated numeric to form the NBI ID. A null or empty string is valid for no changes to the internal generation.
57
Returns:
57
CupmApiResponseValue—Object with NBI ID.
58
Throws:
58
ListSrstPhoneInfoException—If server cannot execute NBI request.
58
ASyncReturn:
58
 CupmApiResultValue—Contains CupmApiStatus and CupmApiList. CupmApiList contains the WS-Enumeration context object, which is used as the key to pull the list.
58
 CupmApiFaultType—Included if the NBI request fails.
58
getOrderSummary Java Signature
58
Syntax:
58
public ResponseReturn getOrderSummmary (CUPMServiceStub stub, Calendar startTime, Calendar endTime, String endPointReference, String idPrefix);
58
Parameters:
58
 startTime—The beginning of the time period to report on. If not specified, the value defaults to the earliest known work order.
58
 endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.
58
 idPrefix—String that is added to the beginning of the internally generated numeric to form the NBI ID. A null or empty string is valid for no changes to the internal generation.
58
Returns:
58
 CupmApiResponseValue—Object with NBI ID.
58
Throws:
58
 GetOrderSummaryException—If server cannot execute NBI request.
58
ASyncReturn:
58
 CupmApiResultValue—Contains CupmApiStatus and CupmApiList. CupmApiList contains one object, the OrderSummary object
58
 CupmApiFaultType—Included if the NBI request fails.
58
submitConfigTemplate Java Signature
59
Sends a set of Cisco IOS telephony commands, any router-related commands, and infrastructure product ordering commands to a capability on a device. The commands are specified in a template. Keyword substitution functionality is available.
59
Syntax:
59
public ResponseReturn submitConfigTemplate (CUPMServiceStub stub, ConfigDetailValue configDetail, String validate, String rollback, String endPointReference, String idPrefix);
59
Parameters:
59
 configDetail—This object defines the device and capability to send the Cisco IOS commands to. It specifies the template to send, and it contains a list of the keywords and their value for this usage.
59
 validate—VALIDATE, SUBMIT, or VALIDATE_AND_SUBMIT are the settings for this enumeration.
59
 rollback—PARTIAL_ROLLBACK setting.
59
 endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.
59
 idPrefix—String that is added to the beginning of the internally generated numeric to form the NBI ID. Null or empty string valid for no change to internal generation.
59
Returns:
59
CupmApiResponseValue—Object with NBI ID.
59
Throws:
59
submitConfigTemplateException—If server cannot execute NBI request.
59
ASyncReturn:
59
 CupmApiResultValue—Contains CupmApiStatus and CupmApiList. CupmApiList contains status of the execution of the Cisco IOS commands on the device.
59
 CupmApiFaultType—Included if the NBI request fails.
59
listConfigTemplateKeyword Java Signature
59
Provides support for listing the keywords used in templates submitted by the submitConfigTemplate request. Returns a list of all the keywords in the specified template.
59
Syntax:
59
public ResponseReturn listConfigTemplateKeyword (CUPMServiceStub stub String templateName, String endPointReference, String idPrefix);
60
Parameters:
60
 templateName—Name identifying the template for which to return the list of keywords.
60
 endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.
60
 idPrefix—String that is added to the beginning of the internally generated numeric to form the NBI ID. Null or empty string valid for no change to internal generation.
60
Returns:
60
CupmApiResponseValue—Object with NBI ID.
60
Throws:
60
listConfigTemplateException—If server cannot execute NBI request.
60
ASyncReturn:
60
 CupmApiResultValue—Contains CupmApiStatus and CupmApiList. CupmApiList contains one object that lists the keywords in this template. That object is a KeywordListDocument containing an ArrayOfString object.
60
 CupmApiFaultType—Included if the NBI request fails.
60
WS-Enumeration Requests
60
When a Prime Collaboration Provisioning NBI List Command is executed successfully, a CupmApiResultValue is sent as a notification to the client. This notification contains the object wsen:EnumerationContext. The client can now send the following reque...
60
 PullOp—Returns a list of elements according to a specified enumeration context. It may also return an updated enumeration context, which the caller should use for all future requests.
60
 RenewOp—Renews the expiration time for a specified enumeration context as long as the context is still valid. This operation will fail and generate a fault if the context is invalid.
60
 GetAPIStatus—Returns the status of an enumeration context, such as the expiration time.
60
 ReleaseOp—Invalidates a specified enumeration context and releases any resources allocated to theenumeration. The UUID list generated by the Prime Collaboration Provisioning NBI List command is flagged for deletion.
60
Note: The objects used in the Java code can be imported from org.xmlsoap.schemas.ws.x2005.x09.enumeration.
60
pullOp Java Signature
61
The pullOp command retrieves a portion of the list data generated by any list NBI. The client may set the MaxElements attribute in the CupmApiEnumIterator before sending to specify the number of elements returned. The default is 1. The pullOp command ...
61
Syntax:
61
public ResponseReturn pullOp (CUPMServiceStub stub, wsen:EnumerationContext, wsen:MaxElements, pullSize);
61
Parameters:
61
 wsen:EnumerationContext—The latest version of this object that the client has received from the server.
61
 wsen:MaxElements, pullSize—The number of objects to return with this request.
61
Returns:
61
Standard Pull response.
61
Throws:
61
 RemoteExcepton—If the server cannot execute the NBI request.
61
SyncReturn:
61
The standard pull response, which contains an ItemArrayType. In that type is the number of objects requested. If the pull reached the end of the list, a wsen:EndOfSequence object is returned as a peer of the list. This indicates to the client that no ...
61
CupmApiFaultType—Included if the NBI request fails.
61
renewOp Java Signature
61
The renewOp command tells the server that the client wants to keep the data longer than the initial expiration date. The Prime Collaboration Provisioning server will allow this to happen only if the throttling thresholds for reports will not be exceed...
61
Syntax:
61
public ResponseReturn renewOp (CUPMServiceStub stub, wsen:EnumerationContext enumerationContext, XmlCalendar Date or Duration duration);
61
If a date is specified, that date becomes the new expiration date. If a duration is specified, that time is added to the current expiration date.
61
The NBI properties control the maximum number of times an expiration date can be increased.
62
Parameters:
62
 wsen:EnumerationContext—The latest version of this object that the client has received from the server.
62
 idPrefix—String that is added to the beginning of the internally generated numeric to form the unique NBI identifier. A null or empty string is valid, resulting in an NBI identifier that is just the internally generated numeric.
62
Returns:
62
Standard WS-Enumeration Renew response message.
62
Throws:
62
Remote Exception—If the server cannot execute the NBI request.
62
SyncReturn:
62
Returns the new expiration date.
62
getStatusOp Java Signature
62
Updates the ApiEnumerator object.
62
Syntax:
62
public ResponseReturn getStatusOp (CUPMServiceStub stub, wsen:EnumerationContext enumerationContext);
62
Parameters:
62
wsen:EnumerationContext—The latest version of this object that the client has received from the server.
62
Returns:
62
Standard WS-Enumeration getStatus response message.
62
Throws:
62
RemoteException—If the server cannot execute the NBI request.
62
SyncReturn:
62
Returns the current expiration date.
62
releaseOp Java Signature
62
Tells the server that the client is done with the data and it may be purged.
62
Syntax:
63
public ResponseReturn release (CUPMServiceStub stub, wsen:EnumerationContext enumerationContext);
63
Parameters:
63
wsen:EnumerationContext—The latest version of this object that the client has received from the server.
63
Returns:
63
WS-Enumeration standard Release response message.
63
Throws:
63
RemoteException—If the server cannot execute the NBI request.
63
SyncReturn:
63
A response with no parameters.
63
Prime Collaboration Provisioning NBI Implementation of WS-Notification
63
A Prime Collaboration Provisioning client submits an NBI request to the Prime Collaboration Provisioning server. The two platforms are Web Services peers. The client is a NotificationConsumer and is subscribed to the Web Services resource that is the ...
63
There are no cases where the Prime Collaboration Provisioning server will send a message to the client unsolicited.
63
Notification Consumer Service
63
The Prime Collaboration Provisioning NBI SDK provides a notification consumer service to receive the request notifications. The notification consumer service is written in Java and designed to be deployed in an axis2.war file, running under Tomcat.
63
The default functionality for this service is to receive the notification on port 8080 and display the notification in the Tomcat console window.
63
The notification software includes a method to write the notification to disk. The directory to write the notifications in is set by the environment variable consumer.home. The default value used if this environment variable is not set is \Notificatio...
63
The ability to write the notification to disk is required, if you want to use the auto pull feature in the Perl clients for list subscriber or list Domain.
64
Appendix A: Sample Clients
65
This section describes how to use the source code, jar files, and XML files to build sample clients. For detailed information, see the following sections:
65
 Introduction
65
 Setting Up the Prime Collaboration Provisioning NBI SDK Development Environment
65
 Setting Up the Sample Java Clients
65
 Setting Up the Perl NBI Client
65
Introduction
65
Using Ant, you will compile and generate two Prime Collaboration Provisioning NBI clients. The clients use environment variables to specify the server URL to send the request to.
65
A simple notification consumer service is provided. Using Ant, you will compile and generate archives that can be installed in an AXIS2.war file that has been installed in Tomcat.
65
You will also be able to package the clients, notification consumer, and tools into a zip file that can be installed on Windows XP platforms.
65
Setting Up the Prime Collaboration Provisioning NBI SDK Development Environment
65
In your Prime Collaboration Provisioning installation, you will find a sample client-development directory at CUPM\sep\ipt\nbi-sdk. You may either work in the directory or copy it to another Windows XP platform. This platform must have Java 1.6 and An...
65
Overview of Prime Collaboration Provisioning NBI SDK Directory
65
This section lists the directories included in the Prime Collaboration Provisioning NBI SDK. After you download and unzip the SDK, you will see the following directories under the ...\nbi-sdk directory:
65
 doc—User documentation.
65
 html-doc—For each NBI XSD file, this directory contains html documentation generated from the annotation fields in the XSD file. In addition, there are graphic descriptions of all NBI complex objects.
65
The documentation describes all complex objects used by the Prime Collaboration Provisioning NBI. For top level objects, it discusses which attributes are the keys and which attributes must be set in the create request for that object. There are also ...
66
 productcatalog—Contains the XML file version of the complete Prime Collaboration Provisioning product catalog. In the product catalog directory, there are two subdirectories: the schema subdirectory that has an XSD file that defines all products sup...
66
 sample—Contains the Java, bat, and XML files for building and running sample clients. Also included are sample create requests for configuration objects.
66
 wsdl-xsd—Contains all WSDL and XSD files that define the Prime Collaboration Provisioning NBI.
66
Setting Up the Sample Java Clients
66
After setting up your environment, either on your Prime Collaboration Provisioning system or on another system, go to the CUPM\sep\ipt\nbi-sdk\sample directory.
66
The build.xml file in this directory creates the subdirectories output and image. The output directory contains all generated class, jar, zip, and other targets. The image directory is the installable image that can be run from here when referenced wi...
66
Use the build-install-all target to run all the Ant targets required to prepare the clients and to prepare and deploy the notification consumer service.
66
The build.xml file provides the following targets:
66
 build-install-all—Compiles and builds clients, and compiles, builds, and installs notification consumer.
66
 build-clients—Only builds clients.
66
 compile-clients—Java compilation.
66
 lib-clients—Creates jar files for clients.
66
 image-clients—Adds the clients to the installable image directory.
66
 build-consumer—Builds only the notification consumer service.
66
 compile-consumer-schema
66
 compile-consumer-src
66
 lib-consumer
66
 image-consumer
67
After you have built an image, or installed an image on another platform, run the following Ant commands from the CUPM\sep\ipt\nbi-sdk\sample directory:
67
 setup-axis2-tomcat—Generates an AXIS2.war file from a new AXIS2 installation, then copies and expands that AXIS2.war file into a Tomcat installation.
67
 deploy-consumer—Installs the notification consumer in a version of Tomcat with AXIS2 installed and expanded.
67
Running SDK Sample Clients
67
After you have prepared your image directory, run the SDKSetup.bat command to set the appropriate environment variables and test the connection with the simple ping command. If you prefer to manually prepare your environment, set the environment varia...
67
You now have access to the following SDK commands:
67
 SdkQueryEnvVar—Displays all Environment Variables that are used by the SDK clients, along with their current settings.
67
 ValidateRequest <XML-File>—Validates an XML file that contains any NBI request. The SAX parser performs the validation against the appropriate XSD file.
67
 PingRequest <Optional Arguments>—Sends a ping request to the specified Prime Collaboration Provisioning server and sets the EPR to the notification consumer service.
67
Note: The Server URL and Notification Consumer URL can be specified by the environment variables, or by arguments on the command line. An argument of -h provides a description of the command arguments.
67
 SendXmlRequest <XML-File>—This client reads an XML file. It optionally substitutes the EPR in the file with the one specified by the environment variables. It optionally substitutes the setting for the idPrefix. It then sends the request and prints ...
67
Environment Variables
67
The sample NBI clients allow you to set the server information and notification either on the command line, or by using environment variables. The environment variables enable you to issue a set of requests to one server and receive notifications at o...
67
XML Sample Files
69
Included are examples of XML requests to create, update, get, delete, and list some network objects. Simple Orders to configure phones and lines are included.
69
Note: These requests will require editing to match your configuration.
69
The sample XML files are commented such that you can update them to match your environment. For example, for create device, at the minimum, you would need to set the IP address and the credentials to match your device.
69
Installing and Running the Prime Collaboration Provisioning NBI SDK
69
 Compiles and builds two sample clients.
70
 Compiles and builds an XML request validator utility.
70
 Compiles and builds a notification consumer service AAR file.
70
 Creates the axis2.war file.
70
 Installs and expands axis2.war in tomcat.
70
 Deploys the notification consumer service in axis2 in Tomcat.
70
e. Run SdkSetup.bat <pmadmin-password>. Run this bat file with your pmadmin user ID password as the first argument. This bat file performs the following:
70
 Sets the environment variable CUPM_NBI_SDK_COMMAND_HOME to the SDK command image built in the previous step (...\nbi-sdk\sample\image\CupmNbiSdkCommands).
70
 Adds CUPM_NBI_SDK_COMMAND_HOME to the path.
70
 Sets the following SDK environment variables:
70
o server.ipaddress=localhost
70
o notification.ipaddress=localhost
70
o cupm.user=pmadmin
70
o cupm.password=<bat-parameter>
70
 Runs the PingRequest client. As this runs, the data from the ping response is displayed. It shows the Prime Collaboration Provisioning version and the Prime Collaboration Provisioning NBI version. Also, the notification server status string is disp...
70
Note: The SdkSetup.bat is designed for the SDK and Prime Collaboration Provisioning to be installed on the same system and to use the default values for Prime Collaboration Provisioning’s account name and ports.
71
If any of the following apply to your installation of Prime Collaboration Provisioning, you will need to set the environment variables to your customized settings:
71
o Prime Collaboration Provisioning is installed on a system other than the SDK.
71
o The Prime Collaboration Provisioning account is not pmadmin.
71
o Port 80 is not used for the server.
71
o Port 8080 is not used for notification consumer.
71
o You are using your own notification consumer service.
71
If you have a configuration other than basic, run SdkSetup.bat and let it fail. Then use the command SET to set the environment variables to match your configuration.
71
a. Run SendXmlRequest xml\CreateDevice.xml. Sends the XML file CreateDevice.xml in the XML subdirectory to the server. This creates a fictitious device with IPT capabilities. As this runs, a response XML file appears and after a few seconds, the notif...
71
To create a real device, you must first edit the CreateDevice.XML file. Change the IP address and credential tags to match the real device.
71
b. Run SendXmlRequest xml\CreateDomain.xml. Sends the XML file CreateDomain.xml in the XML subdirectory to the server. This creates a Domain. As this runs, a response XML file appears. After about a minute, the Notification Result XML file appears in ...
71
c. Run SendXmlRequest xml\CreateServiceArea.xml. Sends the XML file CreateServiceArea.xml in the XML subdirectory to the server. This creates a Service Area within the Domain. As this runs, a response XML file appears. After a few seconds, the Notific...
71
d. Run SendXmlRequest xml\CreateSubscriber.xml. Sends the XML file CreateSubscriber.xml in the XML subdirectory to the server. This creates a subscriber within the Domain. As this runs, a response XML file appears. After a few seconds, the Notificatio...
71
e. Run SendXmlRequest xml\CreateSubscriber2.xml. Sends the XML file CreateSubscriber2.xml in the XML subdirectory to the server. This creates a second subscriber within the Domain. As this runs, a response XML file appears. After a few seconds, the No...
71
SDK Commands
72
Once you have installed the SDK and run SdkSetup, you will have access to the SDK commands from that command window. They can be run from any directory.
72
The following are the SDK commands:
72
 SendXmlRequest—Reads an XML file from disk. The first argument is the filename of the XML file, and the full path filename if this file is not in the current directory. This command will use the environment variable settings to modify the XML file b...
72
 ValidateRequest—Reads an XML file from disk. Without making any substitutions, the XML file is validated with the SAX parser against the appropriate XSD file to confirm that this is a valid XML file. File is valid appears if the file passes validati...
72
 PingRequest—Sends the ping request only. Nothing is read from disk. The instance is created and populated within Java. The ping request is used to test connectivity and credentials from the client to the server, and to test connectivity from the ser...
72
 SdkQueryEnvVar—Displays all environment variables that are used by the other commands, and their current settings.
72
 SdkVersion—Displays the date and time that the SDK commands were built.
72
NBI Prepopulation Requirements
72
The ListProductAttributeChoice request is often referred to as the prepopulation NBI. It is designed to return choice lists for attributes in a product. The choice lists can be either complete choice lists or context-based choice lists dependent on ot...
72
Table 11 lists any additional requirements, limitations, and restrictions for returning choice lists for the attributes in a product.
72
Setting Up the Perl NBI Client
73
A sample Perl client is included in the subdirectory perl/pm.
73
Requirements
73
Perl 5.10.0 is required. The NBI client was developed and tested with ActivePerl, which offers free downloads of the ActivePerl interpreter. The ActivePerl-5.10.0.1005-MSWin32-x86-290470.msi file was used. You should run the installation file, rather ...
73
Common Properties
73
The Perl client uses the same environment variables that the Java client does for the Prime Collaboration Provisioning Server EPR and credentials, and for the notification EPR. Environment variables can be used throughout the session for every request...
73
XML Template Usage
73
The Perl client uses XML templates for sending the requests. Each template contains the full SOAP envelope for the command. Keywords are substituted by the user-specified values, resulting in a valid XML request that is then sent to the server.
73
Supported Requests
74
The sample Perl client supports the following requests:
74
 ping
74
 pull
74
 listDomain
74
 listSubscriber
74
The architecture allows extension of additional commands by adding a Perl Module (.pm) file to the subdirectory modules, and a corresponding XML template file to the subdirectory XML/CUPMRequest.
74
Usage (Sample Session)
74
The Perl client is run from the command line. It must be run from the perl/pm subdirectory, unless that subdirectory is added to the system path environment variable.
74
The command is pm.pl. Enter the command with no arguments or with –h for online help.
74
The command takes one argument, the request name. Additional properties can be assigned with the –D prefix.
74
Sample Session
74
The following commands will ping a server and then retrieve a Domain list from it:
74
1. Set up the environment variables:
75
2. Run the perl client: pm.pl ping. Sends the ping request. The Prime Collaboration Provisioning version and the Prime Collaboration Provisioning NBI version are returned in the response and displayed.
75
3. Run pm.pl ping -Dserver.ipaddress=11.22.33.44 -Dcupm.password=diffpassword. Sends a ping request to a different server, temporarily overriding the environment variable settings.
75
4. Run pm.pl listDomain. Sends the listDomain command. The NBI ID is returned in the response and displayed.
75
5. Run pm.pl pull -Dobject.name=<NBI-ID-RETURNED-BY-ABOVE-LIST>. Returns the first element of the list of Domains.
75
6. Run pm.pl pull -Dobject.name=<NBI-ID-RETURNED-BY-ABOVE-LIST> -Dpull.count=1000. Returns the remaining objects on the list, up to 1000.
75
7. The listDomain and the listSubscriber requests provide the functionality to automatically pull all the items in the list immediately after the list is generated. This is triggered by setting the pull.count environment variable to a positive value.
75
For example: pm.pl listSubscriber -Dpull.count=5
75
This sends a request for a list of all the subscribers in the system. It waits for the notification consumer to write the notification to disk. Then it pulls the list back in increments of five until the end of sequence attribute is received.
75
Note: For this functionality to work, you must compile the NotificationConsumerService after uncommenting the call to the method saveMessageResult.
75
Appendix B: Troubleshooting
76
This appendix provides troubleshooting information.
76
FAQs
76

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

81

Size:

1.17 MB
Pages:

81
Language:

English

Open manual

Getting Started Guide

Size:

559 KB
Pages:

2
Language:

English

Open manual

Documentation Roadmaps

Size:

149 KB
Pages:

6
Language:

English

Open manual

Licensing Information

Size:

1.26 MB
Pages:

312
Language:

English

Open manual

Release Notes

Size:

239 KB
Pages:

14
Language:

English

Open manual

Licensing Information

Size:

1.26 MB
Pages:

307
Language:

English

Open manual

Installation Guide

Size:

165 KB
Pages:

6
Language:

English

Open manual

Licensing Information

Size:

4.84 MB
Pages:

2406
Language:

English

Open manual

Licensing Information

Size:

4.83 MB
Pages:

2402
Language:

English

Open manual

Cisco Cisco Prime Collaboration 10.5 User Manuals

User Guide

Table of Contents

Developer's Guide

Table of Contents

Getting Started Guide

Documentation Roadmaps

Licensing Information

Release Notes

Licensing Information

Installation Guide

Licensing Information

Licensing Information