Cisco Cisco Prime Collaboration Provisioning 11.0 User Manuals

Table of Contents

• 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
• Overview of Request Arguments

  13
• Create<Object>

  13
• Get<Object>

  13
• Delete<Object>

  13
• Update<Object>

  13
• List<Object>

  13
• Configurable Properties

  13
• Prime Collaboration Provisioning NBI Objects

  13
• Device

  13
• Key attribute: deviceName

  13
• Domain

  14
• Key attribute: domainID

  14
• ServiceArea

  14
• Key attributes: serviceAreaID

  14
• InventoryItem

  14
• ServiceDetail

  14
• Order

  14
• Subscriber

  14
• Key attribute: subscriberID

  14
• CupmApiListValue

  14
• CupmApiResponseValue

  15
• CupmApiResultValue

  15
• CupmApiStatusValue

  15
• CupmApiFilterValue

  16
• Complete Object Definition File: Common.xsd

  17
• Infrastructure Product Key Attributes

  17
• Subscriber Product Key Attributes

  19
• Referencing Product Attributes from the Product Catalog

  19
• <item>

  20
• <attributeValue>

  20
• <productAttribute>

  20
• <<item>

  20
• Prime Collaboration Provisioning NBI Requests

  21
• Request Signature Class

  21
• Device Management Commands and Queries

  21
• createDevice Java Signature

  21
• getDevice Java Signature

  22
• updateDevice Java Signature

  23
• listDevice Java Signature

  23
• deleteDevice Java Signature

  24
• getConfiguredInfraProduct Java Signature

  25
• ASyncReturn:

  26
• listConfiguredInfraProduct Java Signature

  26
• Domain Management Commands and Queries

  26
• createDomain Java Signature

  26
• getDomain Java Signature

  27
• updateDomain Java Signature

  28
• listDomain Java Signature

  28
• deleteDomain Java Signature

  29
• Service Area String Management Commands and Queries

  30
• createServiceArea Java Signature

  30
• getServiceArea Java Signature

  31
• updateServiceArea Java Signature

  32
• listServiceArea Java Signature

  32
• deleteServiceArea Java Signature

  34
• Synchronization Management Commands

  34
• syncDevice Java Signature

  34
• syncDomain Java Signature

  35
• Subscriber Management Commands and Queries

  36
• createSubscriber Java Signature

  36
• createSubscribers Java Signature

  37
• getSubscriber Java Signature

  37
• updateSubscriber Java Signature

  38
• listSubscriber Java Signature

  39
• deleteSubscriber Java Signature

  40
• resetSubscriberServicePassword Java Signature

  40
• unlockVoiceMail Java Signature

  41
• listSubscriberService Java Signature

  42
• getSubscriberService Java Signature

  43
• moveService Java Signature

  44
• moveSubscriber Java Signature

  44
• 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
• 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
• Inventory Queries

  51
• getInventoryItem Java Signature

  51
• listInventoryItem Java Signature

  52
• Prepopulation

  52
• listProductAttributeChoice Java Signature

  52
• 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.

  52
• Syntax:

  52
• public ResponseReturn listProductAttributeChoice (CUPMServiceStub stub, String[] arrayOfAttributes, ProductValue product, CupmApiFilterValue filter, String endPointReference, String idPrefix);

  52
• Parameters:

  53
•  product—The product specified for the return choice list, containing all attributes that have already been set.

  53
•  arrayOfAttributes—Each attribute for which a choice list will be returned.

  53
•  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...

  53
•  endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.

  53
•  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.

  53
• Returns:

  53
• CupmApiResponseValue—Object with NBI ID.

  53
• Throws:

  53
• ListProductAttributeChoiceException—If the server cannot execute the NBI request.

  53
• ASyncReturn:

  53
•  CupmApiResultValue, containing CupmApiStatus and CupmApiList. CupmApiList contains the choice lists requested for the product attributes.

  53
•  CupmApiFaultType—Included if the NBI request fails.

  53
• Prime Collaboration Provisioning NBI Status Queries

  53
• getApiStatus Java Signature

  53
• Returns the status of a specific NBI request. If the execution of the command has been completed, an attached CupmApiResultValue is also returned.

  53
• Syntax:

  53
• public ResponseReturn getApiStatus (CUPMServiceStub stub, String apiId, String endPointReference, String idPrefix);

  53
• Parameters:

  53
•  apiId—The NBI ID of the command status to return.

  53
•  endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.

  54
•  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.

  54
• Returns:

  54
• CupmApiResponseValue—Object with NBI ID.

  54
• Throws:

  54
• GetApiStatusExcepton—If the server cannot execute the NBI request.

  54
• SyncReturn:

  54
