21 Managing Devices with BRM

This chapter describes the Oracle Communications Billing and Revenue Management (BRM) Device Management framework and explains how to use its components to build custom device management systems.

Before you read this chapter, you should have a good understanding of BRM opcodes and storable classes. See "Understanding the PCM API and the PIN Library" and "Understanding Flists and Storable Classes".

If you plan to develop device management applications, you should also read "Adding New Client Applications" and the client applications chapter that covers the programming language you will use.

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 storable 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. See "Device Management Tasks" for details.

Device Management Tasks

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

• Creating Devices

• Managing the Device Life Cycle

• Changing Device Brands

• Managing Device Attributes

• Associating Devices and Services

• Deleting Devices

• Tracking Device History

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.

/device objects are brand aware. Their brand affiliation is determined by the brand affiliation of the login used to create them. See "Device Management and Brands" for more information.

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 and brand.

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 and brand. For more information, see "Customizing Device State Changes" and load_pin_device_state.

The device life cycle is unique for each device type in each brand. The same device type could have different life cycles in different brands. See "Device Management and Brands" for more information.

Changing Device Brands

In a branded environment, devices are only available to a single brand at a time. The /device objects are associated with the /account object of a brand when they are created. You can change this brand association later by calling PCM_OP_DEVICE_UPDATE (or PCM_OP_DEVICE_SET_BRAND individually). See "Device Management and Brands".

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 such as Customer Center.

Device attributes are stored in /device object fields. Attributes applicable to all devices (device ID, description, manufacturer, and model) appear in the base /device 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 brand association, device state, or service association.

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 determines 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 and brand 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 aborts 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, you should disassociate the services from the old device object and reassociate them with the new device in the same transaction. After the services have been 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 from a client application such as Customer Center or a custom device management system.

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 the BRM Reports Packages" in BRM Reports.

Device Management and Brands

The Device Management framework supports branding. For example, in Customer Center, a CSR can see and assign only devices in brands for which they have permissions. Similarly, devices can be associated only with services in the same brand.

Branding in the device management framework is implemented by associating brands with both /device objects and the /config objects used to configure them. Each /device or /config object includes a PIN_FLD_ACCOUNT_OBJ field, which in turn contains the POID of the /account object of the brand.

The brand affiliation of /device and /config objects is determined by the BRM login used to create them:

• For /device objects, this might be the login of a Customer Center user or the user of a bulk device creation tool.

• For /config objects (/config/device_state and /config/device_permit_map) the brand is determined by the login in the Infranet.properties file for the load utilities used to create the objects. See "Defining the Device Life Cycle" and "Defining Device-to-Service Associations" for more information about the load utilities.

Access permissions ensure that only logins associated with the correct brands can read, write, and create /device objects and their /config objects:

• /device objects have read permission set to Brand Lineage and write permission set to Ancestral Lineage. See "Branding Access Permissions".

• /config objects have read permissions set to Brand, write permissions set to Self, and create permissions set to Brand Owner. See "Branding Access Permissions".

You can set up device management features to work differently for devices in different brands. For example, you might define a different life cycle for a device type in Brand A than for the same device type in Brand B. See "Defining the Device Life Cycle" and "Defining Device-to-Service Associations".

You can change the brand affiliation of a /device object by using PCM_OP_DEVICE_UPDATE (or PCM_OP_DEVICE_SET_BRAND individually). The caller of the opcode must have access permissions that allow it to change objects in both the old and new brands. In some cases, this may require the use of a root login.

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

1. If your system has multiple configuration files for event notification, merge them. See "Merging Event Notification Lists".

2. 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 you installed BRM components:

   # Device Management Framework related event notification
   2706    0    /event/notification/device/state
     
   

