Number Manager and SIM Card Manager Opcode Workflows

19 Number Manager and SIM Card Manager Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) Number Manager and SIM Card Manager opcode workflows.

Topics in this document:

Opcodes Described in This Chapter

Table 19-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 19-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_SCHEDULE_CREATE	Managing Number Quarantine
PCM_OP_ACT_SCHEDULE_DELETE	Managing Number Quarantine
PCM_OP_CUST_POL_CANONICALIZE	Creating Blocks of Numbers
PCM_OP_DEVICE_ASSOCIATE	Customizing How Numbers Are Associated with Services
PCM_OP_DEVICE_CREATE	Creating Blocks of Numbers Customizing Telephone Number Attributes Creating SIM Cards Customizing SIM Card Validation
PCM_OP_DEVICE_POL_ASSOCIATE	Customizing SIM Card Service Association
PCM_OP_DEVICE_POL_DELETE	Deleting a Number
PCM_OP_DEVICE_SET_ATTR	Modifying Blocks of Numbers Managing Number Quarantine Customizing How a Number Can Be Changed
PCM_OP_DEVICE_SET_STATE	Managing Number Quarantine Customizing How Numbers Are Associated with Services Provisioning SIM Cards Customizing SIM Card Service Association
PCM_OP_NUM_CREATE_BLOCK	Creating Blocks of Numbers Customizing Number Normalization
PCM_OP_NUM_MODIFY_BLOCK	Creating Blocks of Numbers Modifying Blocks of Numbers
PCM_OP_NUM_POL_CANONICALIZE	Creating Blocks of Numbers Modifying Blocks of Numbers Customizing Number Normalization Customizing How a Number Can Be Changed
PCM_OP_NUM_POL_DEVICE_ASSOCIATE	Customizing How Numbers Are Associated with Services
PCM_OP_NUM_POL_DEVICE_CREATE	Customizing Telephone Number Attributes
PCM_OP_NUM_POL_DEVICE_DELETE	Deleting a Number
PCM_OP_NUM_POL_DEVICE_SET_ATTR	Customizing How a Number Can Be Changed
PCM_OP_NUM_PORT_IN	Managing Number Portability
PCM_OP_NUM_PORT_OUT	Managing Number Portability
PCM_OP_NUM_QUARANTINE	Managing Number Quarantine
PCM_OP_NUM_SPLIT_BLOCK	Splitting Blocks of Numbers
PCM_OP_SIM_CREATE_ORDER	Creating and Updating SIM Card Orders
PCM_OP_SIM_DEVICE_PROVISION	Provisioning SIM Cards
PCM_OP_SIM_POL_DEVICE_ASSOCIATE	Customizing SIM Card Service Association
PCM_OP_SIM_POL_DEVICE_CREATE	Customizing SIM Card Validation
PCM_OP_SIM_POL_DEVICE_SET_ATTR	Customizing SIM Card Validation Customizing SIM Card Number Changes
PCM_OP_SIM_POL_ORDER_CREATE	Creating SIM Cards
PCM_OP_SIM_PROCESS_ORDER_RESPONSE	Creating SIM Cards
PCM_OP_SIM_UPDATE_ORDER	Creating and Updating SIM Card Orders Creating SIM Cards

Number Manager Opcodes

See the following topics:

Creating Blocks of Numbers

To create a block of numbers, use PCM_OP_NUM_CREATE_BLOCK. This opcode creates a /block object and the specified number of telephone numbers, created as /device/num objects.

The opcode identifies whether you want to modify the block or extend/shrink the block. If the value of the PIN_FLD_REQ_MODE flag is True, PCM_OP_NUM_MODIFY_BLOCK extends or shrinks the number block. If the value of the flag is False, PCM_OP_NUM_MODIFY_BLOCK modifies the number block.

PCM_OP_NUM_CREATE_BLOCK calls PCM_OP_CUST_POL_CANONICALIZE and PCM_OP_NUM_POL_CANONICALIZE to format the block name and telephone numbers. It calls PCM_OP_DEVICE_CREATE to create numbers and PCM_OP_CREATE_OBJ to create the block.

This opcode returns an error if the block name already exists or if any of the telephone numbers already exists.

Modifying Blocks of Numbers

To modify a block of numbers, use PCM_OP_NUM_MODIFY_BLOCK.