•  CupmApiResponseValue—Contains CupmApiResultValue, which contains CupmApiStatus and CupmApiList. The list contains one object, the CupmApiStatus for the NBI request specified in the request.

  54
•  CupmApiFaultType—Included if the NBI request fails.

  54
• AsyncReturn:

  54
• None—The command is synchronous.

  54
• Note: The command will fail if the server has purged the NBI request.

  54
• listApiStatus Java Signature

  54
• Returns the status of all outstanding NBI requests this client has submitted.

  54
• Syntax:

  54
• public ResponseReturn listApiStatus (CUPMServiceStub stub, CupmApiFilterValue filter, String endPointReference, String idPrefix);

  54
• Parameters:

  54
• filter—Limited filtering of the NBI requests returned.

  54
• You can filter using the following attribute:

  54
•  status

  54
•  endPointReference—String to convert to an EndpointReference object that the asynchronous result notification will be sent to.

  54
•  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
• ListApiStatusExcepton—If the server cannot execute the NBI request.

  55
• SyncReturn:

  55
•  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.

  55
•  CupmApiFaultType—Included if the NBI request failed or had warnings.

  55
• Async return:

  55
• None—The command is synchronousSpecialized Requests

  55
• listSrstPhoneInfo Java Signature

  55
• 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...

  55
• Syntax:

  55
• public ResponseReturn listSrstPhoneInfo (CUPMServiceStub stub, String cpIpAddr, String srstIpAddr, String queryOption, String endPointReference, String idPrefix);

  55
• Paramaters:

  55
•  cpIpAddr—IP address of the Call Processor.

  55
•  srstIpAddr—IP address of the SRST.

  55
•  queryOption—The data selection criteria, defined by the PhoneInfoqueryOption enumeration.

  55
• o ALL—(Default) all phones in Prime Collaboration Provisioning will be considered.

  55
• o IN_CUPM_SUBSCRIBER_RECORD—Only the phones that are in the Prime Collaboration Provisioning subscriber record will be selected.

  55
• 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.

  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 NBI ID. A null or empty string is valid for no changes to the internal generation.

  56
• Returns:

  56
• CupmApiResponseValue—Object with NBI ID.

  56
• Throws:

  56
• ListSrstPhoneInfoException—If server cannot execute NBI request.

  56
• ASyncReturn:

  56
•  CupmApiResultValue—Contains CupmApiStatus and CupmApiList. CupmApiList contains the WS-Enumeration context object, which is used as the key to pull the list.

  56
•  CupmApiFaultType—Included if the NBI request fails.

  56
• getOrderSummary Java Signature

  56
• Syntax:

  56
• public ResponseReturn getOrderSummmary (CUPMServiceStub stub, Calendar startTime, Calendar endTime, String endPointReference, String idPrefix);

  56
• Parameters:

  56
•  startTime—The beginning of the time period to report on. If not specified, the value defaults to the earliest known work order.

  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 NBI ID. A null or empty string is valid for no changes to the internal generation.

  56
• Returns:

  56
•  CupmApiResponseValue—Object with NBI ID.

  56
• Throws:

  56
•  GetOrderSummaryException—If server cannot execute NBI request.

  57
• ASyncReturn:

  57
•  CupmApiResultValue—Contains CupmApiStatus and CupmApiList. CupmApiList contains one object, the OrderSummary object

  57
•  CupmApiFaultType—Included if the NBI request fails.

  57
• submitConfigTemplate Java Signature

  57
• 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.

  57
• Syntax:

  57
• public ResponseReturn submitConfigTemplate (CUPMServiceStub stub, ConfigDetailValue configDetail, String validate, String rollback, String endPointReference, String idPrefix);

  57
• Parameters:

  57
•  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.

  57
•  validate—VALIDATE, SUBMIT, or VALIDATE_AND_SUBMIT are the settings for this enumeration.

  57
•  rollback—PARTIAL_ROLLBACK setting.

  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. Null or empty string valid for no change to internal generation.

  57
• Returns:

  57
• CupmApiResponseValue—Object with NBI ID.

  57
• Throws:

  57
• submitConfigTemplateException—If server cannot execute NBI request.

  57
• ASyncReturn:

  57
•  CupmApiResultValue—Contains CupmApiStatus and CupmApiList. CupmApiList contains status of the execution of the Cisco IOS commands on the device.

  57
•  CupmApiFaultType—Included if the NBI request fails.

  57
• listConfigTemplateKeyword Java Signature

  58
• 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.

  58
• Syntax:

  58
• public ResponseReturn listConfigTemplateKeyword (CUPMServiceStub stub String templateName, String endPointReference, String idPrefix);

  58
• Parameters:

  58
•  templateName—Name identifying the template for which to return the list of keywords.

  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. Null or empty string valid for no change to internal generation.

  58
• Returns:

  58
