11 Device Management Opcodes

Learn about the tasks you can perform using the Oracle Communications Billing and Revenue Management (BRM) Device Manager APIs.

For more information, see "Managing Devices with BRM" in BRM Developer's Guide.

Topics in this document:

• Opcodes Described in This Chapter

• About the Device Management Opcodes

• Creating /device Objects

• Changing Device Attributes and States

• Associating /service and /device Objects

• Deleting /device Objects

Opcodes Described in This Chapter

Table 11-1 lists the opcodes described in this chapter.

Caution:

• Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.

• Do not use SQL commands to change data in the database. Always use the API.

Table 11-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_APN_POL_DEVICE_SET_STATE	Changing the State of a /device Object
PCM_OP_DEVICE_ASSOCIATE	Associating /service and /device Objects Changing the State of a /device Object Deleting /device Objects
PCM_OP_DEVICE_CREATE	Creating /device Objects
PCM_OP_DEVICE_DELETE	Deleting /device Objects
PCM_OP_DEVICE_POL_ASSOCIATE	Associating /service and /device Objects
PCM_OP_DEVICE_POL_CREATE	Creating /device Objects
PCM_OP_DEVICE_POL_DELETE	Deleting /device Objects
PCM_OP_DEVICE_POL_SET_ATTR	Changing the Attributes of /device Objects
PCM_OP_DEVICE_POL_SET_STATE	Changing the State of a /device Object
PCM_OP_DEVICE_SET_ATTR	Changing the Attributes of /device Objects
PCM_OP_DEVICE_SET_STATE	Changing the State of a /device Object Creating /device Objects
PCM_OP_DEVICE_UPDATE	Changing Device Attributes and States
PCM_OP_IP_POL_DEVICE_ASSOCIATE	Associating /service and /device Objects
PCM_OP_IP_POL_DEVICE_CREATE	Creating /device Objects
PCM_OP_IP_POL_DEVICE_DELETE	Deleting /device Objects
PCM_OP_IP_POL_DEVICE_SET_ATTR	Changing the Attributes of /device Objects
PCM_OP_NUM_POL_DEVICE_DELETE	Deleting /device Objects

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 and states, use PCM_OP_DEVICE_UPDATE. This wrapper opcode calls these opcodes to make the separate changes in 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_STATE and PCM_OP_DEVICE_POL_SET_STATE change device states.

  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.

PCM_OP_DEVICE_CREATE checks the device type on the input flist (PIN_FLD_OBJ_TYPE) to determine whether to call further device FM opcodes. For example, if the device type is /device/ip, this opcode calls PCM_OP_DEVICE_POL_CREATE, which in turn calls PCM_OP_IP_POL_DEVICE_CREATE.

PCM_OP_DEVICE_CREATE calls PCM_OP_DEVICE_POL_CREATE before it creates any /device objects. This 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.

PCM_OP_DEVICE_POL_CREATE probes the device type (PIN_FLD_OBJ_TYPE field) and may call other device FM opcodes. For example, if the device type is /device/ip, this opcode calls PCM_OP_IP_POL_DEVICE_CREATE to perform the validation checks it contains.

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. Creates a /device object of the type specified in the input flist. This object includes all mandatory attributes for the device type.

4. Calls PCM_OP_DEVICE_SET_STATE to set the initial device state.

5. 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 and States

Use PCM_OP_DEVICE_UPDATE to change any combination of device attribute values and states with a single transaction.

This opcode is called by BRM GUI applications and BRM FMs that modify device characteristics.

PCM_OP_DEVICE_UPDATE calls the following opcodes to perform validation checks before committing any changes:

• PCM_OP_DEVICE_POL_SET_ATTR

• PCM_OP_DEVICE_POL_SET_STATE

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 PCM_OP_DEVICE_POL_SET_ATTR before it sets attributes. For example, you can write code to validate that the device ID in the input flist conforms to the pattern for a particular device type. PCM_OP_DEVICE_POL_SET_ATTR is an empty hook, but you can customize it to validate device IDs or perform other validation tasks.