If numbers are changed, this opcode calls PCM_OP_NUM_POL_CANONICALIZE to normalize the number and PCM_OP_DEVICE_SET_ATTR to change attributes such as the manufacturer, model number, and description.

This opcode returns an error if the new block name already exists or if the range of numbers specified is not valid.

If this opcode runs successfully, it returns the POID of the modified block and an array of POIDs for new blocks.

Splitting Blocks of Numbers

To split a block of numbers, use PCM_OP_NUM_SPLIT_BLOCK.

The input includes the POID and name of the existing block and the start and end numbers for each block.

If this opcode runs successfully, it returns the POIDs of the original block and the new blocks.

If an invalid block or number attribute is found, this opcode returns an error to the error buffer.

Managing Number Quarantine

To quarantine numbers, use PCM_OP_NUM_QUARANTINE.

This opcode creates or deletes a /schedule/device object to manage the telephone number quarantine. PCM_OP_NUM_QUARANTINE is called by PCM_OP_DEVICE_SET_STATE when the number device state changes in and out of the Quarantined state. This is the default behavior as specified in the number device state configuration.

If the state transition is to Quarantined, this opcode calls PCM_OP_ACT_SCHEDULE_CREATE to create a /schedule/device object that, at the end of the quarantine period, is used to change the state to Unassigned.
There are two possible exit transitions from the Quarantined state:
- If the state transition is from Quarantined to Assigned, PCM_OP_NUM_QUARANTINE calls PCM_OP_SEARCH to find the /schedule/device object associated with the number and calls PCM_OP_ACT_SCHEDULE_DELETE to delete the /schedule/device object.
- If the state transition is from Quarantined to Unassigned, PCM_OP_NUM_QUARANTINE calls PCM_OP_DEVICE_SET_ATTR to delete the text in the device description field.

To customize how number quarantine works, you can edit and load the pin_device_state file to call a custom opcode instead of calling PCM_OP_NUM_QUARANTINE. See "Defining the Device Life Cycle" in BRM Developer's Guide.

Managing Number Portability

To manage number portability, use PCM_OP_NUM_PORT_IN and PCM_OP_NUM_PORT_OUT.

PCM_OP_NUM_PORT_IN creates a number device using the provided number. This opcode is used when porting the number from another service provider into the existing network.

PCM_OP_NUM_PORT_IN calls opcodes to do the following:

Create the number and the /device/num object.
Set the status of the /device/num object.
Reformats the number provided in the input flist to your required format.
Validate the required information in the input flist.
Search for the provided number in the database and, if found, return an error.
If not found, create the number in the number device and update the status of the number device and commit the number to associate the device with the account.

PCM_OP_NUM_PORT_OUT sets the status of the specified telephone number as quarantine_port_out in the /device/num object. PCM_OP_NUM_PORT_OUT is used when porting the number from your network to another service provider.

Note:

The present state of the device must be assigned and the new state must be set to quarantine_port_out. If these are not the states, PCM_OP_NUM_PORT_IN returns an error.

PCM_OP_NUM_PORT_OUT calls opcodes to perform the necessary validations and set the status of the number device. This opcode:

Validates the number to be ported out.
Validates the current status of the number device.
Updates the status of the number device.

Customizing Number Manager

See the following topics:

Customizing Number Normalization

To customize number normalization, use PCM_OP_NUM_POL_CANONICALIZE. This opcode handles number normalization when receiving numbers from applications and outputting numbers to other opcodes or applications.

This opcode is called by:

PCM_OP_NUM_CREATE_BLOCK
PCM_OP_NUM_MODIFY_BLOCK
PCM_OP_NUM_PORT_IN

PCM_OP_NUM_POL_CANONICALIZE is called by PCM_OP_NUM_CREATE_BLOCK when a block of numbers is created.

You can customize this opcode to change normalization rules for handling numbers.

By default, this opcode performs the following translations:

Adds two leading zero characters (00) if they are missing from the input.
Removes all characters except digits.

PCM_OP_NUM_POL_CANONICALIZE returns an error when the minimum or maximum length is not valid. These values are defined in the PIN_NUM_CANON_MIN_LENGTH and PIN_NUM_CANON_MAX_LENGTH entries in the pin_num.h file in BRM_home/include.

