Cisco Prime Cable Provisioning Integration Developers Guide, 6.0

Provisioning Operations
Provisioning API Use Cases
- How to Create an API Client
- Use Cases

Java API Client Use Cases

This chapter describes the most common Prime Cable Provisioning API use cases that are directly related to device provisioning and device management.

Many system configuration and management operations, such as managing Class of Service, DHCP Criteria, and licenses, are not addressed here because these operations do not require integration with BSS and OSS. You can use the Prime Cable Provisioning admin UI to perform most of these activities. For more information on Prime Cable Provisioning admin UI, see the Cisco Prime Cable Provisioning 6.0 User Guide.

For more details on related API calls and sample API client code segments explaining individual API calls and features, refer to these resources that are available in the Prime Cable Provisioning installation directory:

API Javadoc located at BAC_53_Linux/docs/BAC_Javadoc_API_Provisioning on a Linux machine.
Sample API client code, located at BPR_HOME/rdu/samples/provapi.

BPR_HOME is the home directory in which you install Prime Cable Provisioning. The default home directory is /opt/CSCObac.

This chapter lists various API constants and their functions. To execute any API, you must follow the steps described in the Getting Started with the Prime Cable Provisioning API chapter.

Provisioning Operations

This section describes the following provisioning operation use cases:

Note The classfiles referenced in these use cases; for example, the AddDeviceExample.java classfile that illustrates how you can add a device record to the RDU, are only samples that are bundled with the Prime Cable Provisioning software.

Adding a device record to the RDU— See Table 7-1 .
Modifying a device record in the RDU— See Table 7-2 .
Retrieving discovered device data from the RDU— See Table 7-3 .
Deleting device from the RDU— See Table 7-4 .
Retrieve Devices Matching Vendor Prefix— See Table 7-5 .

Table 7-1 Adding a Device Record to the RDU
Classfile	API
`AddDeviceExample.java`	IPDevice.add()
Adds a new device record to the RDU database. Uses the IPDevice.add() API and submits the batch synchronously with the NO_ACTIVATION flag. This operation causes the RDU to generate instructions for the device, which are then cached in the DPE. Figure 7-1 explains adding or modifying a device record in the RDU with Activation mode = No_ACTIVATION.

Figure 7-1 Change Device Class of Service (Activation mode= NO_ACTIVATION)

Table 7-2 Modifying a Device Record in the RDU
Classfile	API
`ModifyDeviceExample.java`	IPDevice.changeProperties()
Changes the properties of a device record stored in the RDU. Uses the IPDevice.changeProperties() API and submits the batch synchronously with the NO_ACTIVATION flag. This operation causes the RDU to generate instructions for the device, which are then cached in the DPE.

Table 7-3 Retrieving Discovered Device Data in the RDU
Classfile	API
`QueryDeviceExample.java`	IPDevice.getDetails()
Retrieves the discovered data of a device that is stored in the RDU. Uses the IPDevice.getDetails() API and submits the batches synchronously using the on-connect mode with the NO_ACTIVATION flag.

Table 7-4 Delete Device from the RDU
Classfile	API
`DeleteDeviceExample.java`	IPDevice.delete()
Deletes a device from the RDU. Uses the IPDevice.delete() API and submits the batch synchronously with the NO_ACTIVATION flag.

Table 7-5 Retrieve Devices Matching Vendor Prefix
Classfile	API
`RetriveDevicesMatchingVendorPrefix.java`	IPDevice.searchDevice()
Searches for devices that exist in the database. Uses the IPDevice.searchDevice() API to query a list of devices that exist in the database.

Provisioning API Use Cases

This section presents a series of the most common provisioning application programming interface (API) use cases. See the Cisco Prime Cable Provisioning 6.0 API Javadoc for more details and sample Java code segments explaining individual API calls and features.

These use cases are directly related to device provisioning, service provisioning, or both. Many administrative operations, such as managing Class of Service, DHCP Criteria, and licenses are not addressed here. We recommend that you go through the API javadoc for more details on the related API calls. You can also use the administrator user interface to perform most of these activities.

This section describes:

How to Create an API Client

Before going through the use cases, you must familiarize yourself with how to create an API client. Use the workflow described in this section to create the API client.

Step 1 Create a connection to the Provisioning API Command Engine (PACE).

// The PACE connection to use throughout the example. When

// executing multiple batches in a single process, it is advisable

// to use a single PACE connection that is retrieved at the start

// of the application. When done with the connection, YOU MUST

// explicitly close the connection with the releaseConnection()

// method call.

PACEConnection connection = null;

// Connect to the Regional Distribution Unit (RDU).

// The parameters defined at the beginning of this class are

// used here to establish the connection. Connections are

// maintained until releaseConnection() is called. If

// multiple calls to getInstance() are called with the same

// arguments, you must still call releaseConnection() on each

// connection you received.

// The call can fail for one of the following reasons:

// - The hostname / port is incorrect.

// - The authentication credentials are invalid.

// - The maximum number of allowed sessions for the user

// has already been reached.

// However, the number of session validation for an user can be

// avoided by using the following overloaded method :

// PACEConnectionFactory.getInstance(

// RDU host rduHost,

// RDU port rduPort,

// User name userName,

// Password password

// Is immediate authentication required authenticateImmediately

// create a session forcefully forceLogin

//)

try