PCM_OP_DEVICE_POL_SET_ATTR probes the device type (PIN_FLD_OBJ_TYPE field) and may call other device FM opcodes. For example, if the device type is /device/ip, this opcode calls PCM_OP_IP_POL_DEVICE_SET_ATTR to perform the validation checks it contains.

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.

  You cannot use PCM_OP_DEVICE_SET_ATTR alone to change the 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.

PCM_OP_DEVICE_SET_ATTR checks the device type on the input flist (PIN_FLD_OBJ_TYPE) to determine whether to call further device FM opcodes. For example, if the device type is /device/ip, this opcode calls PCM_OP_DEVICE_POL_SET_ATTR, which in turn calls PCM_OP_IP_POL_DEVICE_SET_ATTR.

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

PCM_OP_DEVICE_SET_STATE checks the device type on the input flist (PIN_FLD_OBJ_TYPE) to determine whether to call further device FM opcodes. For example, if the device type is /device/apn, this opcode calls PCM_OP_DEVICE_POL_SET_STATE, which in turn calls PCM_OP_APN_POL_DEVICE_SET_STATE.

PCM_OP_DEVICE_SET_STATE 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 PCM_OP_DEVICE_POL_SET_STATE.

Note:

PCM_OP_DEVICE_SET_STATE uses the event notification feature. Before using this opcode, you must configure 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.

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.

PCM_OP_DEVICE_POL_SET_STATE probes the device type (PIN_FLD_OBJ_TYPE field) and may call other device FM opcodes. For example, if the device type is /device/apn, this opcode calls PCM_OP_APN_POL_DEVICE_SET_STATE to perform the validation checks it contains.

PCM_OP_DEVICE_POL_SET_STATE is an empty hook.

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, 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 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.

PCM_OP_DEVICE_ASSOCIATE calls PCM_OP_DEVICE_POL_ASSOCIATE before it associates any objects.

PCM_OP_DEVICE_POL_ASSOCIATE enables customized validation during device-to-service association and disassociation. For example, you could limit the number of associations for particular device types or trigger a state change after certain associations or disassociations.

PCM_OP_DEVICE_POL_ASSOCIATE probes the device type (PIN_FLD_OBJ_TYPE field) and may call other device FM opcodes. For example, if the device type is /device/ip, this opcode calls PCM_OP_IP_POL_DEVICE_ASSOCIATE to perform the validation checks it contains.

PCM_OP_DEVICE_POL_ASSOCIATE is an empty hook.

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.

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.

PCM_OP_DEVICE_DELETE checks the device type on the input flist (PIN_FLD_OBJ_TYPE) to determine whether to call further device FM opcodes. For example, if the device type is /device/ip, this opcode calls PCM_OP_DEVICE_POL_DELETE, which in turn calls PCM_OP_IP_POL_DEVICE_DELETE.

PCM_OP_DEVICE_DELETE calls PCM_OP_DEVICE_POL_DELETE before it deletes any device objects. By default, this 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. For example, you can disable the service association check that is performed by default. You can also include a call to PCM_OP_DEVICE_ASSOCIATE to automatically disassociate services before device deletion.

PCM_OP_DEVICE_POL_DELETE checks whether a device is associated with any services, and if it is, stops the transaction. 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.

PCM_OP_DEVICE_POL_DELETE probes the device type (PIN_FLD_OBJ_TYPE field) and may call other device FM opcodes. For example, if the device type is /device/ip, this opcode calls PCM_OP_IP_POL_DEVICE_DELETE to perform the validation checks it contains.

PCM_OP_DEVICE_POL_DELETE calls a different opcode to customize device deletion. For example, if PIN_FLD_OBJ_TYPE is /device/num, this opcode calls PCM_OP_NUM_POL_DEVICE_DELETE to perform the validation checks it contains.

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.