If successful, this opcode returns the normalized string.

Customizing How Numbers Are Associated with Services

To customize how numbers are associated with services, use PCM_OP_NUM_POL_DEVICE_ASSOCIATE. This opcode specifies the rules for associating or disassociate a number and a service. This opcode is called by PCM_OP_DEVICE_ASSOCIATE when a number is associated or disassociated with a service.

If the number is being associated and there is no service currently associated with the number, this opcode calls PCM_OP_DEVICE_SET_STATE to change the state to Assigned. This is the default behavior as specified in the number device state configuration.
If the number is being disassociated, and there is only one service associated with the number, this opcode calls PCM_OP_DEVICE_SET_STATE to change the state to Quarantined. This is the default behavior as specified in the number device state configuration.

When associating a number that is already associated with a service, the following rules are applied:

A number can be associated with multiple services, but each service must be of a different type. For example, you cannot associate one number with two SMS services. To do so, you must customize PCM_OP_NUM_POL_DEVICE_ASSOCIATE.
A number can be associated with multiple services, but all services must belong to the same account.
If an associated service has a SIM card device associated with it, the number and the SIM card must have the same network element.

To find an account based on the IMSI or MSISDN in the CDR, PCM_OP_NUM_POL_DEVICE_ASSOCIATE copies the IMSI and MSISDN to the alias list array in the associated service object. The element ID is significant:

The IMSI is copied to ALIAS_LIST[0]
The MSISDN is copied to ALIAS_LIST[1]

PCM_OP_NUM_POL_DEVICE_ASSOCIATE returns an error in the following cases:

The number is already associated with the same type of service. For example, if the number is already associated with a fax service, an error is returned if you try to associate the number with another fax service.
The service that is being associated does not belong to the same account as an existing associated service.
The number network element is not the same as the network element of a SIM card that is already associated with the service.

Customizing Telephone Number Attributes

To customize telephone number attributes when a number is created, use PCM_OP_NUM_POL_DEVICE_CREATE. This opcode validates a new number to make sure it is unique in the database.

This opcode is called by PCM_OP_DEVICE_CREATE and calls PCM_OP_NUM_POL_CANONICALIZE.

You can customize this opcode if you extend the number device attributes and require additional validation or if you want to change existing validations.

PCM_OP_NUM_POL_DEVICE_CREATE returns an error if a new number is not unique in the database.

Customizing How a Number Can Be Changed

To customize how a number can be changed, for example, which digits can be changed, use PCM_OP_NUM_POL_DEVICE_SET_ATTR.

By default, PCM_OP_NUM_POL_DEVICE_SET_ATTR supports changing US area codes by using the following logic: If the number starts with 001 and is 13 digits long, allow changing digits 4 through 6.

This opcode is called by PCM_OP_DEVICE_SET_ATTR and calls PCM_OP_NUM_POL_CANONICALIZE.

You can customize PCM_OP_NUM_POL_DEVICE_SET_ATTR to allow customized modifications on numbers. For example, you can customize this opcode to allow changing digits 5 through 7 of a number if the number starts with 44.

Deleting a Number

To delete a number, use PCM_OP_NUM_POL_DEVICE_DELETE. This opcode checks the state of the device. If the device state is PIN_NUM_STATE_NEW or PIN_NUM_STATE_UNASSIGNED, allows you to delete the device; otherwise, it generates an error and does not allow you to delete the device. This opcode is called by PCM_OP_DEVICE_POL_DELETE.

SIM Card Manager Opcodes

See the following topics:

Creating and Updating SIM Card Orders

When you use SIM Card Administrator to create an order, PCM_OP_SIM_CREATE_ORDER creates an order object (/order/sim) in the database. It returns an error if it finds a duplicate SIM card number or IMSI. The order status is set to New.

When you update an order, PCM_OP_SIM_UPDATE_ORDER updates the order object in the database. It returns an error if it finds a duplicate SIM card number or IMSI.

PCM_OP_SIM_UPDATE_ORDER also changes the order status, for example, when you process a response file, or cancel an order.

PCM_OP_SIM_UPDATE_ORDER is called when a customer updates the order, or when the order status needs to be changed, for example, after processing a vendor response file. This opcode is also called when an order is canceled.