{

connection = PACEConnectionFactory.getInstance(

// RDU host rduHost,

// RDU port rduPort,

// User name userName,

// Password password);

}

catch (PACEConnectionException e)

{

// Handle connection error:

System.out.println("Failed to establish a PACEConnection to [" +

userName + "@" + rduHost + ":" + rduPort + "]; " +

e.getMessage());

System.exit(1);

}

Step 2 Create a new instance of a batch.

// To perform any operations in the Provisioning API, you must

// first create a batch. As you add commands to the batch,

// nothing gets executed until you post the batch.

// Multiple batches can be started concurrently against a

// single connection to the RDU.

Batch myBatch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

Step 3 Register an API command with the batch. The example featured in this step uses the getDetails(...) call.

// Use the Provisioning API to get all of the information for

// the specified MAC address. Since methods aren't actually

// executed until the batch is posted, the results are not

// returned until after post() completes. The getCommandStatus()

// followed by getData() calls must be used to access the results

// once the batch is posted.

final DeviceID modemMACAddress = DeviceID.getInstance("1,6,00:11:22:33:44:55",

KeyType.MAC_ADDRESS);

List options = new ArrayList();

options.add(DeviceDetailsOption.INCLUDE_LEASE_INFO);

myBatch.getDetails(modemMACAddress, options);

Step 4 Post the batch to the Regional Distribution Unit (RDU) server.

// Executes the batch against the RDU. All of the

// methods are executed in the order entered.

BatchStatus bStatus = null;

try

{

// Post batch in synchronous fashion without a timeout. This method will block until

// results are returned. Other API calls are available to submit a batch with timeout // or in asynchronous (non-blocking) fashion.

bStatus = myBatch.post();

}

catch (ProvisioningException pe)

{

System.out.println("Failed to query for modem with MAC address [" +

modemMACAddress + "]; " + pe.getMessage());

System.exit(2);

}

Step 5 Check the status of the batch.

// Check if any errors occurred during the execution of the

// batch. Exceptions occur during post() for truly exceptional

// situations such as failure of connectivity to RDU.

// Batch errors occur for inconsistencies such as no lease

// information for a device requiring activation. Command

// errors occur when a particular method has problems, such as

// trying to add a device that already exists.

//check batchStatus and commandStatus

//for any error

CommandStatus commandStatus = null;

if (batchStatus.getCommandCount() > 0)

{

commandStatus = batchStatus.getCommandStatus(0);

}

if (batchStatus.isError()

|| commandStatus == null

|| commandStatus.isError())

{

System.out.println("Failed to query for modem with MAC address [" +

modemMACAddress + "]; " + bs.getStatusCode().toString() + ", "

+ bs.getErrorMessage());

for (int i = 0; i < bs.getCommandCount(); i++)

{

CommandStatus cs = bs.getCommandStatus(i);

System.out.println("Cmd " + i + ": status code "

+ cs.getStatusCode().toString() + ", " + cs.getErrorMessage());

}

If there is no error, the batch call returns a successful result.

// Successfully queried for device.

System.out.println("Queried for DOCSIS modem with MAC address ["+

modemMACAddress + "]");

// Display the results of the command (TreeMap is sorted). The

// data returned from the batch call is stored on a per-command

// basis. In this example, there is only one command, but if

// you had multiple commands all possibly returning results, you

// could access each result by the index of when it was added.

// The first method added is always index 0. From the status of

// each command, you can then access the accompanying data by

// using the getData() call. Since methods can return data of

// different types, you will have to cast the response to the

// type indicated in the Provisioning API documentation.

Map deviceData = (Map)bStatus.getCommandStatus(0).getData();

// Created a sorted map view

Map<String, Object> deviceDetails = new TreeMap(deviceData);

for(String key: deviceDetails.keySet())

{

System.out.println(" " + key + "=" + deviceDetails.get(key));

}

Step 6 Release the connection.

// Once the last batch has been executed, the connection can

// be closed to the RDU. It is important to explicitly

// close connections since it helps ensure clean shutdown of

// the Java virtual machine.

connection.releaseConnection();

Use Cases

This section includes these use cases:

Self-Provisioned Modem and Computer in Fixed Standard Mode

The subscriber has a computer installed in a single-dwelling unit and has purchased a DOCSIS cable modem. The computer has a web browser installed.

Desired Outcome

Use this workflow to bring a new unprovisioned DOCSIS cable modem and computer online with the appropriate level of service.

Step 1 The subscriber purchases and installs a DOCSIS cable modem at home and connects a computer to it.

Step 2 The subscriber powers on the modem and the computer, and Prime Cable Provisioning gives the modem restricted access. The computer and modem are assigned IP addresses from restricted access pools.

Step 3 The subscriber starts a web browser, and a spoofing DNS server points the browser to a service provider’s registration server (for example, an OSS user interface or a mediator).

Step 4 The subscriber uses the service provider’s user interface to complete the steps required for registration, including selecting Class of Service.

Step 5 The service provider's user interface passes the subscriber’s information, such as the selected Class of Service and computer IP address, to Prime Cable Provisioning, which then registers the subscriber’s modem and computer.

// First we query the computer's information to find the

// modem's MAC Address. We use the computer IP Address (the web browser

// received this when the subscriber opened the service provider’s

// web interface

PACEConnection connection = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "changeme");

// NO_ACTIVATION is the activation mode because this is a query.

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the device.

// NO_PUBLISHING is the publishing mode because we are not attempting

// to publish to external database.

Batch batch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// register getAllForIPAddress to the batch

batch.getAllForIPAddress("10.0.14.38");

BatchStatus batchStatus = null;

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

// Get the LeaseResults object after posting a batch.

CommandStatus commandStatus = batchStatus.getCommandStatus(0);

LeaseResults computerLease = (LeaseResults)commandStatus.getData();

// Derive the modem MAC address from computer's network

// information. The "1,6" is a standard prefix for an Ethernet

// device. The fully qualify MAC Address is required by PCP

StringBuffer modemMACAddress = new StringBuffer();

modemMACAddress.append("1,6,");

modemMACAddress.append(computerLease.getSingleLease().get("relay-agent-remote-id"));

// Create MacAddress object from the string

MACAddress modemMACAddressObject = new MACAddress(modemMACAddress.toString());

List<DeviceID> modemDeviceIDList = new ArrayList<DeviceID>();

modemDeviceIDList.add(modemMACAddressObject);

// Create a new batch to add modem device

batch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// Register add API to the batch

batch.add(DeviceType.DOCSIS, modemDeviceIDList,

null, null, "0123-45-6789", "silver", "provisioned-cm", null);

// post the batch to RDU server

// Derive computer MAC address from computer's network information.

String computerMACAddress =

(String)computerLease.getSingleLease().get(DeviceDetailsKeys.MAC_ADDRESS);

// Create a map for computer property.

Map<String, Object> properties = new HashMap<String, Object>();

properties.put(IPDeviceKeys.MUST_BE_BEHIND_DEVICE, modemMACAddress.toString());

List<DeviceID> compDeviceIDList = new ArrayList<DeviceID>();

MACAddress computerMACAddressObject = new MACAddress(computerMACAddress);

compDeviceIDList.add(computerMACAddressObject);

// Register add API to the batch

batch.add(DeviceType.COMPUTER, compDeviceIDList,

null, null, "0123-45-6789", null, "provisioned-cpe", properties);

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Step 6 The provisioning client calls performOperation(DeviceOperation deviceOperation, DeviceID deviceID, Map<String,Object> parameters to reboot the modem and gives the modem provisioned access.

// Reset the computer

// Create a new batch

batch = connection.newBatch(

// No reset

ActivationMode.AUTOMATIC,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION);

// Register performOperation command to the batch

batch.performOperation(DeviceOperation.RESET, modemMACAddressObject, null);

// Post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Step 7 The user interface prompts the subscriber to reboot the computer.

After rebooting, the computer receives a new IP address, and both cable modem and computer are now provisioned devices. The computer has access to the Internet through the service provider’s network.

Adding a New Computer in Fixed Standard Mode

A Multiple System Operator (MSO) lets a subscriber have two computers behind a cable modem. The subscriber has one computer already registered and then brings home a laptop from work and wants access. The subscriber installs a hub and connects the laptop to it.

Desired Outcome

Use this workflow to bring a new unprovisioned computer online with a previously provisioned cable modem so that the new computer has the appropriate level of service.

Step 1 The subscriber powers on the new computer and Prime Cable Provisioning gives it restricted access.

Step 2 The subscriber starts a web browser on the new computer and a spoofing DNS server points it to the service provider's registration server (for example, an OSS user interface or a mediator).

Step 3 The subscriber uses the service provider’s user interface to complete the steps required to add a new computer.

Step 4 The service provider’s user interface passes the subscriber’s information, such as the selected Class of Service and computer IP address, to Prime Cable Provisioning, which then registers the subscriber’s modem and computer.

// First we query the computer's information to find the

// modem's MAC Address. We use the computer IP address (the web browser

// received this when the subscriber opened the service provider’s

// web interface.

PACEConnection connection = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "changeme");

// NO_ACTIVATION is the activation mode because this is a query

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the device

// NO_PUBLISHING is the publishing mode because we are not attempting

// to publish to external database.

Batch batch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// register getAllForIPAddress to the batch

batch.getAllForIPAddress("10.0.14.39");

BatchStatus batchStatus = null;

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

// Get the LeaseResults object after posting a batch.

CommandStatus commandStatus = batchStatus.getCommandStatus(0);

LeaseResults computerLease = (LeaseResults)commandStatus.getData();

// derive the modem MAC address from computer's network

// information. The "1,6" is a standard prefix for an Ethernet

// device. The fully qualify MAC Address is required by PCP

StringBuffer modemMACAddress = new StringBuffer();

modemMACAddress.append("1,6,");

modemMACAddress.append(computerLease.getSingleLease().get("relay-agent-remote-id"));

// derive computer MAC address from computer's network information.

String computerMACAddress =

(String)computerLease.getSingleLease().get(DeviceDetailsKeys.MAC_ADDRESS);

//Create a map for computer property.

Map<String, Object> properties = new HashMap<String, Object>();

// setting IPDeviceKeys.MUST_BE_BEHIND_DEVICE on the computer ensures

// that when the computer boots, it will only receive its provisioned

// access when it is behind the given device. If it is not behind

// the given device, it will receive default access (unprovisioned)

// and hence fixed mode.

properties.put(IPDeviceKeys.MUST_BE_BEHIND_DEVICE, modemMACAddress);

// the IPDeviceKeys.MUST_BE_IN_PROV_GROUP ensures that the computer

// will receive its provisioned access only when it is brought up in

// the specified provisioning group. This prevents the computer

// (and/or) the modem from moving from one locality to another

// locality.

properties.put(IPDeviceKeys.MUST_BE_IN_PROV_GROUP, "bostonProvGroup");

List<DeviceID> compDeviceIDList = new ArrayList<DeviceID>();

MACAddress computerMACAddressObject = new MACAddress(computerMACAddress);

compDeviceIDList.add(computerMACAddressObject);

batch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// register add API to the batch

batch.add(

DeviceType.COMPUTER, // deviceType: Computer

compDeviceIDList, // compDeviceIDList: the list of DeviceIDs derived from // computerLease

null, // hostName: not used in this example

null, // domainName: not used in this example

"0123-45-6789", // ownerName

null, // class of service: get the default COS

"provisionedCPE", // dhpcCriteria: Network Registrar uses this to

// select a modem lease granting provisioned IP address properties // device properties

);

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Step 5 The user interface prompts the subscriber to reboot the new computer so that Prime Cable Provisioning can give the computer its registered service level.

The computer is now a provisioned device with access to the appropriate level of service.

Disabling a Subscriber

A service provider needs to disable a subscriber from accessing the Internet due to recurring nonpayment.

Desired Outcome

Use this workflow to disable an operational cable modem and computer, so that the devices temporarily restrict Internet access for the user. Additionally, this use case can redirect the user’s browser to a special page that could announce:

You haven’t paid your bill so your Internet access has been disabled.

Step 1 The service provider’s application uses a provisioning client program to request a list of all of the subscriber’s devices from Prime Cable Provisioning.

Step 2 The service provider’s application then uses a provisioning client to individually disable or restrict each of the subscriber’s devices.

PACEConnection conn = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "password1");