• CupmApiResponseValue—Object with NBI ID.

  58
• Throws:

  58
• listConfigTemplateException—If server cannot execute NBI request.

  58
• ASyncReturn:

  58
•  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.

  58
•  CupmApiFaultType—Included if the NBI request fails.

  58
• WS-Enumeration Requests

  58
• 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...

  58
•  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.

  58
•  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.

  58
•  GetAPIStatus—Returns the status of an enumeration context, such as the expiration time.

  58
•  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.

  59
• Note: The objects used in the Java code can be imported from org.xmlsoap.schemas.ws.x2005.x09.enumeration.

  59
• pullOp Java Signature

  59
• 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 ...

  59
• Syntax:

  59
• public ResponseReturn pullOp (CUPMServiceStub stub, wsen:EnumerationContext, wsen:MaxElements, pullSize);

  59
• Parameters:

  59
•  wsen:EnumerationContext—The latest version of this object that the client has received from the server.

  59
•  wsen:MaxElements, pullSize—The number of objects to return with this request.

  59
• Returns:

  59
• Standard Pull response.

  59
• Throws:

  59
•  RemoteExcepton—If the server cannot execute the NBI request.

  59
• SyncReturn:

  59
• 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 ...

  59
• CupmApiFaultType—Included if the NBI request fails.

  59
• renewOp Java Signature

  59
• 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...

  59
• Syntax:

  59
• public ResponseReturn renewOp (CUPMServiceStub stub, wsen:EnumerationContext enumerationContext, XmlCalendar Date or Duration duration);

  60
• 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.

  60
• The NBI properties control the maximum number of times an expiration date can be increased.

  60
• Parameters:

  60
•  wsen:EnumerationContext—The latest version of this object that the client has received from the server.

  60
•  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.

  60
• Returns:

  60
• Standard WS-Enumeration Renew response message.

  60
• Throws:

  60
• Remote Exception—If the server cannot execute the NBI request.

  60
• SyncReturn:

  60
• Returns the new expiration date.

  60
• getStatusOp Java Signature

  60
• Updates the ApiEnumerator object.

  60
• Syntax:

  60
• public ResponseReturn getStatusOp (CUPMServiceStub stub, wsen:EnumerationContext enumerationContext);

  60
• Parameters:

  60
• wsen:EnumerationContext—The latest version of this object that the client has received from the server.

  60
• Returns:

  60
• Standard WS-Enumeration getStatus response message.

  60
• Throws:

  60
• RemoteException—If the server cannot execute the NBI request.

  60
• SyncReturn:

  60
• Returns the current expiration date.

  61
• releaseOp Java Signature

  61
• Tells the server that the client is done with the data and it may be purged.

  61
• Syntax:

  61
• public ResponseReturn release (CUPMServiceStub stub, wsen:EnumerationContext enumerationContext);

  61
• Parameters:

  61
• wsen:EnumerationContext—The latest version of this object that the client has received from the server.

  61
• Returns:

  61
• WS-Enumeration standard Release response message.

  61
• Throws:

  61
• RemoteException—If the server cannot execute the NBI request.

  61
• SyncReturn:

  61
• A response with no parameters.

  61
• Prime Collaboration Provisioning NBI Implementation of WS-Notification

  61
• 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 ...

  61
• There are no cases where the Prime Collaboration Provisioning server will send a message to the client unsolicited.

  61
• Notification Consumer Service

  61
• 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.

  61
• The default functionality for this service is to receive the notification on port 8080 and display the notification in the Tomcat console window.

  61
• 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...

  62
• 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.

  62
• Appendix A: Sample Clients

  63
• 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:

  63
•  Introduction

  63
•  Setting Up the Prime Collaboration Provisioning NBI SDK Development Environment

  63
•  Setting Up the Sample Java Clients

  63
•  Setting Up the Perl NBI Client

  63
• Introduction

  63
• 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.

  63
• 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.

  63
• 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.

  63
• Setting Up the Prime Collaboration Provisioning NBI SDK Development Environment

  63
• 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...

  63
• Overview of Prime Collaboration Provisioning NBI SDK Directory

  63
• 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:

  63
•  doc—User documentation.

  63
•  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.

  63
• 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 ...

  64
•  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...

  64
•  sample—Contains the Java, bat, and XML files for building and running sample clients. Also included are sample create requests for configuration objects.

  64
•  wsdl-xsd—Contains all WSDL and XSD files that define the Prime Collaboration Provisioning NBI.

  64
• Setting Up the Sample Java Clients

  64
• 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.

  64
• 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...

  64
• 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.

  64
• The build.xml file provides the following targets:

  64
•  build-install-all—Compiles and builds clients, and compiles, builds, and installs notification consumer.

  64
•  build-clients—Only builds clients.

  64
