Managing Devices with BRM

About the Device Management Framework

The Device Management framework enables you to write applications to manage devices in BRM or to connect an existing device management system to BRM. The Device Management framework is used by BRM optional components such as SIM (Subscriber Identity Module) Manager and Number Manager to facilitate their device management features.

The Device Management framework is part of Inventory Manager, which is an optional, separately purchased feature.

In BRM, a device can be physical, such as a set-top box, or "virtual," such as a phone number. Both types of devices are represented in BRM as objects.

The Device Management framework provides a storable class, /device, which can be subclassed to accommodate specific device types. Each /device or its /device subclass represents an individual device.

Device management involves creating device objects, associating them with services and accounts, controlling their life cycles, and removing them when they are no longer needed. The framework provides storable classes, standard and policy opcodes, and utilities for these purposes.

Implementing Device Management

The Device Management framework includes opcodes and objects that are used to store and manage devices. It provides the following functionality:

Creating Devices

Each device that you track in BRM is represented by a /device object. The way these objects are created depends on your business. For example, if you supply the devices yourself, you might create /device objects in bulk with a custom-designed application. When a customer is assigned a device, you would use one of the already existing /device objects.

On the other hand, if your business works with devices such as SIM cards that customers supply themselves, you might use a custom graphic user interface (GUI) tool to create /device objects at the same time that you set up customer accounts.

While there are many scenarios for device creation, the actual process used is always the same: all device-creation applications call PCM_OP_DEVICE_CREATE. This opcode creates /device objects using the device type, initial state, and attributes specified in the input flist. See "Managing the Device Life Cycle" for more information about device states and "Managing Device Attributes" for more information about device attributes.

Because your business may need to manage several types of devices, the /device storable class can be subclassed to represent device types. Each device type is a group of devices that have similar characteristics. For example, the BRM Number Manager creates /device/num objects while the SIM Manager creates /device/sim objects.

You use Storable Class Editor, part of Developer Center, to create new subclasses. See "Creating Custom Fields and Storable Classes".

A policy opcode, PCM_OP_DEVICE_POL_CREATE, enables you to customize the device creation process. For example, you can customize the policy to ensure that all devices have unique numbers.

Managing the Device Life Cycle

Devices pass through various stages in their life cycle. For example, a set-top box moves from manufacturing to a service provider's inventory, where it might be pre-provisioned. From there it is assigned to a retailer or perhaps directly to a subscriber. After it reaches the end-user, it could be returned for repair, obsoleted, or stolen.

A device management system must keep track of these stages or device states. In BRM, the device state is represented by the PIN_FLD_DEVICE_STATE field in a /device object. The value of this field represents the current state of the device. The set of possible device states and state transitions defines the life cycle of a /device object.

Device life cycles are regulated by /config/device_state objects in the database. You define device states and state changes in a configuration file and load it into the database by using the load_pin_device_state utility. See "Defining the Device Life Cycle" for more information.

Device management applications call the PCM_OP_DEVICE_UPDATE opcode to change device states (or PCM_OP_DEVICE_SET_STATE for state changes only). The opcode validates the change specified in the opcode against the /config/device_state object for that device type.

There are two ways to add validation checks or other business logic to a device state change. One way is to modify the PCM_OP_DEVICE_POL_SET_STATE policy opcode. This opcode is called automatically by PCM_OP_DEVICE_SET_STATE before changing the device state. Another way is to add additional validation checks to the policy opcode of your choice or a custom policy opcode, and reference the opcode in the /config/device_state object. You do this by adding opcode numbers to the configuration file that you create for each device, and loading the data in the file into /config/device_state by using the load_pin_device_state utility. BRM invokes the opcodes specified for each device type. For more information, see "Customizing Device State Changes" and "load_pin_device_state".

Managing Device Attributes

Devices have attributes such as descriptions, serial numbers, and manufacturer names that a device management system needs to track the devices. These attributes can be used to identify devices in GUI device management applications.

Device attributes are stored in /device object fields. Attributes applicable to all devices (device ID, description, manufacturer, and model) appear in the base /device storable class. You can add fields to /device subclasses for attributes specific to particular device types. For example, /device/sim contains attributes specific to SIM cards.

Applications call PCM_OP_DEVICE_UPDATE (or PCM_OP_DEVICE_SET_ATTR individually) to set device attributes. This opcode can be used to change the common attributes mentioned above and the attributes introduced in subclasses. It cannot be used to change the device state or service association.

Use the PCM_OP_DEVICE_POL_SET_ATTR opcode to customize setting device attributes. See BRM Opcode Guide.

Associating Devices and Services

Devices are associated with services. For example, a set-top box requires movies or other content to be useful. The reverse is also true; a video-on-demand service requires a device to display it.

In BRM, these device-to-service associations are represented by the association of /device objects with /service objects. For example, when a CSR provisions an account with a service that requires a device, the POID of the /service object is added to the PIN_FLD_SERVICES array in the /device object. The /account object POID associated with the service is also added to the /device object.