//get all for owner ID

Batch batch = conn.newBatch();

batch.getAllForOwnerID("0123-45-6789");

BatchStatus batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(Exception e)

{

e.printStackTrace();

}

CommandStatus commandStatus = batchStatus.getCommandStatus(0);

//batch success without error, retrieve the result

RecordSearchResults rcSearchResult = (RecordSearchResults)commandStatus.getData(); List<RecordData> resultList = rcSearchResult.getRecordData();

if (resultList != null)

{

// getting the data

for (int i=0; i<resultList.size(); i++)

{

RecordData rd = resultList.get(i);

Map<String, Object> detailMap = rd.getDetails();

//get the deviceType from the detail map

String deviceType =

(String)detailMap.get(DeviceDetailsKeys.DEVICE_TYPE);

Key primaryKey = rd.getPrimaryKey();

//only interest in DOCSIS

if (DeviceType.getDeviceType(deviceType)

.equals(DeviceType.DOCSIS))

{

//change COS

batch = conn.newBatch();

batch.changeClassOfService((DeviceID)primaryKey, "DisabledCOS");

//change DHCPCriteria

batch.changeDHCPCriteria((DeviceID)primaryKey, "DisabledDHCPCriteria");

batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(Exception e)

{

e.printStackTrace();

}

//disable computer

else if (DeviceType.getDeviceType(deviceType)

.equals(DeviceType.COMPUTER))

{

//change DHCPCriteria

batch = conn.newBatch();

batch.changeClassOfService((DeviceID)primaryKey,

"DisabledComputerCOS");

batch.changeDHCPCriteria((DeviceID)primaryKey,

"DisabledComputerDHCPCriteria");

batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(Exception e)

{

e.printStackTrace();

}

Note You may need to consider the impact on the CPE behind the modem when defining the characteristics of DisabledCOS and resetting the modem. This is especially important if you have voice endpoints behind the modem, because disrupting the cable modem might affect the telephone conversation in progress at that time.

The subscriber is now disabled.

Preprovisioning Modems/Self-Provisioned Computers

A new subscriber contacts the service provider and requests service. The subscriber has a computer installed in a single-dwelling unit. The service provider preprovisions all its cable modems in bulk.

Desired Outcome

Use this workflow to bring a preprovisioned cable modem, and an unprovisioned computer, online in the roaming standard mode. This must be done so that both devices have the appropriate level of service and are registered.

Step 1 The service provider chooses a subscriber username and password for the billing system.

Step 2 The service provider selects services that the subscriber can access.

Step 3 The service provider’s field technician installs the physical cable to the new subscriber's house and installs the preprovisioned device, connecting it to the subscriber’s computer.

Step 4 The technician turns on the modem and Prime Cable Provisioning gives it a provisioned IP address.

Step 5 The technician turns on the computer and Prime Cable Provisioning gives it a private IP address.

Step 6 The technician starts a browser application on the computer and points the browser to the service provider's user interface.

Step 7 The technician accesses the service provider's user interface to complete the steps required for registering the computer behind the provisioned cable modem.

// First we query the computer's information to find the

// modem's MAC Address. We use the computer IP address (the web browser

// received this when the subscriber opened the service provider’s

// web interface

PACEConnection connection = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "changeme");

// NO_ACTIVATION is the activation mode because this is a query

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the device

// NO_PUBLISHING is the publishing mode because we are not attempting

// to publish to external database.

Batch batch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// register getAllForIPAddress to the batch

batch.getAllForIPAddress("10.0.14.38");

BatchStatus batchStatus = null;

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

// Get the LeaseResults object after posting a batch.

CommandStatus commandStatus = batchStatus.getCommandStatus(0);

LeaseResults computerLease = (LeaseResults)commandStatus.getData();

// derive computer MAC address from computer's network information.

String computerMACAddress =

(String)computerLease.getSingleLease().get(DeviceDetailsKeys.MAC_ADDRESS);

List<DeviceID> compDeviceIDList = new ArrayList<DeviceID>();

MACAddress computerMACAddressObject = new MACAddress(computerMACAddress);

compDeviceIDList.add(computerMACAddressObject);

// NO_ACTIVATION will generate new configuration for the computer,

// however it will not attempt to reset it.

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the computer because this cannot be done.

batch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// register add API to the batch

batch.add(

DeviceType.COMPUTER, // deviceType: Computer

compDeviceIDList, // compDeviceIDList: the list of DeviceIDs derived from // computerLease

null, // hostName: not used in this example

null, // domainName: not used in this example

"0123-45-6789", // ownerName

null, // class of service: get the default COS

"provisionedCPE", // dhpcCriteria: Network Registrar uses this to

// select a modem lease granting provisioned IP address

null // properties: not used

);

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Note The IPDeviceKeys.MUST_BE_BEHIND_DEVICE property is not set on the computer and this allows roaming from behind one cable modem to another.

Step 8 The technician restarts the computer and the computer receives a new provisioned IP address.

The cable modem and the computer are now both provisioned devices. The computer has access to the Internet through the service provider’s network.

Modifying an Existing Modem

A service provider’s subscriber currently has a level of service known as Silver and has decided to upgrade to Gold service. The subscriber has a computer installed at home.

Note The intent of this use case is to show how to modify a device. You can apply this example to devices provisioned in modes other than roaming standard.

Desired Outcome

Use this workflow to modify an existing modem’s Class of Service and pass that change of service to the service provider’s external systems.

Step 1 The subscriber phones the service provider and requests to have service upgraded. The service provider uses its user interface to change the Class of Service from Silver to Gold.

Step 2 The service provider’s application makes these API calls in Prime Cable Provisioning:

// NO_ACTIVATION is the activation mode because this is a query

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the device

// NO_PUBLISHING is the publishing mode because we are not attempting

// to publish to external database.

Batch batch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// replace changeClassOfService to this. Make sure the comment

// on top of this line is still there.

batch.changeClassOfService(new MACAddress("1,6,00:11:22:33:44:55")

// the MACAddress object

, "Gold");

// post the batch to the RDU

BatchStatus batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

The subscriber can now access the service provider’s network with the Gold service.

Unregistering and Deleting a Subscriber’s Devices

A service provider needs to delete a subscriber who has discontinued service.

Desired Outcome

Use this workflow to permanently remove all the subscriber’s devices from the service provider’s network.

Step 1 The service provider’s user interface discontinues service to the subscriber.

Step 2 This step describes how to unregister a subscriber’s device and delete a subscriber’s device. Deleting a device is optional because some service providers prefer to keep the cable modem in the database unless it is broken. Note however that if you unregister a device using Step 2-a, you cannot delete the device using Step 2-b.

a. To unregister a device, the service provider’s application uses a provisioning client program to request a list of all the subscriber’s devices from Prime Cable Provisioning, and unregisters and resets each device so that it is brought down to the default (unprovisioned) service level.

Note If the device specified as the parameter to the “unregister” API is already in unregistered state then the status code from the API call will be set to CommandStatusCodes.CMD_ERROR_DEVICE_UNRE- GISTER_UNREGISTERED_ERROR. This is normal/expected behavior.

// MSO admin UI calls the provisioning API to get a list of

// all the subscriber's devices.

// Create a new connection

PACEConnection conn = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "password1");

// NO_ACTIVATION is the activation mode because this is a query

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the device

// NO_PUBLISHING is the publishing mode because we are not attempting

// to publish to external database.

Batch batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

batch.getAllForOwnerID("0123-45-6789"

// query all the devices for this account number

);

BatchStatus batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(Exception e)

{

e.printStackTrace();

}

CommandStatus commandStatus = batchStatus.getCommandStatus(0);

//batch success without error, retrieve the result

RecordSearchResults rcSearchResult = (RecordSearchResults)commandStatus.getData();

List<RecordData> resultList = rcSearchResult.getRecordData();

// We need to unregister all the devices behind each modem(s) or else the

// unregister call for that modem will fail.

if (resultList != null)

{

//Unregister the COMPUTER

for (int i=0; i<resultList.size(); i++)

{

RecordData rd = resultList.get(i);

Map<String, Object> detailMap = rd.getDetails();

//get the deviceType from the detail map

String deviceType = (String)detailMap.get(DeviceDetailsKeys.DEVICE_TYPE);

//only interest in DOCSIS

if (DeviceType.getDeviceType(deviceType).equals(DeviceType.COMPUTER))

{

Key primaryKey = rd.getPrimaryKey();

batch = conn.newBatch();

batch.unregister((DeviceID)primaryKey);

batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

// for each modem in the retrieved list:

for (int i=0; i<resultList.size(); i++)

{

RecordData rd = resultList.get(i);

Map<String, Object> detailMap = rd.getDetails();

//get the deviceType from the detail map

String deviceType = (String)detailMap.get(DeviceDetailsKeys.DEVICE_TYPE);

//only interest in DOCSIS

if (DeviceType.getDeviceType(deviceType).equals(DeviceType.DOCSIS))

{

Key primaryKey = rd.getPrimaryKey();

batch = conn.newBatch();

batch.unregister((DeviceID)primaryKey);

batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

b. To delete a device, the service provider’s application uses a provisioning client program to delete each of the subscriber’s remaining devices individually from the database.

// Create a new connection

PACEConnection conn =

PACEConnectionFactory.getInstance("localhost", 49187, "admin", "password1");

// NO_ACTIVATION is the activation mode because this is a query

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the device

// NO_PUBLISHING is the publishing mode because we are not attempting

// to publish to external database.

Batch batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publisining to external database

PublishingMode.NO_PUBLISHING);

batch.getAllForOwnerID("0123-45-6789" // query all the devices for this account // number

);

BatchStatus batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(Exception e)

{

e.printStackTrace();

}

CommandStatus commandStatus = batchStatus.getCommandStatus(0);

//batch success without error, retrieve the result

RecordSearchResults rcSearchResult = (RecordSearchResults)commandStatus.getData();

List<RecordData> resultList = rcSearchResult.getRecordData();

if (resultList != null)

{

// for each modem in the retrieved list, delete it

for (int i=0; i<resultList.size(); i++)

{

RecordData rd = resultList.get(i);

Map<String, Object> detailMap = rd.getDetails();

//get the deviceType from the detail map

String deviceType = (String)detailMap.get(DeviceDetailsKeys.DEVICE_TYPE);

//only interest in DOCSIS

if (DeviceType.getDeviceType(deviceType).equals(DeviceType.DOCSIS))

{

Key primaryKey = rd.getPrimaryKey();

//change COS

batch = conn.newBatch();

batch.delete((DeviceID)primaryKey, true);

batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Self-Provisioning First-Time Activation in Promiscuous Mode

The subscriber has a computer (with a browser application) installed in a single-dwelling unit and has purchased a DOCSIS cable modem.

Desired Outcome

Use this workflow to bring a new unprovisioned DOCSIS cable modem and computer online with the appropriate level of service.

Step 1 The subscriber purchases a DOCSIS cable modem and installs it at home.

Step 2 The subscriber powers on the modem, and Prime Cable Provisioning gives it restricted access.

Step 3 The subscriber starts a browser application on the computer and a spoofing DNS server points the browser to the service provider’s registration server (for example, an OSS user interface or a mediator).

Step 4 The subscriber uses the service provider’s user interface to complete the steps required for registration, including selecting a Class of Service.

The service provider’s user interface passes the subscriber’s information to Prime Cable Provisioning, including the selected Class of Service and computer IP address. The subscriber’s cable modem and computer are then registered with Prime Cable Provisioning.

Step 5 The user interface prompts the subscriber to reboot the computer.

// Create a new connection

PACEConnection conn = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "password1");

Batch batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// NO_ACTIVATION is the activation mode because this is a

// query. NO_CONFIRMATION is the confirmation mode because

// we are not attempting to reset the device.

// First we query the computer's information to find the

// modem’s MAC address.

// We use the computer’s IP address (the web browser

// received this when the subscriber opened the service

// provider’s web interface).

// We also assume that "bostonProvGroup"

// is the provisioning group used in that locality.

List<String> provGroupList = new ArrayList<String>();

provGroupList.add("bostonProvGroup");

batch.getAllForIPAddress("10.0.14.38",

// ipAddress: restricted access computer lease

provGroupList

// provGroups: List containing provgroup

);

BatchStatus batchStatus = null;

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

// Get the LeaseResults object after posting a batch.

CommandStatus commandStatus = batchStatus.getCommandStatus(0);

LeaseResults computerLease = (LeaseResults)commandStatus.getData();

// Derive the modem MAC address from the computer's network

// information. The 1,6, is a standard prefix for an Ethernet

// device. The fully qualified MAC address is required by PCP

StringBuffer modemMACAddress = new StringBuffer();

modemMACAddress.append("1,6,");

modemMACAddress.append(computerLease.getSingleLease().get("relay-agent-remote-id"));

//create MacAddress object from the string

MACAddress modemMACAddressObject = new MACAddress(modemMACAddress.toString());

List<DeviceID> modemDeviceIDList = new ArrayList<DeviceID>();

modemDeviceIDList.add(modemMACAddressObject);

// NO_ACTIVATION is the activation mode because this is a query

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the device

// NO_PUBLISHING is the publishing mode because we are not attempting

// to publish to external database.

batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

Map<String, Object> properties = new HashMap<String, Object>();

// Set the property PolicyKeys.COMPUTER_PROMISCUOUS_MODE_ENABLED

// to enable promiscuous mode on modem

properties.put(PolicyKeys.COMPUTER_PROMISCUOUS_MODE_ENABLED, Boolean.TRUE);

properties.put(PolicyKeys.COMPUTER_DHCP_CRITERIA, "provisionedCPE");

// enable promiscuous mode by changing the technology default

batch.changeDefaults(DeviceType.DOCSIS,

properties, null);

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

batch.add(

DeviceType.DOCSIS, // deviceType: DOCSIS

modemDeviceIDList, // macAddress: derived from computer lease

null, // hostName: not used in this example

null, // domainName: not used in this example

"0123-45-6789", // ownerID: here, account number from billing system

"Silver", // ClassOfService

"provisionedCM", // DHCP Criteria: Network Registrar uses this to

// select a modem lease granting provisioned IP address

null // properties:

);

Step 6 The provisioning client calls performOperation(…) to reboot the modem and gives the modem provisioned access.

// Reset the computer

// create a new batch

batch = conn.newBatch(

// No reset

ActivationMode.AUTOMATIC,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION);

// register performOperation command to the batch

batch.performOperation(DeviceOperation.RESET,

modemMACAddressObject, null);

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Step 7 When the computer is rebooted, it receives a new IP address.

The cable modem is now a provisioned device. The computer is not registered with Prime Cable Provisioning, but it gains access to the Internet through the service provider’s network. Computers that are online behind promiscuous modems are still available using the provisioning API.

Bulk Provisioning 100 Modems in Promiscuous Mode

A service provider wants to preprovision 100 cable modems for distribution by a customer service representative at a service kiosk.

Desired Outcome

Use this workflow to distribute modem data for all modems to new subscribers. The customer service representative has a list of modems available for assignment.

Step 1 The cable modem’s MAC address data for new or recycled cable modems is collected into a list at the service provider’s loading dock.

Step 2 Modems that are assigned to a particular kiosk are bulk-loaded into Prime Cable Provisioning and are flagged with the identifier for that kiosk.

Step 3 When the modems are distributed to new subscribers at the kiosk, the customer service representative enters new service parameters, and changes the Owner ID field on the modem to reflect the new subscriber’s account number.

// Create a new connection

PACEConnection conn = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "password1");

Batch batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// The activation mode for this batch should be NO_ACTIVATION.

// NO_ACTIVATION should be used in this situation because no

// network information exists for the devices because they

// have not booted yet. A configuration can’t be generated if no

// network information is present. And because the devices

// have not booted, they are not online and therefore cannot

// be reset. NO_CONFIRMATION is the confirmation mode because

// we are not attempting to reset the devices.

// Create a Map for the properties of the modem

Map properties;

// Set the property PolicyKeys.COMPUTER_PROMISCUOUS_MODE_ENABLED to

// enable promiscuous mode on modem.

// This could be done at a system level if promiscuous mode

// is your default provisioning mode.

properties.put(PolicyKeys.COMPUTER_PROMISCUOUS_MODE_ENABLED, Boolean.TRUE);

// The PolicyKeys.CPE_DHCP_CRITERIA is used to specify the DHCP

// Criteria to be used while selecting IP address scopes for

// CPE behind this modem in the promiscuous mode.

properties.put(PolicyKeys.COMPUTER_DHCP_CRITERIA, "provisionedCPE");

// enable promiscuous mode by changing the technology default

batch.changeDefaults(DeviceType.DOCSIS,properties, null);

BatchStatus batchStatus = null;

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

// for each modem MAC-address in list:

ModemLoop:

{

batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

batch.add(

DeviceType.DOCSIS, // deviceType: DOCSIS

modemMACAddressList, // modemMACAddressList: the list of deviceID

null, // hostName: not used in this example

null, // domainName: not used in this example

"0123-45-6789", // ownerID: here, account number from billing system "Silver", // ClassOfService

"provisionedCM", // DHCP Criteria: Network Registrar uses this to

// select a modem lease granting provisioned IP address properties // properties:

);

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

// end ModemLoop.

}

Preprovisioning First-Time Activation in Promiscuous Mode

A new subscriber contacts the service provider and requests service. The subscriber has a computer installed in a single-dwelling unit.

Desired Outcome

Use this workflow to bring a new unprovisioned cable modem and computer online with the appropriate level of service.

Step 1 The service provider chooses a subscriber username and password for the billing system.

Step 2 The service provider selects the services that the subscriber can access.

Step 3 The service provider registers the device using its own user interface.

Step 4 The service provider's user interface passes information, such as the modem’s MAC address and the Class of Service, to Prime Cable Provisioning. Additionally, the modem gets a CPE DHCP Criteria setting that lets Network Registrar select a provisioned address for any computers to be connected behind the modem. The new modem is then registered with Prime Cable Provisioning.

Step 5 The service provider’s field technician installs the physical cable to the new subscriber’s house and installs the preprovisioned device, connecting it to the subscriber’s computer.

// MSO admin UI calls the provisioning API to pre-provision

// an HSD modem.

// Create a new connection

PACEConnection conn = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "password1");

Batch batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// The activation mode for this batch should be NO_ACTIVATION.

// NO_ACTIVATION should be used in this situation because no

// network information exists for the modem because it has not

// booted. A configuration cannot be generated if no network

// information is present. And because the modem has not booted,

// it is not online and therefore cannot be reset.

// NO_CONFIRMATION is the confirmation mode because we are not

// attempting to reset the modem.

// Create a map for the properties of the modem.

Map<String, Object> properties = new HashMap<String, Object>();

// Set the property PolicyKeys.COMPUTER_PROMISCUOUS_MODE_ENABLED

// to enable promiscuous mode on modem

properties.put(PolicyKeys.COMPUTER_PROMISCUOUS_MODE_ENABLED, Boolean.TRUE);

properties.put(PolicyKeys.COMPUTER_DHCP_CRITERIA, "provisionedCPE");

// enable promiscuous mode by changing the technology default

batch.changeDefaults(DeviceType.DOCSIS, properties, null);

BatchStatus batchStatus = null;

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

MACAddress macAddressObject = new MACAddress("1,6,00:11:22:33:44:55");

List<DeviceID> modemDeviceIDList = new ArrayList<DeviceID>();

modemDeviceIDList.add(macAddressObject);

batch.add(

DeviceType.DOCSIS, // deviceType: DOCSIS

modemDeviceIDList, // macAddress: derived from computer lease

null, // hostName: not used in this example

null, // domainName: not used in this example

"0123-45-6789", // ownerID: here, account number from billing system

"Silver", // ClassOfService

"provisionedCM", // DHCP Criteria: Network Registrar uses this to

// select a modem lease granting provisioned IP address

null // properties:

);

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Step 6 The technician powers on the cable modem and Prime Cable Provisioning gives it provisioned access.

Step 7 The technician powers on the computer and Prime Cable Provisioning gives it provisioned access.

The cable modem and the computer are now both provisioned devices. The computer has access to the Internet through the service provider’s network.

Replacing an Existing Modem

A service provider wants to replace a broken modem.

Note If the computer has the option to restrict roaming from one modem to another, and the modem is replaced, the computer’s MAC address for the modem must also be changed.

Desired Outcome

Use this workflow to physically replace an existing cable modem with a new modem without changing the level of service provided to the subscriber.

Step 1 The service provider changes the MAC address of the existing modem to that of the new modem.

// Create a new connection

PACEConnection conn = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "password1");

batch = conn.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

MACAddress macAddressObject = new MACAddress("1,6,00:11:22:33:44:55");

List<DeviceID> modemDeviceIDList = new ArrayList<DeviceID>();

modemDeviceIDList.add(macAddressObject);

// old macAddress: unique identifier for the old modem

MACAddress oldMacAddress = new MACAddress("1,6,00:11:22:33:44:55");

// new macAddress: unique identifier for the new modem

MACAddress newMacAddress = new MACAddress("1,6,00:11:22:33:44:66");

List<DeviceID> newDeviceIDs = new ArrayList<DeviceID>();

newDeviceIDs.add(newMacAddress);

batch.changeDeviceID(oldMacAddress, newDeviceIDs);

// post the batch to RDU server

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Step 2 The service provider replaces the cable modem and turns it on.

Step 3 The computer must also be turned on.

The cable modem is now a fully provisioned device with the appropriate level of service, as is the computer behind the cable modem.

Adding a Second Computer in Promiscuous Mode

A subscriber wants to connect a second computer behind an installed cable modem. This case does not require calls to the provisioning API.

Desired Outcome

Use this workflow to ensure that the subscriber’s selected service permits the connection of multiple sets of CPE, and that the subscriber has network access from both connected computers.

Step 1 The subscriber connects a second computer behind the cable modem.

Step 2 The subscriber turns on the computer.

If the subscriber’s selected service permits connecting multiple sets of CPE, Prime Cable Provisioning gives the second computer access to the Internet.

Self-Provisioning First-Time Activation with NAT

A university has purchased a DOCSIS cable modem with network address translation (NAT) and DHCP capability. The five occupants of the unit each have a computer installed with a browser application.

Desired Outcome

Use this workflow to bring a new unprovisioned cable modem (with NAT) and the computers behind it online with the appropriate level of service.

Step 1 The subscriber purchases a cable modem with NAT and DHCP capability and installs it in a multiple-dwelling unit.

Step 2 The subscriber turns on the modem and Prime Cable Provisioning gives it restricted access.

Step 3 The subscriber connects a laptop computer to the cable modem, and the DHCP server in the modem provides an IP address to the laptop.

Step 4 The subscriber starts a browser application on the computer and a spoofing DNS server points the browser to the service provider’s registration server (for example, an OSS user interface or a mediator).

Step 5 The subscriber uses the service provider’s user interface to complete the steps required for cable modem registration of the modem. The registration user interface detects that the modem is using NAT and registers the modem, making sure that the modem gets a Class of Service that is compatible with NAT. For details, see Self-Provisioned Modem and Computer in Fixed Standard Mode.

Note Certain cable modems with NAT may require you to reboot the computer to get the new Class of Service settings. If the cable modem and NAT device are separate devices, the NAT device must also be registered similarly to registering a computer.

Adding a New Computer Behind a Modem with NAT

The landlord of an apartment building has four tenants sharing a modem and accessing the service provider’s network. The landlord wants to provide Internet access to a new tenant, sharing the building’s modem. The modem has NAT and DHCP capability. The new tenant has a computer connected to the modem.

Note This case does not require calls to the provisioning API.

Desired Outcome

Use this workflow to bring a new unprovisioned computer online with a previously provisioned cable modem so that the new computer has the appropriate level of service.

Step 1 The subscriber turns on the computer.

Step 2 The computer is now a provisioned device with access to the appropriate level of service.

The provisioned NAT modem hides the computers behind it from the network.

Move Device to Another DHCP Scope

A service provider is renumbering its network causing a registered cable modem to require an IP address from a different Network Registrar scope.

Desired Outcome

A provisioning client changes the DHCP Criteria, and the cable modem receives an IP address from the corresponding DHCP scope.

Step 1 Change the DOCSIS modem’s DHCP Criteria to “newmodemCriteria”.

// Create a new connection

PACEConnection conn = PACEConnectionFactory.getInstance(

"localhost", 49187, "admin", "password1");

Batch batch = conn.newBatch(

// No reset

ActivationMode.AUTOMATIC,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// AUTOMATIC is the Activation mode because we are attempting

// to reset the modem so that a phone line is disabled

// NO_CONFIRMATION is the Confirmation mode because we don't

// want the batch to fail if we can't reset the modem.

// This use case assumes that the DOCSIS modem has been

// previously added to the database

batch.changeDHCPCriteria(

new MACAddress("1,6,ff:00:ee:11:dd:22"), // Modem's MAC address or FQDN

"newmodemCriteria"

);

// post the batch to RDU server

BatchStatus batchStatus = null;

try

{

batchStatus = batch.post();

}

catch(ProvisioningException e)

{

e.printStackTrace();

}

Step 2 The modem gets an IP address from the scope targeted by “newmodemCriteria.”

Log Device Deletions Using Events

A service provider has multiple provisioning clients and wants to log device deletions.

Desired Outcome

When any provisioning client deletes a device, the provisioning client logs an event in one place.

Step 1 Create a listener for the device deletion event. This class must extend the DeviceAdapter abstract class or, alternatively, implement the DeviceListener interface. This class must also override the deletedDevice(DeviceEvent ev) method in order to log the event.

public DeviceDeletionLogger

extends DeviceAdapter

//Extend the DeviceAdapter class.

{

public void deletedDevice(DeviceEvent ev)

//Override deletedDevice.

{

logDeviceDeletion(ev.getDeviceID());

//Log the deletion.

}

Step 2 Register the listener and the qualifier for the events using the PACEConnection interface.

DeviceDeletionLogger deviceDeletionLogger =

new DeviceDeletionLogger();

// Modem's MAC address or FQDN "newmodemCriteria"

DeviceEventQualifier qualifier = new DeviceEventQualifier();

// We are interested only in device deletion.

qualifier.setDeletedDevice ();

// Add device listener using PACEConnection

connection.addDeviceListener(deviceDeletionLogger, qualifier

);

Step 3 When a device is deleted from the system, the event is generated, and the listener is notified.

Monitoring an RDU Connection Using Events

A service provider is running a single provisioning client and wants notification if the connection between the provisioning client and the RDU breaks.

Desired Outcome

Use this workflow to have the event interface notify the service provider if the connection breaks.

Step 1 Create a listener for the messaging event. This class must extend the MessagingAdapter abstract class or, alternatively, implement the MessagingListener interface. This class must override the connectionStopped(MessagingEvent ev) method.

// Extend the service provider’s Java program using the

// provisioning client to receive Messaging events.

public MessagingNotifier

extends MessagingAdapter

//Extend the MessagingAdapter class.

{

public void connectionStopped(MessagingEvent ev)

//Override connectionStopped.

{

doNotification(ev.getAddress(), ev.getPort());

//Do the notification.

}

Step 2 Register the listener and the qualifier for the events using the PACEConnection interface.

MessagingQualifier qualifier =new MessagingQualifier();

qualifier.setConnectionDown();

MessagingNotifier messagingNotifier = new MessagingNotifier();

connnection.addMessagingListener(messagingNotifier, qualifier

);

Step 3 If a connection breaks, the event is generated, and the listener is notified. Whenever connectivity is interrupted, the PACE Connection automatically reconnects to the RDU.

Logging Batch Completions Using Events

A service provider has multiple provisioning clients and wants to log batch completions.

Desired Outcome

When any provisioning client completes a batch, an event is logged in one place.

Step 1 Create a listener for the event. This class must extend the BatchAdapter abstract class or implement the BatchListener interface. This class must override the completion(BatchEvent ev) method in order to log the event.

public BatchCompletionLogger

extends BatchAdapter

//Extend the BatchAdapterclass.

{

public void completion(BatchEvent ev)

//Override completion.

{

logBatchCompletion(ev.BatchStatus().getBatchID());

//Log the completion.

}

Step 2 Register the listener and the qualifier for the events using the PACEConnection interface.

BatchCompletionLogger batchCompletionLogger = new BatchCompletionLogger();

BatchEventQualifier qualifier = new BatchEventQualifier();

connection.addBatchListener(batchCompletionLogger, qualifier

);

Step 3 When a batch completes, the event is generated, and the listener is notified.

Getting Detailed Device Information

A service provider wants to allow an administrator to view detailed information for a particular device.

Desired Outcome

The service provider’s administrative application displays all known details about a given device, including MAC address, lease information, provisioned status of the device, and the device type (if known).

Step 1 The administrator enters the MAC address for the device being queried into the service provider’s administrator user interface.

Step 2 Prime Cable Provisioning queries the embedded database for the device details.

// The host name or IP address of the RDU. It is

// recommended that you normally use a fully-qualified domain name

// since it lends itself to the greatest flexibility going forward.

// For example, you could change the host running RDU without

// having to reassign IPs. For that reason, having an alias for

// the machine is better than a specific name.

final String rduHost = "localhost";

// The port number of RDU on the server.

final int rduPort = 49187;

// The user name for connecting to RDU.

final String userName = "admin";

// The password to use with the username.

final String password = "changeme";

// --------------------------------------------------------------------

// DEVICE PARAMETERS, see IPDevice.getDetails()

// --------------------------------------------------------------------

// The MAC address of the modem to be queried. MAC addresses in BAC

// must follow the simple "1,6,XX:XX:XX:XX:XX:XX" format.

final DeviceID modemMACAddress = DeviceID.getInstance("1,6,00:11:22:33:44:55",

KeyType.MAC_ADDRESS);

// The PACE connection to use throughout the example. When

// executing multiple batches in a single process, it is advisable

// to use a single PACE connection that is retrieved at the start

// of the application. When done with the connection, YOU MUST

// explicitly close the connection with the releaseConnection()

// method call.

PACEConnection connection = null;

// 1) Connect to the Regional Distribution Unit (RDU).

// The parameters defined at the beginning of this class are

// used here to establish the connection. Connections are

// maintained until releaseConnection() is called. If

// multiple calls to getInstance() are called with the same

// arguments, you must still call releaseConnection() on each

// connection you received.

// The call can fail for one of the following reasons:

// - The hostname / port is incorrect.

// - The authentication credentials are invalid.

// - The maximum number of allowed sessions for the user

// has already been reached.

try

{

connection = PACEConnectionFactory.getInstance(

// RDU host rduHost,

// RDU port rduPort,

// User name userName,

// Password password

);

}

catch (PACEConnectionException e)

{

// failed to get a connection

System.out.println("Failed to establish a PACEConnection to [" +

userName + "@" + rduHost + ":" + rduPort + "]; " +

e.getMessage());

System.exit(1);

}

// 2) Create a new batch instance.

// To perform any operations in the Provisioning API, you must

// first start a batch. As you make commands against the batch,

// nothing will actually start until you post the batch.

// Multiple batches can be started concurrently against a

// single connection to the RDU.

Batch myBatch = connection.newBatch(

// No reset

ActivationMode.NO_ACTIVATION,

// No need to confirm activation

ConfirmationMode.NO_CONFIRMATION,

// No publishing to external database

PublishingMode.NO_PUBLISHING);

// 3) Register the getDetails(...) with the batch.

// Use the Provisioning API to get all of the information for

// the specified MAC address. Since methods aren't actually

// executed until the batch is posted, the results are not

// returned until after post() completes. The getCommandStatus()

// followed by getData() calls must be used to access the results

// once the batch is posted.

final DeviceID modemMACAddress = DeviceID.getInstance("1,6,00:11:22:33:44:55",

KeyType.MAC_ADDRESS);

List options = new ArrayList();

options.add(DeviceDetailsOption.INCLUDE_LEASE_INFO);

myBatch.getDetails(modemMACAddress, options);

// 4) Post the batch to the server.

// Executes the batch against the RDU. All of the

// methods are executed in the order entered and the data

// changes are applied against the embedded database in RDU.

BatchStatus bStatus = null;

try

{

bStatus = myBatch.post();

}

catch (ProvisioningException pe)

{

System.out.println("Failed to query for modem with MAC address [" +

modemMACAddress + "]; " + pe.getMessage());

System.exit(2);

}

// 5) Check to see if the batch was successfully posted.

// Verify if any errors occurred during the execution of the

// batch. Exceptions occur during post() for truly exception

// situations such as failure of connectivity to RDU.

// Batch errors occur for inconsistencies such as no lease

// information for a device requiring activation. Command

// errors occur when a particular method has problems, such as

// trying to add a device that already exists.

if (bStatus.isError())

{

// Batch error occurred.

System.out.println("Failed to query for modem with MAC address [" +

modemMACAddress + "]; " + bStatus.getErrorMessage());

System.exit(3);

}

Step 3 The service provider’s application presents a page of device data details, which can display everything that is known about the requested device. If the device was connected to the service provider’s network, this data includes lease information (for example, IP address and relay agent identifier). The data indicates whether the device was provisioned, and if it was, the data also includes the device type.