PCM_OP_SIM_UPDATE_ORDER checks for duplicate SIM card and IMSI numbers. If no error is found, this opcode updates a SIM card order object. If the order is being canceled, this opcode changes the status to Canceled. This opcode will not function if the order is not in the New status.

Creating SIM Cards

SIM Card Manager uses PCM_OP_SIM_PROCESS_ORDER_RESPONSE to process the order response file and create SIM card device objects (/device/sim objects) in the database.

PCM_OP_SIM_PROCESS_ORDER_RESPONSE does the following:

Reads the status of the order from the order object. If an order has been canceled, or there is no matching order for the response file, this opcode terminates and reports an error.
Finds the initial state of the device as defined in the /config/device_state/sim object. If the state is New, the SIM card is pre-provisioned. To disable pre-provisioning, or customize how SIM cards are provisioned, change the initial state from New to a customized state.
Finds the network element associated with the order.
Calls PCM_OP_DEVICE_CREATE to create the SIM card devices (/device/sim) in the BRM database.
Calls PCM_OP_SIM_UPDATE_ORDER to change the status of the order to either Partially Received or Received.

The vendor response file includes a list of SIM cards that you load into the BRM database by using SIM Administration Center.

To customize how SIM cards are validated during creation, use PCM_OP_SIM_POL_ORDER_CREATE.

Provisioning SIM Cards

SIM Card Manager uses PCM_OP_SIM_DEVICE_PROVISION to associate a SIM card with a service, and to disassociate the pre-provisioning service.

This opcode is called by PCM_OP_DEVICE_SET_STATE during the state transition from initial to new and from provisioning to release.

PCM_OP_SIM_DEVICE_PROVISION is used as the validation opcode for changing the device state from New to Provisioning and from Provisioning to Released or Failed Provisioning.

To customize pre-provisioning, you can write your own opcode and use your custom opcode as the validation opcode.

Customizing SIM Card Manager

See the following topics:

Customizing SIM Card Service Association

Use PCM_OP_SIM_POL_DEVICE_ASSOCIATE to change how SIM cards and services are associated.

This opcode is called by PCM_OP_DEVICE_POL_ASSOCIATE.

If the service is being associated, PCM_OP_SIM_POL_DEVICE_ASSOCIATE validates that the network element is the same as the network element for the number associated with the same service. This opcode then calls PCM_OP_DEVICE_SET_STATE to change the status from Released to Assigned.
If the service is being unassociated, PCM_OP_SIM_POL_DEVICE_ASSOCIATE disassociates the service and calls PCM_OP_DEVICE_SET_STATE to change the status from Assigned to Unassigned.

To find an account based on the IMSI or MSISDN in the CDR, PCM_OP_SIM_POL_DEVICE_ASSOCIATE copies the IMSI and MSISDN to the alias list array in the associated service object. The element ID is significant:

The IMSI is copied to ALIAS_LIST[0]
The MSISDN is copied to ALIAS_LIST[1]

PCM_OP_SIM_POL_DEVICE_ASSOCIATE returns an error in the following cases:

It returns an error if the network element of the SIM card and telephone number are not the same.
It returns an error if the service type is already associated with the SIM card. The only exception is when two /service/telco/gsm/telephony services are associated with the same SIM card.
It returns an error when the device and the service to be associated with it are not owned by the same account.

Customizing SIM Card Validation

Use PCM_OP_SIM_POL_DEVICE_CREATE to change validation rules for creating SIM card devices.

This opcode validates a device by validating the SIM card number, IMSI, KI, and network element values. For example, it makes sure that the numbers have the correct number of digits and are in the proper syntax. It also verifies that the SIM card does not already exist in the database.

This opcode is called by PCM_OP_DEVICE_CREATE when creating a SIM card device.

Note:

For information about validating the network element when updating a device, see PCM_OP_SIM_POL_DEVICE_SET_ATTR.

Customizing SIM Card Number Changes

Use PCM_OP_SIM_POL_DEVICE_SET_ATTR to change how SIM cards and services are associated.

This opcode ensures that the SIM card number (PIN_FLD_DEVICE_ID) cannot be changed.

This opcode is called by PCM_OP_DEVICE_POL_SET_ATTR when updating a SIM card device.

This opcode returns an error if an attempt is made to change SIM card number (PIN_FLD_DEVICE_ID).