3. (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".

4. (Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger. See "Using Event Notification to Trigger Custom Operations".

5. Load your final event notification list into the BRM database. See "Loading the Event Notification List".

For more information, see "Using Events to Trigger Operations".

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 and brand. /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 and brand. /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 and brand 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 and brand. /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 and brand. 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 21-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 21-1 Wireless Phone SIM Card Life Cycle

Description of ''Figure 21-1 Wireless Phone SIM Card Life Cycle''

Because /config/device_state objects are brand aware, you must load an object for each unique combination of device type and brand. For example, if you have two device types (A and B) that occur in two brands (1 and 2) and a third device type (C) that occurs only in Brand 1, you must load /config/device_state objects for these five combinations: A1, A2, B1, B2, and C1.

If the state changes for a device type are the same for all brands, you can create a single /config/device_state object for that device type by using the root login when you run load_pin_device_state. The device management opcodes automatically check the /config/device_state object associated with root if they can't find an object associated with a device's brand. See "Device Management and Brands" for more information.

To define the life cycle for a device type in a particular brand:

1. If necessary, edit the infranet.connection entry in the BRM_Home/apps/device_management/Infranet.properties file to use a login associated with the brand you are working on.

2. Enter device state change definitions in a new text file or edit BRM_Home/sys/data/config/pin_device_state.

   See load_pin_device_state for information about the syntax of the file.

   Caution:

   The load_pin_device_state utility overwrites existing device states for a device type and brand. If you are updating device states, you cannot load new device states only. You must load complete sets of device states for the device type and brand each time you run the load_pin_device_state utility.

3. Save the configuration file. For ease of maintenance, use a file name that reflects the device type and brand.

4. Use the following command to run the load_pin_device_state utility, where state_change_file represents the path and name of the configuration file you saved:

   load_pin_device_state state_change_file
     
   

5. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

To verify that the state change file was loaded, you can display the /config/device_state objects by using the Object Browser, or use the robj command with the testnap utility. (See "Reading an Object and Writing Its Contents to a File".)

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.

Each /config/device_permit_map object contains device-to-service mapping information for all the device types in one brand. However, you load the information separately for each device type in the brand.

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.

Important:

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.

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.

You must load device-to-service mapping information for each unique combination of device type and brand. For example, if the same device type exists in several different brands, you must load mapping information for that device type into the /config/device_permit_map object for each brand.

If the mapping definitions are the same for all brands or if you are not using branding, you can create a single /config/device_permit_map object by using the root login when you run load_pin_device_permit_map. The device management opcodes automatically check the /config/device_permit_map object associated with root if they can't find an object associated with a device's brand. See "Device Management and Brands" for more information.

The device-to-service mapping information that you define determines which associations are valid in a particular brand. If PCM_OP_DEVICE_ASSOCIATE attempts to associate a device to a service that is not defined in the /config/device_permit_map object, the association fails.

To map devices and services within a brand:

1. If necessary, edit the infranet.connection entry in the BRM_Home/apps/device_management/Infranet.properties file to use a login associated with the brand you are working on.

2. Enter device-to-service mapping definitions into a new text file or edit BRM_Home/sys/data/config/pin_device_permit_map.

   See load_pin_device_permit_map for information about the syntax of the file.

   Caution:

   The load_pin_device_permit_map utility overwrites existing mapping definitions for the device type in this brand. If you are updating mapping definitions, you cannot load only the new mappings. You must load complete sets each time you run the utility.

3. Save the configuration file. For ease of maintenance, use a file name that reflects the device type and brand.

4. Use the following command to run the load_pin_device_permit_map utility, where map_file represents the path and name of the configuration file you saved:

   load_pin_device_permit_map map_file
     
   

5. Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

6. To verify that the map file was loaded, display the /config/device_permit_map object by using the Object Browser, or use the robj command with the testnap utility. (See "Reading an Object and Writing Its Contents to a File".)

By default, when you associate a device with a service or disassociate a device from a service, BRM updates the status of the service and the associated supplementary features.

You can configure BRM to not update the status of a service when you associate a device with a service or disassociate a device from a service. For more information, see "Configuring Service Status Change for Device-to-Service Associations" in BRM Telco Integration.

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.

For information about creating BRM client applications, see the chapters in Creating custom client applications. "Adding New Client Applications" provides a general overview as well as 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:

1. 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 classes. See "Creating Custom Fields and Storable Classes".

2. If necessary, write a new FM for any unique functionality required by your device management system.

   See "Writing a Custom Facilities Module".

3. If necessary, modify the Device FM policy opcodes to customize the default device management functionality.

   See "Adding and Modifying Policy Facilities Modules" for general information and "Device FM Policy Opcodes" in BRM Developer's Reference for specific information about the Device policy opcodes.

4. Write a custom application that calls the Device standard and policy opcodes as well as any custom opcodes you have created.

   See "Adding New Client Applications" for general information as well as information about writing applications in C. See the other chapters in Creating custom client applications about writing applications in other languages.

5. Define the life cycles and device-to-service mappings for your devices.

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

About the Device Management Opcodes

You use the following opcodes to manage devices in BRM:

• To create devices, use PCM_OP_DEVICE_CREATE and PCM_OP_DEVICE_POL_CREATE. See "Creating /device Objects".

• To change any combination of device attributes, brands, and states, use PCM_OP_DEVICE_UPDATE. This wrapper opcode calls these opcodes to make the separate changes within a single transaction:

  • PCM_OP_DEVICE_SET_ATTR and PCM_OP_DEVICE_POL_SET_ATTR change existing device attribute values. See "Changing the Attributes of /device Objects".

  • PCM_OP_DEVICE_SET_BRAND and PCM_OP_DEVICE_POL_SET_BRAND associate devices with brands, or changes brand associations. See "Associating /devices and /brand Objects".

    PCM_OP_DEVICE_SET_STATE and PCM_OP_DEVICE_POL_SET_STATE change device states. See "UseElementId".

  You can also call these opcodes individually.

• To associate or disassociate services with devices, use PCM_OP_DEVICE_ASSOCIATE and PCM_OP_DEVICE_POL_ASSOCIATE. See "Associating /service and /device Objects".

• To delete devices, use PCM_OP_DEVICE_DELETE and PCM_OP_DEVICE_POL_DELETE. See "Deleting /device Objects".

Creating /device Objects

Use PCM_OP_DEVICE_CREATE to create /device objects in the BRM database.

This opcode calls the PCM_OP_DEVICE_POL_CREATE policy opcode before it creates any /device objects. By default, this policy opcode is an empty hook, but you can customize it to validate IDs, check that all mandatory attributes are specified, or perform other custom tasks.

For example, if devices of a particular type require a device ID with certain characteristics, you can validate the ID supplied by the input flist. Similarly, you can use the opcode to ensure that all mandatory attributes of a particular device type are included in the new object.

To create devices, your custom device-creation application must call PCM_OP_DEVICE_CREATE directly and pass in the following data:

• A type-only POID that specifies the device type

• The target database schema

• The name of the program calling the opcode

• The physical ID of the device

• The initial state to which the device should be set

  Note:

  Depending on the device type, additional inputs may be required for other device attributes.

PCM_OP_DEVICE_CREATE performs these tasks:

1. Calls PCM_OP_DEVICE_POL_CREATE to perform any custom validation.

2. Checks /config/device_permit_map to validate any device-to-service associations.

3. Sets the brand of the /device object.

4. Creates a /device object of the type specified in the input flist. This object includes all mandatory attributes for the device type.

5. Calls PCM_OP_DEVICE_SET_STATE to set the initial device state. See "UseElementId".

6. If events are being recorded, generates an /event/device/create object.

PCM_OP_DEVICE_CREATE stops processing under these circumstances:

• When the validation of the device-to-service association fails.

• When PCM_OP_DEVICE_POL_CREATE fails during the validation process.

• When PCM_OP_DEVICE_SET_STATE fails while setting the object's initial device state.

If PCM_OP_DEVICE_CREATE is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back and no /device object is created.

Changing Device Attributes, Brands, and States

Use PCM_OP_DEVICE_UPDATE to change any combination of device attribute values, brands, and states with a single call. This opcode calls PCM_OP_DEVICE_SET_ATTR, PCM_OP_DEVICE_SET_BRAND, and PCM_OP_DEVICE_SET_STATE individually to make the changes. These individual opcodes in turn, call their respective policy opcodes to perform any validation checks that you have added as explained in the following sections.

Changing the Attributes of /device Objects

Use PCM_OP_DEVICE_SET_ATTR to change device attribute values, such as the device manufacturer and model number.

Each type of device can have different attributes. For example, a /device/sim object has different attributes than a /device/num object. Attributes common to all devices, such as the text description stored in the PIN_FLD_DESCR field, are contained in the base /device object. Attributes specific to a particular type of device are stored in the /device subclass.

PCM_OP_DEVICE_SET_ATTR calls the PCM_OP_DEVICE_POL_SET_ATTR policy opcode before it sets attributes. By default, this policy opcode is an empty hook, but you can customize it to validate device IDs or perform other validation tasks.

To change device attributes, your custom device-creation application must call PCM_OP_DEVICE_SET_ATTR directly and pass in the following data:

• The POID of the /device object.

• The name of the program calling the opcode.

• The fields to change, along with their new values. If the opcode is changing the attributes of a /device subclass, it can include fields introduced in the subclass.

  Note:

  You can't use PCM_OP_DEVICE_SET_ATTR to change the brand association, device state, or service association. If the input flist includes these fields, they are ignored.

PCM_OP_DEVICE_SET_ATTR performs these operations:

1. Calls PCM_OP_DEVICE_POL_SET_ATTR to perform any custom validation.

2. Updates the /device object to include the new attribute values.

3. If events are being recorded, generates an /event/device/attribute object.

PCM_OP_DEVICE_SET_ATTR stops processing under these circumstances:

• When PCM_OP_DEVICE_POL_SET_ATTR fails.

• When an attribute to be changed doesn't exist in the /device object.

Associating /devices and /brand Objects

Use PCM_OP_DEVICE_SET_BRAND to change the brand associated with a device. For example, you use this opcode when a /device object was created in one brand, but you need to change the brand before assigning it to an account.

Important:

Devices and their associated services and accounts must all have the same brand.

The brand associated with the BRM login that calls this opcode determines which brand changes are possible. /device objects have ancestral lineage write permissions, so the caller of this opcode must be in the ancestral lineage of both the old and new brands. If the old and new brands are too distantly related for this to be possible, the opcode caller must have root permissions.

This opcode calls the PCM_OP_DEVICE_POL_SET_BRAND policy opcode before in changes any brand associations. By default, this policy opcode is an empty hook, but you can customize it to check brand types or perform other validations. For example, you could limit brand changes to certain device types or situations.

To associate devices with brands, your custom device-creation application must call PCM_OP_DEVICE_SET_BRAND directly and pass in the following data:

• The POID of the /device object.

• The name of the program calling the opcode.

• The /account object POID of the new brand.

PCM_OP_DEVICE_SET_BRAND performs these operations:

1. Calls PCM_OP_DEVICE_POL_SET_BRAND to perform any custom validation.

2. Validates permissions to ensure that the caller has permissions for both the new and old brands.

3. Replaces the old brand account value with the new one.

4. If events are being recorded, generates an /event/device/brand object.

The value of the PIN_FLD_FLAGS field in the PCM_OP_DEVICE_SET_BRAND input flist determines whether the opcode associates or disassociates objects. When the last bit is 1, the opcode associates. When the last bit is 0, the opcode disassociates.

PCM_OP_DEVICE_SET_BRAND stops processing under these circumstances:

• When the caller does not have permissions for both the new and old brands.

• When PCM_OP_DEVICE_POL_SET_STATE fails.

If the opcode is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back and no brand change takes place.

Changing the State of a /device Object

Use PCM_OP_DEVICE_SET_STATE to change the state of a /device object.

This opcode checks the validity of each state change by using the /config/device_state object for this device type and brand. The /config/device_state object includes an array that lists valid transitions from each device state. You create these rules in a configuration file and load them into /config/device_state objects by running the load_pin_device_state utility. See "Defining the Device Life Cycle".

The opcode calls policy opcodes at two points. The first takes place during the state change itself and the other just after it. You specify which policy opcodes to call by using the pin_device_state file. By default, it calls the PCM_OP_DEVICE_POL_SET_STATE policy opcode.

Note:

PCM_OP_DEVICE_SET_STATE uses the event notification feature. Before using this opcode, you must configure event notification for device management. See "Configuring Event Notification for Device Management".

To set device states, your custom device-creation application must call PCM_OP_DEVICE_SET_STATE directly and pass in the following data:

• The POID of the /device object.

• The name of the program calling the opcode.

• The old state ID.

• The new state ID.

PCM_OP_DEVICE_SET_STATE performs these operations:

1. Determines whether the state change is valid by checking the config/device_state object for this device type and brand.

2. Calls the opcode specified in /config/device_state for the in-transition event.

3. Changes the /device object's PIN_FLD_DEV_STATE_ID field to the new state.

4. If events are being recorded, generates an /event/device/state object.

5. Calls the opcode specified in /config/device_state for the post-transition event.

PCM_OP_DEVICE_SET_STATE stops processing under these circumstances:

• When the device state change is invalid based on the /config/device_state object for this device type.

• When a /config/device_state object cannot be found for this device type.

• When the input flist attempts to change the device state from RAW to any type other than INIT, or attempts to change the device state from END to any other state.

• When an error occurs during the event notification process or when a policy opcode is called.

  Note:

  The second policy call occurs after the state change has been recorded. If this policy fails, the state change is not rolled back.

PCM_OP_DEVICE_POL_SET_STATE allows customization during device state changes. For example, you might want to customize the process for assigning a SIM card to a customer. During this process, the state is changed from Inventory to Assigned. 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.

By default, PCM_OP_DEVICE_POL_SET_STATE is an empty hook provided to facilitate customization.

Associating /service and /device Objects

Use PCM_OP_DEVICE_ASSOCIATE to associate or disassociate services with devices.

When an account is provisioned with a device through Customer Center or some other application, this opcode associates the /device object with one or more /service objects. (One device can support multiple services. Conversely, one service may require multiple devices.) To facilitate searching, the account associated with the services is also associated with the device.

Note:

The services that can be associated with a particular device type and brand are determined by the /config/device_permit_map object. You enter the device-to-service mapping information in a device-specific configuration file and load it into the database by running the load_pin_device_permit_map utility. For the configuration file syntax, see "load_pin_device_permit_map".

PCM_OP_DEVICE_ASSOCIATE calls the PCM_OP_DEVICE_POL_ASSOCIATE policy opcode before it associates any objects. By default, this policy opcode does nothing, but you can customize it to limit the number of device associations or perform other validation tasks.

To associate services with devices, your custom device-creation application must call PCM_OP_DEVICE_ASSOCIATE directly and pass in the following data:

• The POID of the /device object.

• The name of the program calling the opcode.

• A flag to indicate association or disassociation.

• An array that includes the POIDs of the services and the account to be associated or disassociated.

PCM_OP_DEVICE_ASSOCIATE performs these operations:

1. Determines whether to associate or disassociate the objects by checking the PIN_FLD_FLAGS field.

   • When the last bit is 1, the opcode associates.

   • When the last bit is 0, the opcode disassociates.

2. Determines whether the device is already associated with the specified service by checking the /device object.

3. When associating objects, validates the device-to-service association by checking the /config/device_permit_map object. This validation includes ensuring that the brand of the device and service are the same.

4. Calls PCM_OP_DEVICE_POL_ASSOCIATE to perform any custom validation.

5. When associating objects, writes new fields for the services and account into the /device object's PIN_FLD_SERVICES array.

6. When disassociating objects, deletes the appropriate service and account fields from the /device object.

7. If events are being recorded, generates an /event/device/associate object.

PCM_OP_DEVICE_ASSOCIATE stops processing under these circumstances:

• For associations, when a service listed in the input flist already exists in the /device object.

• When the validation of the device-to-service association fails.

If the opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back and no association or disassociation takes place.

Deleting /device Objects

Use PCM_OP_DEVICE_DELETE to delete /device objects.

This opcode calls the PCM_OP_DEVICE_POL_DELETE policy opcode before it deletes any device objects. By default, this policy opcode checks whether the device is associated with any services, and if it is, stops the transaction. You can customize this opcode to bypass this check or to perform other validation steps.

By default, PCM_OP_DEVICE_POL_DELETE stops processing under these circumstances:

• When the device is still associated with a service.

• When there is an error in the syntax of the input flist.

To delete devices, your custom device-creation application must call PCM_OP_DEVICE_DELETE directly and pass in the following data:

• The POID of the /device object.

• The name of the program calling the opcode.

PCM_OP_DEVICE_DELETE performs these operations:

1. Calls PCM_OP_DEVICE_POL_DELETE for validation.

2. Deletes the object.

3. If events are being recorded, generates an /event/device/delete object.

The opcode stops processing if PCM_OP_DEVICE_POL_DELETE fails.