These device-to-service associations can take place on a many-to-many basis. One device may require multiple services and one service may require multiple devices. For example, a SIM card can be provisioned with several different wireless services.

The /config/device_permit_map object determine which service types can be associated with which device types. You define the valid device-to-service mappings in a configuration file and load it into the /config/device_permit_map object by running the load_pin_device_permit_map utility. See "Defining Device-to-Service Associations".

Applications call PCM_OP_DEVICE_ASSOCIATE to associate and disassociate devices and services for a particular account or at the account level. A flag in the input flist determines whether the services and devices are associated or disassociated. This opcode validates the associations against the /config/device_permit_map object for the device type specified in the input flist. Invalid associations cause the opcode to fail.

Deleting Devices

Devices can be removed from service for a variety of reasons. They might be returned by the customer, lost, stolen, or become obsolete. You can call PCM_OP_DEVICE_DELETE to remove the device object from the database when it is no longer needed.

Before you delete a device object, you should disassociate services from the device. During device deletion, the PCM_OP_DEVICE_POL_DELETE opcode checks for services associated with the device. If associations are found, the opcode generates an error and cancels the transaction. If desired, you can modify the policy to prevent the association check or to automatically remove associations before the device object is deleted.

In some cases you may want to replace a device object while keeping service associations intact. In this case, disassociate the services from the old device object and reassociate them with the new device in the same transaction. After the services are reassociated, you can delete the original device object.

See "Associating Devices and Services" for more information about device-to-service associations.

Tracking Device History

All operations on a /device object, such as device creation, state transitions, and changes to attributes, are recorded in the database as events. Recording events allows you to track the history of a device.

You can turn off event recording and turn on auditing to maintain a device history without storing details. For information about choosing which events to record, see "Managing Database Usage" in BRM System Administrator's Guide. For an introduction to auditing and links to more detailed information, see "About Maintaining an Audit Trail of BRM Activity" in BRM Managing Customers.

Two BRM Reports enable you to monitor the status and device history of devices. See "About BRM Reports" in BRM Reports.

Device Management and Multischema Environments

The Device Management framework supports multischema environments, with some restrictions:

A /device object can be associated only with /account and /service objects located in the same database schema as the /device object.
/device objects are not available across schemas. Device management /config objects (/config/device_state and /config/device_permit_map) are available, however.
You cannot move /device objects from one schema to another. You can delete the objects and re-create them in another schema, but service and account associations are lost.
You can enforce device number uniqueness across schemas, but this requires the use of global search opcodes and may result in slow performance.

Configuring Event Notification for Device Management

When a device state changes, Device Management uses event notification to call opcodes that perform the appropriate follow-up operations.

Although any subclass of the /event storable class can be used to trigger event notification (see "About Notification Events"), Device Management generates /event/notification/device/state specifically to use for event notification.

Before you can use Device Management, you must configure the event notification feature as follows:

If your system has multiple configuration files for event notification, merge them. See "Merging Event Notification Lists".
Ensure that the merged file includes the following information from the BRM_home/sys/data/config/pin_notify file, where BRM_home is the directory in which the BRM server software is installed:
```
# Device Management Framework related event notification
2706    0    /event/notification/device/state
  
```
(Optional) If necessary to accommodate your business needs, add, modify, or delete entries in your final event notification list. See "Editing the Event Notification List".
(Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger. See "Triggering Custom Operations".
Load your final event notification list into the BRM database. See "Loading the Event Notification List".

For more information, see "Using Event Notification".

Defining the Device Life Cycle

You define the life cycle for device objects in BRM by editing or creating a configuration file and then loading the data into a /config/device_state object in the database.

Each /config/device_state object contains definitions of the possible device states and state changes for one device type. /config/device_state objects also contain information about which policy opcodes to call during state changes.

See "load_pin_device_state" for detailed information about the syntax of the configuration file and running the load utility. See "Customizing Device State Changes" for information about calling policy opcodes.

Note:

You must load the life cycle definitions into the database before using any device management features. Because device management configuration data is always customized, no default values are loaded during BRM installation.

While the life cycle for every /device object is unique, the general pattern for all /device objects is the same:

During device creation, a /device object moves from Raw state (state 0) to an initial state that is defined for that device type. /device objects cannot be saved in Raw state.
During the life of the /device object, it moves from state to state in ways that are defined in a /config/device_state object. For example, a device might be able to move from a Pre-provisioned state to an Assigned to Dealer state, but not directly from Assigned to Subscriber state. Each device type has its own /config/device_state object, so you can define different life cycles to meet your business needs.
At the end of the working life of the /device object, it moves into a final state such as Stolen or Obsolete. Depending on business needs, the object could then be deleted to save space.

There can be any number of device states, each of which is assigned a number in the device state configuration file. State 0 is reserved for Raw state, but other numbers can be freely assigned.

There are four state types that correspond to the stages in the general pattern described above. These state types are defined in the pin_device.h header file and cannot be changed.

When you define device states, they must be assigned to one of these types:

Raw: There can be only one device state of this type for each device type. /device objects are in raw state only during the creation process. They can never be saved in a raw state. Raw states can transition only to Init states.
Init: This state type is for states in which the object can first be saved to the database. There can be more than one initial state for a particular device type. For example, you might want the device to be initialized to one state when created by a batch device creation tool and to another state when created by a CSR using a GUI tool. Init states can transition to Init, Normal, or End states.
Normal: Normal device states are all those that occur between the object's initial state and its end state. You can think of these as the "working" states for the device. There can be any number of Normal device states. Normal states can transition to Init states, other Normal states, and End states.
End: Devices cannot transition from End states. Because there are many possible end-of-life scenarios, you can include any number of End states.

When you define a device life cycle, be sure to consider all the stages in the life cycle of the actual device and all the possible relationships between them. You should also consider the level of detail that is useful to track in your device management system.

Figure 25-1 shows a relatively simple device life cycle for wireless phone SIM cards. The life cycles for your devices may be more complex depending on the characteristics of the devices and your business needs.

Figure 25-1 Wireless Phone SIM Card Life Cycle

Description of "Figure 25-1 Wireless Phone SIM Card Life Cycle"

Localizing Device State Names

The names you use for device states can be localized for display in a GUI application. You must define the state names as text strings and load the definitions into the database. To localize the device state names, you edit a copy of the device_states.en_US sample file in the BRM_home/sys/msgs/devicestates directory and save the edited version with the correct locale file extension. You then use the load_localized_strings utility to load the contents of the file into the /strings objects.

When you run the load_localized_strings utility, use this command:

load_localized_strings device_states.locale

Note:

If you're loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names".

For information on loading the device_states.locale file, see "Loading Localized or Customized Strings". For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings".

Customizing Device State Changes

PCM_OP_DEVICE_UPDATE is used to change device states. It calls PCM_OP_DEVICE_SET_STATE to actually make the change. During the processing of PCM_OP_DEVICE_SET_STATE opcode, there are two opportunities to call policy opcodes:

The first policy call takes place during the state change itself, just before the transaction is committed to the database.
The second occurs just after the transaction that changes the device state.

You can use these two policy calls for different purposes. For example, you might want to customize the process for assigning a SIM card to a customer, which involves a state change. During the first policy call by PCM_OP_DEVICE_SET_STATE, the policy opcode could check the customer's handset to ensure compatibility with the SIM card. If the two devices are compatible, the state change takes place. In the second policy call, after the state change transaction is complete, the policy opcode could provision the SIM card by calling PCM_OP_DEVICE_ASSOCIATE.

PCM_OP_DEVICE_POL_SET_STATE is the default policy opcode for device state changes. You can create any number of custom policy opcodes to replace or supplement it. You can also specify additional policy opcodes to call for each state change in the device-specific configuration file that defines the device life cycle. For each state change, you can specify an opcode for one, both, or neither of the two potential policy calls.

For information on naming and setting up this configuration file, see load_pin_device_state. For information about the state change opcodes, see:

PCM_OP_DEVICE_UPDATE
PCM_OP_DEVICE_SET_STATE
PCM_OP_DEVICE_POL_SET_STATE

Defining Device-to-Service Associations

You define which device and service types can be associated by editing or creating a configuration file and then loading the data into a /config/device_permit_map object in the database.

See load_pin_device_permit_map for detailed information about running the load utility and about the syntax of the configuration file. See PCM_OP_DEVICE_ASSOCIATE and PCM_OP_DEVICE_POL_ASSOCIATE for more information about the device-to-service mapping opcodes.

Note:

You must load the mapping information into the database before using any device management features. Because device management configuration data is always customized, default values are not loaded during BRM installation.

Use the PCM_OP_DEVICE_POL_ASSOCIATE opcode to customize device association.

Device and service types can be associated in any combination. One device can have any number of associated services. Likewise, one service may require multiple devices.

Creating Custom Device Management Systems

You can create custom device management systems using the Device Management framework. A device management system could be a separate, stand-alone application that performs all necessary tasks, or it could be an enabling application that connects an existing device management system.

A device management application is no different from any other BRM application except that it makes use of the opcodes and storable classes provided by the framework.

"Adding New Client Applications" provides a general overview and information about writing applications in C. Other chapters provide information about additional programming languages.

You will need to complete some or all of the following tasks to implement a device management system:

Create a subclass of the /device storable class for every new device type. Each subclass should include fields for the unique attributes of the device type.

You use Storable Class Editor to create fields and storable classes. See "Creating Custom Fields and Storable Classes".
If necessary, write a new FM for any unique functionality required by your device management system.

See "Writing a Custom Facilities Module".
If necessary, modify the Device FM policy opcodes to customize the default device management functionality.

See "About System and Policy Opcodes" for general information and "Device FM Policy Opcodes" in BRM Opcode Guide for specific information about the Device policy opcodes.
Write a custom application that calls the Device standard and policy opcodes and any custom opcodes you have created.

See "Adding New Client Applications" for general information and information about writing applications in C.
Define the life cycles and device-to-service mappings for your devices.

See "Defining the Device Life Cycle" and "Defining Device-to-Service Associations".