•  compile-clients—Java compilation.

  64
•  lib-clients—Creates jar files for clients.

  64
•  image-clients—Adds the clients to the installable image directory.

  64
•  build-consumer—Builds only the notification consumer service.

  64
•  compile-consumer-schema

  64
•  compile-consumer-src

  64
•  lib-consumer

  64
•  image-consumer

  65
• 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:

  65
•  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.

  65
•  deploy-consumer—Installs the notification consumer in a version of Tomcat with AXIS2 installed and expanded.

  65
• Running SDK Sample Clients

  65
• 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...

  65
• You now have access to the following SDK commands:

  65
•  SdkQueryEnvVar—Displays all Environment Variables that are used by the SDK clients, along with their current settings.

  65
•  ValidateRequest <XML-File>—Validates an XML file that contains any NBI request. The SAX parser performs the validation against the appropriate XSD file.

  65
•  PingRequest <Optional Arguments>—Sends a ping request to the specified Prime Collaboration Provisioning server and sets the EPR to the notification consumer service.

  65
• 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.

  65
•  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 ...

  65
• Environment Variables

  65
• 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...

  65
• XML Sample Files

  67
• 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.

  67
• Note: These requests will require editing to match your configuration.

  67
• 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.

  67
• Installing and Running the Prime Collaboration Provisioning NBI SDK

  67
•  Compiles and builds two sample clients.

  68
•  Compiles and builds an XML request validator utility.

  68
•  Compiles and builds a notification consumer service AAR file.

  68
•  Creates the axis2.war file.

  68
•  Installs and expands axis2.war in tomcat.

  68
•  Deploys the notification consumer service in axis2 in Tomcat.

  68
• 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:

  68
•  Sets the environment variable CUPM_NBI_SDK_COMMAND_HOME to the SDK command image built in the previous step (...\nbi-sdk\sample\image\CupmNbiSdkCommands).

  68
•  Adds CUPM_NBI_SDK_COMMAND_HOME to the path.

  68
•  Sets the following SDK environment variables:

  68
• o server.ipaddress=localhost

  68
• o notification.ipaddress=localhost

  68
• o cupm.user=pmadmin

  68
• o cupm.password=<bat-parameter>

  68
•  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...

  68
• 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.

  69
• 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:

  69
• o Prime Collaboration Provisioning is installed on a system other than the SDK.

  69
• o The Prime Collaboration Provisioning account is not pmadmin.

  69
• o Port 80 is not used for the server.

  69
• o Port 8080 is not used for notification consumer.

  69
• o You are using your own notification consumer service.

  69
• 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.

  69
• 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...

  69
• 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.

  69
• 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 ...

  69
• 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...

  69
• 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...

  69
• 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...

  69
• SDK Commands

  70
• 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.

  70
• The following are the SDK commands:

  70
•  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...

  70
•  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...

  70
•  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...

  70
•  SdkQueryEnvVar—Displays all environment variables that are used by the other commands, and their current settings.

  70
•  SdkVersion—Displays the date and time that the SDK commands were built.

  70
• NBI Prepopulation Requirements

  70
• 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...

  70
• Table 11 lists any additional requirements, limitations, and restrictions for returning choice lists for the attributes in a product.

  70
• Setting Up the Perl NBI Client

  71
• A sample Perl client is included in the subdirectory perl/pm.

  71
• Requirements

  71
• 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 ...

  71
• Common Properties

  71
• 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...

  71
• XML Template Usage

  71
• 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.

  71
• Supported Requests

  72
• The sample Perl client supports the following requests:

  72
•  ping

  72
•  pull

  72
•  listDomain

  72
•  listSubscriber

  72
• 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.

  72
• Usage (Sample Session)

  72
• 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.

  72
• The command is pm.pl. Enter the command with no arguments or with –h for online help.

  72
• The command takes one argument, the request name. Additional properties can be assigned with the –D prefix.

  72
• Sample Session

  72
• The following commands will ping a server and then retrieve a Domain list from it:

  72
• 1. Set up the environment variables:

  73
• 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.

  73
• 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.

  73
• 4. Run pm.pl listDomain. Sends the listDomain command. The NBI ID is returned in the response and displayed.

  73
• 5. Run pm.pl pull -Dobject.name=<NBI-ID-RETURNED-BY-ABOVE-LIST>. Returns the first element of the list of Domains.

  73
• 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.

  73
• 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.

  73
• For example: pm.pl listSubscriber -Dpull.count=5

  73
• 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.

  73
• Note: For this functionality to work, you must compile the NotificationConsumerService after uncommenting the call to the method saveMessageResult.

  73
• Appendix B: Troubleshooting

  74
• This appendix provides troubleshooting information.

  74
• FAQs

  74
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78
• 

  78