Cisco Prime Cable Provisioning Integration Developers Guide, 6.0
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
- Updated:
- February 22, 2015
Chapter: Provisioning Web Services APIs
Provisioning Web Services (PWS)
This chapter provides an overview of PWS, and describes the PWS data types, PWS operations, and some sample use cases of PWS usage in Prime Cable Provisioning.
Overview
The Provisioning Web Services (PWS) component provides a SOAP based web interface that supports provisioning operation. The provisioning services include functionalities such as: adding, retrieving, updating, and removing objects necessary to support the provisioning and configuration generation of CPEs. The PWS objects include devices, classes of service, DHCP criteria, groups, and files.
The PWS component manages the following activities:
- Exposes a provisioning web service that provides functionality similar to the current API client.
- Supports stateless interactions.
- Supports both synchronous and asynchronous requests.
- Supports singular and plural operations.
- Supports both stop on failure and ignore on failure.
- Supports request that can operate on multiple objects.
- Supports SOAP v1.1 and 1.2.
- Supports WSDL v1.1.
- Support WS-I Basic Profile v1.1.
- Support both HTTP and HTTPS transport.
The web service is hosted on a Tomcat container, and it is recommended that you install it on a separate server.
For more information on PWS, see the Cisco Prime Cable Provisioning 6.0 User Guide.
PWS Concepts
The PWS component provides the following functionalities for running an operation on the device:
The session management functionality enables you to establish a session between the WS client and the RDU to process multiple requests from WS client. A WS client can establish connection with multiple RDUs simultaneously. The client runs a createSession operation, and in response receives a context object on successful authentication. The context object identifies the session between the client and the RDU, and can be used as an authentication token to run all the requests in the session.
The client closes the session after processing all the requests. The session also gets closed automatically after a configured period of idle time. The default idle timeout is configured using a command line script for all the sessions. If the session gets closed and the client tries to reestablish the session, the session gets reestablished with the same session id.
The PWS operations can be classified into two categories:
- Single device operations - One operation for a single device. For single device operations, an operation is a single transaction in which all the changes are made or no change is made to the device.
- Multiple device operations - One operation for multiple devices. For multiple device operations, the transaction scope can be set to include all devices, or have each device change in its individual transaction.
You can set the execution option, transactionPerItem, to true to retrieve the transaction data for each batch. The OperationStatus returned will contain the status of the entire operation as well as the individual status if multiple transactions are used.
When a PWS operation fails, you may receive the following SOAP faults:
PWS Data Types
The following data types are defined in WSDL that are supported by PWS:
- DeviceType - Attribute that defines the type of the device. For example, Computer; DOCSISModem; PacketCableMTA; CableHomeWanMan; CableHomeWanData; STB: eRouter.
- ClassOfService (COS) - Attribute that defines the class of service.
- DHCPCriteria - Attribute that defines the DHCP criteria.
- File - Attribute the defines the static configuration file, groovy scripts or dynamic configuration files, jar files, MIB files, template files, firmware image, and other generic files.
- Group - Attribute that defines a group. The devices are assigned to a group based on a specific logical criterion.
- Context - Attribute that defines the authentication data for a client or a client's session.
- Options - Attribute that helps you to customize the WS client’s request either at the PWS level or the RDU level. The Options data type is categorized into the following two types:
–
Execution Options - Used to customize the execution process of the WS client’s request. For example, you can run the client’s request in reliable mode. In case of reliable mode, when the RDU receives a reliable request, the RDU persists the batch until it executes successfully. If the RDU restarts or the WS client restarts, a record of the Batch is retained. The RDU stores the last 1000 reliable batch responses.
Table 8-1 describes the execution options for PWS client’s request.
– Operation Options - Used to customize the operation process of WS client’s request. For example, to retrieve the lease data from a getDevice() request, add the flag includeLeaseInfo in the getDevice() request and set its value to True. The individual properties of the lease data are retrieved in the response. If you want to delete the devices behind the managed device, add the flag deletedevicesbehind in the deleteDevice() or deleteDevices() request and set its value to True.
- DeviceId - Attribute that allocates a unique identity to the device. The supported unique identities are types of device ids such as MACAddressType, DUIDType and FQDNType.
- Properties - Attribute that defines the provisioning criteria for the devices. The provisioning criteria is defined in terms of key-value list, where the key and value are both strings.
- SearchResult - Attribute that is used to retrieve the search results.
- Search - Attribute used to search devices, files, and groups based on a specific logical criterion. The QueryType attribute is used to define the logical criterion for the search operation. Table 8-2 describes the supported logical criteria for the search operation.
- PropertyFilter - Attribute that specifies the properties that you want to include in the response. If the PropertyFilter data type is set, only the listed properties will be returned.
- OperationStatus - Attribute that displays the response of a web service operation.
- DeviceOperationStatus - Attribute that displays the response of a web service operation on devices that involves returning operation result for multiple devices. In addition to the attributes of OperationStatus data type, this object also includes a device object. On success a device object with a SUCCESS code is returned. On failure, the operation status is returned with the description about the issue/failure.
- DevicesBehindOperationStatus - Attribute that displays the response of a web service operation on list of devices behind the specified devices.
- DeviceTypeOperationStatus - Attribute that displays the response of a web service operation on a specific device type, for example; Computer, DOCSISModem, PacketCableMTA, CableHomeWanMan, CableHomeWanData, STB, and eRouter. In addition to the attributes of OperationStatus data type, this object also includes a DeviceType object. On success, a DeviceType object with a SUCCESS code is returned. On failure, the operation status is returned with the description about the issue/failure.
- LeaseResultsOperationStatus - Attribute that displays the response of a web service operation for DHCP lease information query. In addition to the attributes of OperationStatus data type, this object also includes a DHCPLeaseinfo object. On success a DHCPLeaseinfo object with a SUCCESS code is returned. On failure, the operation status is returned with the description about the issue/failure.
- ClassOfServiceOperationStatus - Attribute that displays the response of a web service operation for a class of service query. In addition to the attributes of OperationStatus data type, this object also includes a ClassOfService object. On success a ClassOfService object with a SUCCESS code is returned. On failure, the operation status is returned with the description about the issue/failure.
- DHCPCriteriaOperationStatus - Attribute that displays the response of a web service operation for a DHCP criteria query. In addition to the attributes of OperationStatus data type, this object also includes a DHCPCriteria object. On success a DHCPCriteria object with a SUCCESS code is returned. On failure, the operation status is returned with the description about the issue/failure.
- FileOperationStatus - Attribute that displays the response of a web service operation for a File query. In addition to the attributes of OperationStatus data type, this object also includes a File object. On success, a File object with a SUCCESS code is returned. On failure, the operation status is returned with the description about the issue/failure.
- GroupOperationStatus - Attribute that displays the response of a web service operation for a group query. In addition to the attributes of OperationStatus data type, this object also includes a Group object. On success, a Group object with a SUCCESS code is returned. On failure, the operation status is returned with the description about the issue/failure.
PWS Operations
A Java like syntax is used to denote the operations of the Provisioning Web Service.
This section includes the following PWS operations:
- Session Operations
- Device Provisioning Operations
- DeviceType Operations
- Generic Device Operation
- Class Of Service Operations
- DHCP Criteria Operations
- File Operations
- Group Operations
- pollOperation Status
Session Operations
Device Provisioning Operations
|
|
OperationStatus addDevice (Context context, Device device, Options options) |
|
|
|
|
|
Device argument must not be null. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in device being added to Prime Cable Provisioning database. A failure will result in no change to the database. |
|
|
|
|
|
See Table 8-1 . |
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to add the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The device objects contains invalid or missing data. |
|
|
OperationStatus addDevices (Context context, List<Device> devices, Options options) |
|
|
Submit a request to add multiple new devices. Using the execution options, each device can be wrapped in a separate transaction (batch) or a single transaction. |
|
|
List of device argument must not be null. Options argument is optional. If null, default execution options will be used. |
|
|
A OperationStatus object is returned. A successful call will result in all device being added to Prime Cable Provisioning database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to add the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The device objects contains invalid or missing data. |
|
|
DeviceOperationStatus getDevice (Context context, DeviceId deviceId, PropertyFilter filter, Options options) |
|
|
|
|
|
A valid device ID must be provided. PropertyFilter argument is optional. If null, all properties are returned. Otherwise all properties specified will be returned. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in device data being returned otherwise a fault will be returned. |
|
|
See Table 8-1 . |
|
|
includeLeaseInfo - Include DHCP lease info in both IPv4 and IPv6 in the result. DHCP lease information will be retrieved from provisioning group DHCP server(s). If no DHCP server responds, an error condition is returned. If a DHCP server does respond, but there is no active lease, no lease information will be included in the result and there will be no error returned. |
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The device id contains invalid or missing data or uniqueness constraints were violated. Device does not exist. |
|
|
List<DeviceOperationStatus> getDevices(Context context, List<DeviceId> deviceId, PropertyFilter filter, Options options) |
|
|
|
|
|
A list of valid device ID must be provided. List must contain at least one entry. PropertyFilter argument is optional. If null, all properties are returned. Otherwise all properties specified will be returned. Is present, will apply to all devices. Options argument is optional. If null, default execution options will be used. Options present will apply to all devices. |
|
|
A successful call will result in list of DeviceOperationStatus being returned. |
|
|
See Table 8-1 . |
|
|
includeLeaseInfo - Include DHCP lease info in both IPv4 and IPv6 in the result. DHCP lease information will be retrieved from provisioning group DHCP server(s). If no DHCP server responds, an error condition is returned. If a DHCP server does respond, but there is no active lease, no lease information will be included in the result and there will be no error returned. |
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access – There is no limitation on the number of concurrent access of this operation. |
|
|
ProvServiceException – The device id contains invalid or missing data or uniqueness constraints were violated. Device does not exist. |
|
|
DevicesBehindOperationStatus getDevicesBehindDevice(Context context, DeviceIdSet deviceId, PropertyFilter propertyFilter, Options options) |
|
|
Retrieve the list of devices downstream of a specific device. Either the device ids or the entire device object is returned. |
|
|
A valid device ID must be provided. PropertyFilter argument is optional. If null, all properties are returned. Otherwise all properties specified will be returned. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in the DevicesBehindOperationStatus object which in turn includes the list of device objects. This operation will only return device ids or device objects that are behind this device. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. The operation will fail if the specified device has more than 100 devices behind it, and the attribute stopOnFailure is set to True. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The device id contains invalid or missing data or device does not exist |
|
|
List<DevicesBehindOperationStatus> getDevicesBehindDevices(Context context, List<DeviceIdSet> deviceId, PropertyFilter propertyFilter, Options options) |
|
|
Retrieve the list of devices downstream of the specified devices. Either the device IDs or the entire device object is returned. |
|
|
A valid list of device IDs must be provided containing at least one device id. PropertyFilter argument is optional. If null, all properties are returned. Otherwise all properties specified will be returned. Is present, will apply to all devices. Options argument is optional. If null, default execution options will be used. Options present will apply to all devices. |
|
|
A successful call will result in the list of DevicesBehindOperationStatus which in turn holds the list of target devices. This operation will only return device ids or device objects that are behind the devices. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. For 5.0 only, supports transactionPerItem set to true. The operation will fail if the specified device has more than 100 devices behind it, and the attribute stopOnFailure is set to True. |
|
|
ProvServiceException – The device id contains invalid or missing data or device does not exist. |
|
|
OperationStatus updateDevice(Context context, DeviceId deviceId, Device device, PropertiesToDelete propertiesToDelete, GroupsToUnassign groupsToUnassign, Options options) |
|
|
|
|
|
A valid Device ID must be provided. A valid Device must be provided to serve as a template of changes to make. Any non-null value will be used to update that respective field. All property and their values found in Properties will be either added if the property does not exist or updated if it does exist. PropertiesToDelete specifies those properties to be removed from the Device object. Options argument is optional. If null, default execution options will be used. |
|
|
|
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object and its properties. Concurrent Access - There is no limitation on the number of concurrent access of this operation. However, if multiple calls to update the same object are made, the last update will win. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The Device contains invalid data or specifies non-existent device. |
|
|
OperationStatus updateDevices(Context context, List<DeviceId> deviceId, Device device, PropertiesToDelete propertiesToDelete, GroupsToUnassign groupsToUnassign, Options options) |
|
|
This operation applies the data associated with a specific device object to all the devices specified in the list of device IDs. The properties that are excluded for this operation are deviceIds, hostName, fqdn, and embeddedDevices. |
|
|
A valid list of DeviceId must be provided containing at least one device id. A valid Device must be provided to serve as a template of changes to make. Any non-null value will be used to update that respective field. The changes will be applied to all specified devices. All property found in Properties will be either added if the property does not exist or updated if it does exist. PropertiesToDelete specifies those properties to be removed from the Device object. Options argument is optional. If null, default execution options will be used. Options present will apply to all devices. If present in the device object passed into this operation, the changing device id is ignored in this operation. |
|
|
A list of OperationStatus objects will be returned. A successful call will result in all devices being updated. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object and its properties. Concurrent Access - There is no limitation on the number of concurrent access of this operation. However, if multiple calls to update the same object are made, the last update will win. |
|
|
ProvServiceException – The Device contains invalid data or specifies non-existent device. |
|
|
OperationStatus deleteDevice(Context context, DeviceId deviceid, Options options) |
|
|
|
|
|
A valid DeviceId must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
An OperationStatus object will be returned. A successful call will result in device being deleted. |
|
|
See Table 8-1 . |
|
|
deleteDevicesBehind– A boolean flag to determine whether to delete the devices (if any) behind the specified IP device. If deleteDevicesBehind flag is set to “true”, all devices behind the specified device will be deleted. If deleteDevicesBehind flag is set to “false”, unregistered devices behind the specified device will be deleted. Registered devices will have their discovered DHCP data and provisioning group relationship delete leaving only their registered data. The default value is false. |
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required arguments or DeviceId is missing or specifies non-existent device. |
|
|
OperationStatus deleteDevices (Context context, List<DeviceId> deviceid, Options options) |
|
|
|
|
|
A valid list of DeviceIds must be provided. The list must contain at least one deviceid. Options argument is optional. If null, default execution options will be used. Options present will apply to all devices. |
|
|
An OperationStatus object will be returned. A successful call will result in all devices being deleted. |
|
|
See Table 8-1 . |
|
|
deleteDevicesBehind– A boolean flag to determine whether to delete the devices (if any) behind the specified IP device. If deleteDevicesBehind flag is set to “true”, all devices behind the specified device will be deleted. If deleteDevicesBehind flag is set to “false”, unregistered devices behind the specified device will be deleted. Registered devices will have their discovered DHCP data and provisioning group relationship delete leaving only their registered data. The default value is false. |
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
ProvServiceException – Missing required arguments or DeviceId is missing or specifies non-existent device. |
|
|
OperationStatus unregisterDevice(Context context, DeviceId deviceid, Options options) |
|
|
|
|
|
A valid DeviceId must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in device being unregistered. If the device is registered, transition the device to the unregistered state. If the device is unregistered, it will be deleted from the database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required arguments or DeviceId is missing or specifies non-existent device. |
|
|
OperationStatus unregisterDevices(Context context, DeviceId deviceid, Options options) |
|
|
|
|
|
A valid list of DeviceIds must be provided containing at least one device. Options argument is optional. If null, default execution options will be used. Options are applied to the transaction as a whole. |
|
|
A successful call will result in all specified device being unregistered. If a device is registered, transition the device to the unregistered state. If a device is unregistered, it will be deleted from the database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
ProvServiceException – Missing required arguments or DeviceId is missing or specifies non-existent device. |
|
|
LeaseResultsOperationStatus getDHCPLeaseInfo(Context context, IPAddress ipAddress, List<String> provGroups, Options options) |
|
|
Retrieves all known DHCP lease information about the specified IP Address. |
|
|
A valid device ID must be provided. IPAddress must be provided and can be either in IPv4 or IPv6 format. An optional list of provisioning groups to search. If null, DHCP servers in all provisioning groups are queried. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in DHCP both IPv4 and IPv6 lease query information returned. DHCP lease information will be retrieved from provisioning group DHCP server(s). If no DHCP server responds, an error condition is returned. If a DHCP server does respond, but there is no active lease, no lease information will be included in the result and there will be no error returned. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The IPAddress is missing or contains invalid data. This fault will also be raised if the DHCP server could not be contacted. |
|
|
OperationStatus regenConfigs(Context context, Search deviceSearch, Options options) |
|
|
Submit a request to the RDU's Configuration Regeneration Service to regenerate configurations for the set of devices that match the specified search criteria. |
|
|
A valid Search must be provided. Search.query and Search.maxResults are the only required fields. Options argument is optional. If null, default execution options will be used. |
|
|
This operation returns immediately. A success signifies that it has been queued by the RDU for processing. The returned OperationStatus will contain the batch id that can be used to monitor the status of the regeneration. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the devices. Concurrent Access – Duplicate requests of this operation will be not be allowed. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. |
|
|
OperationStatus rebootDevice(Context context, DeviceId deviceid, Options options) |
|
|
|
|
|
A valid DeviceId must be provided. Under Execution options, the activationMode must be AUTOMATIC. |
|
|
|
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required arguments or DeviceId is missing or specifies non-existent device. |
DeviceType Operations
|
|
OperationStatus addDeviceType (Context context, String deviceType, Options options) |
|
|
|
|
|
DeviceType argument must not be null. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in a new device type being added to Prime CP’ database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to add the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The device objects contains invalid or missing data. |
|
|
DeviceTypeOperationStatus getDeviceTypes(Context context, Options options) |
|
|
|
|
|
Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in all the device types being returned. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The device id contains invalid or missing data or uniqueness constraints were violated. |
|
|
OperationStatus deleteDeviceType(Context context, String deviceType, Options options) |
|
|
|
|
|
A valid DeviceType name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in the device type being deleted. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required DeviceType name or non-existent DeviceType. |
|
|
OperationStatus updateDeviceType(Context context, String deviceTypeName, Map<String, String> propertiesToUpdate, PropertiesToDelete propertiesToDelete, Options options) |
|
|
|
|
|
A valid DeviceType name must be provided. The properties to be updated or deleted must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in the device type being updated. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required DeviceType name or non-existent DeviceType. |
Generic Device Operation
|
|
OperationStatus deviceOperation(Context context, List<DeviceId> deviceIds, DeviceCommand command,Options options) |
|
|
A generic operation that sends an opaque command and parameters to all specified devices. |
|
|
A valid list of one or more DeviceIds must be provided. A valid DeviceCommand specifying the device specific operation must exist. The command and its arguments are opaque to the service. Example of operations includes generation device's configuration, resetting the device, and enabling SNMP v3 access to the device. Each DeviceCommand includes an optional set of parameters that are specific to the type of command being executed. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in a list of asynchronous batch status being returned. The asynchronous batch status can be used for further query in pollOperation. |
|
|
Only asynchronous mode is supported. See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to perform device operations. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
ProvServiceException – Missing required arguments or DeviceId is missing or specifies non-existent device. |
Class Of Service Operations
|
|
OperationStatus addClassOfService(Context context, ClassOfService cos, Options options) |
|
|
Submit a request for the addition of a new class of service. |
|
|
ClassOfService argument must not be null. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in a new COS being added to Prime CP’ database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to add the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The ClassOfService object contains invalid or missing required data. |
|
|
ClassOfServiceOperationStatus getClassOfService(Context context, String cosName, Options options) |
|
|
|
|
|
A valid COS name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
|
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. |
|
|
OperationStatus updateClassOfService(Context context, String cosName, ClassOfService cos, PropertiesToDelete propertiesToDelete, Options options) |
|
|
|
|
|
A valid COS name must be provided. A valid ClassOfService attribute must be provided. Any non-null value will be used to update that respective field. All the properties and their values are either added if the properties does not exist, or updated if the properties exist. In 5.0, renaming a COS will not be supported. PropertiesToDelete specifies those properties to be removed from the ClassOfService object. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in ClassOfService being updated. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object and its properties. Concurrent Access - There is no limitation on the number of concurrent access of this operation. However, if multiple calls to update the same object are made, the last update will win. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – A ClassOfService by the name passed does not exist or the ClassOfService contains invalid or missing data. |
|
|
OperationStatus deleteClassOfService(Context context, String cosName, Options options) |
|
|
|
|
|
A valid ClassOfService name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in the ClassOfService being deleted. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required ClassOfService name or non-existent ClassOfService. |
DHCP Criteria Operations
|
|
OperationStatus addDHCPCriteria(Context context, DHCPCriteria dhcpCriteria, Options options) |
|
|
|
|
|
DHCPCriteria argument must not be null. It must contain a valid name and at least one of the following: clientClass, includeSectionTags, and/or excludeSelectionTags. Properties are optional. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in a new DHCPCriteria being added to Prime CP’ database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to add the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The DHCPCriteria object contains invalid or missing required data. |
|
|
DHCPCriteriaOperationStatus getDHCPCriteria(Context context, String dhcpCriteriaName, Options options) |
|
|
|
|
|
A valid DHCPCriteria name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in DHCPCriteria data being returned. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The DHCPCriteria name is missing or invalid. |
|
|
OperationStatus updateDHCPCriteria(Context context, String dhcpCriteriaName, DHCPCriteria dhcpCriteria, PropertiesToDelete propertiesToDelete, Options options) |
|
|
Updates the properties of the specified DHCPCriteria object. |
|
|
A valid DHCPCriteria name must be provided. A valid DHCPCriteria must be provided. Any non-null value will be used to update that respective field. All property and their values found in Properties will be either added if the property does not exist or updated if it does exist. In 5.0, renaming a DHCPCriteria will not be supported. PropertiesToDelete specifies those properties to be removed from the DHCPCriteria object. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in DHCPCriteria being updated. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object and its properties. Concurrent Access - There is no limitation on the number of concurrent access of this operation. However, if multiple calls to update the same object are made, the last update will win. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – A DHCPCriteria by the name passed does not exist or the DHCPCriteria contains invalid data. |
|
|
OperationStatus deleteDHCPCriteria(Context context, String dhcpCriteriaName, Options options) |
|
|
|
|
|
A valid DHCPCriteria name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in the DHCPCriteria being deleted. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required DHCPCriteria name or non-existent DHCPCriteria. |
File Operations
|
|
OperationStatus addFile(Context context, File file, Options options) |
|
|
|
|
|
File argument must not be null. It must contain a valid filename, filetype. Properties are optional. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in a new File being added to Prime Cable Provisioning database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to add the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The File object contains invalid or missing required data. |
|
|
FileOperationStatus getFile(Context context, String fileName, boolean retrieveFileData, PropertyFilter propertyFilter, Options options) |
|
|
|
|
|
A valid filename name must be provided. PropertyFilter is optional. If null, only the file’s properties will be returned and not the data. If a PropertyFilter is provided with the property fileData, all the properties including data will be returned through MTOM. Also, if retrieveFileData is set to true, all properties including the data will be returned. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in specified File properties or data being returned. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The file name is missing or invalid or the file does not exist. |
|
|
OperationStatus updateFile(Context context, String fileName, File file, PropertiesToDelete propertiesToDelete, Options options) |
|
|
Updates the properties or data of the specified File object. |
|
|
A valid file name must be provided. A valid File must be provided. Any non-null value will be used to update that respective field. All property and their values found in Properties will be either added if the property does not exist or updated if it does exist. In 5.0, renaming a file is not supported. PropertiesToDelete specifies those properties to be removed from the File object. Options argument is optional. If null, default execution options will be used. |
|
|
|
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object and its properties. Concurrent Access - There is no limitation on the number of concurrent access of this operation. However, if multiple calls to update the same object are made, the last update will win. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. |
|
|
OperationStatus deleteFile(Context context, String fileName, Options options) |
|
|
|
|
|
A valid File name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
|
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required File name or non-existent File. |
Group Operations
|
|
OperationStatus addGroup(Context context, Group group, Options options) |
|
|
|
|
|
Group argument must not be null. It must contain a valid name and group type. Properties are optional. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in a new Group being added to Prime Cable Provisioning database. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to add the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The Group object contains invalid or missing required data. |
|
|
GroupOperationStatus getGroup(Context context, String groupName, Options options) |
|
|
|
|
|
A valid Group name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
|
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to read the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The Group name is missing or invalid, or Group does not exist. |
|
|
OperationStatus updateGroup(Context context, String groupName, Group group, PropertiesToDelete propertiesToDelete, Options options) |
|
|
|
|
|
A valid Group name must be provided. A valid Group must be provided. Any non-null value will be used to update that respective field. All property and their values found in Properties will be either added if the property does not exist or updated if it does exist. PropertiesToDelete specifies those properties to be removed from the Group object. Options argument is optional. If null, default execution options will be used. |
|
|
|
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to update the object and its properties. Concurrent Access - There is no limitation on the number of concurrent access of this operation. However, if multiple calls to update the same object are made, the last update will win. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – The group name passed, doesn’t exist. |
|
|
OperationStatus deleteGroup(Context context, String groupName, Options options) |
|
|
|
|
|
A valid Group name must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in the Group being deleted. Any member object will be automatically unassigned. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges to delete the object. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
AccessDeniedException – User does not have proper privileges or credentials are wrong. ProvServiceException – Missing required Group name or non-existent Group. |
pollOperation Status
|
|
OperationStatus pollOperationStatus(Context context, String txId, Options options) |
|
|
Queries for the status of RDU asynchronous requests specified by the transaction ID. |
|
|
A non-null txId must be provided. Options argument is optional. If null, default execution options will be used. |
|
|
A successful call will result in the OperationStatus of the request being return. For non-reliable asynchronous RDU requests that had completed, a request not found will be returned. The support is also available for the following API requests where the OperationStatus is returned: |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
ProvServiceException – Missing required data such as request id. |
Search Operation
|
|
SearchResult search(Context context, Search search, Options options) |
|
|
This is a generic operation. Retrieves devices or classes of service or files or DHCP Criterion or groups based on the search criterion defined in search object. |
|
|
A valid Search must be provided. Search.query is the only required field. Options argument is optional, if null, default execution options will be used. |
|
|
A successful call will result in devices or classes of service or files or DHCP Criterion or groups objects being returned. In 5.0, for device search based on owner id, Class of Service search and DHCP Criterion search, RDU doesn’t support paging while retrieving the matching results from the database. Hence for these types of search operations, all matching objects will be retrieved at one shot. |
|
|
See Table 8-1 . |
|
|
|
|
|
Authorization – Can only be called by authenticated users with valid context and proper privileges. Concurrent Access - There is no limitation on the number of concurrent access of this operation. |
|
|
ProvServiceException – The Search object contains invalid or missing data. |
PWS Use Cases
The Prime Cable Provisioning Web Services (PWS) is a SOAP based service. The PWS Web Service Description Language (WSDL) describes the operations, messages, and data types used when interacting with the service. The PWS uses the document/literal wrapped style to encode SOAP message exchanges. With this approach the request and response messages are completely defined in W3C XML Schema. In addition, the request message takes the name of the operation while the response message takes the name of the operation with Response appended. The name prefixing can vary based on the SOAP framework being used. The following WSDL operation fragment illustrates the SOAP framework used for PWS:
The payload of the request message is described in the getDevice XML schema definition.
The getDevice request takes a required context, a required device ID, an optional property filter, and/or an optional options element.
The payload of the response message is described in the DeviceOperationStatus XML Schema definition.
The DeviceOperationStatus can return a device that matches the device ID provided in the request message. If no device is found, fault is returned.
This section illustrates some of the common device related operations and SOAP request/response messages that may be contained in them. For conciseness, only the request and response messages are depicted.
Note PWS can communicate only with PCP 5.0 RDU version or above. It is not compatible with RDUs of earlier releases of Prime Cable Provisioning.
This section includes the following use cases:
- Registering a New Device
- Unregistering a Device
- Getting DHCP Lease Information of a Device
- Updating Device Details
- Searching a Device
- Deleting a Device
- Multiple Devices Operations in a Single Request
- Reboot of Device or Devices
Registering a New Device
For a device to be operational in the home network and to get required access, a subscriber must connect the device to the network and register it. The device could be of type DOCSISModem, PacketCableMTA, CableHomeWanMan, CableHomeWanData, Set Top Box (STB), or computer.
Use this workflow to register a device and to bring the device online with the appropriate level of service.
Step 1 Create a connection with the respective RDU by sending a create session SOAP request. The session SOAP request must contain user and RDU details as shown below:
Step 2 Create class of service required for registering the device using a SOAP request. The supported device types are DOCSISModem, Set Top Box (STB), PacketCableMTA, computer, CableHomeWanMan, and CableHomeWanData.
Step 3 Create DHCP criteria required for registering the device using SOAP request.
Step 4 Add group using SOAP request.
Step 5 Use the device ID such as MAC address or DUID or FQDN and the device type for adding a new device to the SOAP request. You can assign a group to the new device.
The add device SOAP request also passes the subscriber's information, Class of Service, DHCP Criteria, Hostname and domain to Prime Cable Provisioning, which then registers the subscriber's device such as modem and computer.
Step 6 Provision the device by connecting it to the network. Prime Cable Provisioning provides the device its registered service level.
The device is now a provisioned device with access to the appropriate level of service.
Step 7 Close the open sessions.
Note Idle sessions are automatically closed after 15 minutes.
Unregistering a Device
A device can be unregistered from Prime Cable Provisioning using the unregister SOAP request. This deletes the records from the Prime Cable Provisioning and subscriber gets the appropriate service level.
Unregistering a device removes the device details from Prime Cable Provisioning and gets the unprovisioned level of service.
Use this workflow to unregister a device and to bring the device online with the appropriate level of service.
Step 1 Create a connection with the respective RDU by sending a create session SOAP request. The session SOAP request must contain user and RDU details as shown below.
Step 2 Use the device ID such as MAC address or DUID for unregistering a device. Unregister the device using the following SOAP request.
The device is now a unregistered and unprovisioned device with access to the appropriate level of service.
Step 3 Close the open sessions.
Note Idle sessions are automatically closed after 15 minutes.
Getting DHCP Lease Information of a Device
A registered or unregistered device is assigned an IP address when it is provisioned. This IP address is used for collecting lease information such as, network register server state, and list of provisioning group in this lease.
Lists the details of the lease information from the Prime Cable Provisioning for the provisioned devices.
Use this workflow to collect the lease information of a device.
Step 1 Use an existing session or create a connection with the respective RDU by sending a create session SOAP request. The session SOAP request must contain user and RDU details as shown below.
Step 2 Use the IP address along with its provisioning group name or just the IP address of the provisioned devices in the SOAP request.
Step 3 Close the open sessions.
Note Idle sessions are automatically closed after 15 minutes.
Updating Device Details
You can update the device’s class of service, DHCP criteria, assign or unassign a group, and change or add properties. You can update any or all of this information as part of single updateDevice operation.
Embedded devices are not supported in Prime Cable Provisioning. The following workflow updates a single device. Before updating the device a new class of service and new dhcp criteria are added.
Prime Cable Provisioning regenerates the configuration file after updating the device with the required changes. The device then gets re-provisioned with updated level of service.
Use this workflow to update a device’s details and provision it with the updated level of service.
Step 1 Create a connection with the respective RDU by sending a session SOAP request. The session SOAP request must contain user and RDU details as shown below.
Step 2 Add a new class of service for the device using the following SOAP request:
Step 3 Add a new DHCP criteria for the device using the following SOAP request:
Step 4 If you want to assign a group that is not yet created, create it using the following SOAP request.
Step 5 Use the device ID such as MAC address or DUID or FQDN and the device type to update the device details. You can update the subscriber’s details as well as assign or unassign the device to a group by using the following SOAP request.
The device gets a regenerated configuration and is provisioned with updated service level.
Step 6 Close the open sessions.
Note Idle sessions are automatically closed after 15 minutes.
Searching a Device
The subscriber has devices such as DOCSIS, MTA, DPoE and computer in Prime Cable Provisioning. These devices can be searched from the Prime Cable Provisioning and get the results as a list in SOAP response.
Searches device(s) from Prime Cable Provisioning based on specific search criteria.
Use this workflow to search a device and get the list that is generated based on the search criteria.
Step 1 Create a connection with the respective RDU by sending a session SOAP request. The session SOAP request must contain user and RDU details as shown below.
Step 2 Use the query to create a search criteria.
Note For the first query, the start element must not be included.
For all the supported search requests Search.query and Search.maxResults elements are required. Search.start is used to support paging across large search results. The first search operation must not include Search.start element. Its absence indicates that a new search is being initiated. A response to a search operation contains a SearchResult. SearchResult contains a next element which itself is a Search object. The entire content of the next element (query, start, size) should be used to page to the next batch of search results. The value of the start element is used by RDU’s internal paging mechanism. Hence, from second request onwards, Search.start is required to page over the results. At the end of the search process, an empty SearchResult where SearchResult.size equals zero will be returned.
Step 3 Ensure that the response contains the next query request.
Step 4 Use the next element contents for the next search query criteria.
Step 5 Repeat step 4 and step 5 till you receive the search response size as zero.
All the devices are available based on the search request.
Step 6 Close the open sessions.
Note Idle sessions are automatically closed after 15 minutes.
Note You can also run search query based on different object types such as, device, Class of Service, DHCP Criteria, file and group. A sample search query pattern with these object types is shown below:
Supported Query Elements
The supported search elements in Prime Cable Provisioning 6.0 are:
Searching basic device details of a registered device with class of service as sample-gold-docsis :
Searching basic device details of a registered device with default CoS device type as DOCSISModem:
Searching basic device details of a registered device with default DHCP criteria device type as DOCSISModem:
Searching all the device details of a device with device ID type as macAddress :
Searching all the device details of a device with device type as DocsisModem:
Searching all the device details of a device with group name as testGroup :
Search the entire device by ownerId as testOwner:
Searching all class of service with device type as DOCSISModem:
Searching all files with file type as CABLELABS_CONFIGURATION_TEMPLATE :
Searching all files with a file name pattern:
Searching all groups with group type as system :
Searching all groups with a group name pattern:
Deleting a Device
The existing devices in Prime Cable Provisioning can be deleted using the delete SOAP request.
Deleting a device removes the device details from the Prime Cable Provisioning.
Use this workflow to delete a device.
Step 1 Create a connection with the respective RDU by sending a session SOAP request. The session SOAP request must contain user and RDU details as shown below.
Use the device ID such as MAC address or DUID to delete the device.
Step 2 Delete the device using the following SOAP request.
Step 3 Close the open sessions.
Note Idle sessions are automatically closed after 15 minutes.
The device record is deleted from Prime Cable Provisioning.
Multiple Devices Operations in a Single Request
Multiple devices in Prime Cable Provisioning can be added, retrieved, updated, or deleted using a single SOAP request.
Use this workflow to add, retreive, update, and delete multiple devices.
Step 1 Create a connection with the respective RDU by sending a session SOAP request. The session SOAP request must contain user and RDU details as shown below.
Step 2 Add five devices using a single SOAP request.
Step 3 Get five devices using a single SOAP request
Step 4 Update two devices using a single SOAP request.
Step 5 Get updated five devices details using a single SOAP request.
Step 6 Get five devices details with lease query information using a single SOAP request.
Step 7 Delete five devices in a single SOAP request.
Step 8 Close the open session.
Note Idle sessions are automatically closed after 15 minutes.
Reboot of Device or Devices
The devices in Prime Cable Provisioning can be rebooted using the reboot SOAP request.
Use this workflow to reboot a device or multiple devices.
Step 1 Create a connection with the respective RDU by sending a session SOAP request. The session SOAP request must contain user and RDU details as shown below.
Use the device ID such as MAC address or DUID to reboot the device.
Step 2 Reboot the device using the following SOAP request.
The device record is initiated for reboot operation in Prime Cable Provisioning.
Step 3 Use the transaction ID (txId) to retrieve the operation status from the Prime Cable Provisioning.
Step 4 Close the open session.
Note Idle sessions are automatically closed after 15 minutes.
Feedback