36 About Managing SIM Card Inventory

This chapter describes how to manage SIM card inventory in your Oracle Communications Billing and Revenue Management (BRM) system by using SIM Manager and SIM Administration Center.

Important:

SIM Manager and SIM Administration Center are optional components, not part of base BRM.

You need to manage SIM card inventory when you offer GSM services. For information about GSM Manager, see "About Integrating Wireless Services".

Before using SIM Manager and SIM Administration Center, you need to know the following information:

Basic BRM concepts. See BRM Concepts.
BRM system architecture. See "BRM System Architecture" in BRM Concepts.
How to create and edit BRM configuration files. See "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

About Managing SIM Cards

To manage SIM cards, you use the following components:

SIM Manager includes the opcodes and storable classes required for creating and managing SIM card devices in the BRM database.
SIM Administration Center is a GUI application that you use to create and process SIM card orders, and to change SIM card brand and network element.

You use Customer Center to assign and manage SIM cards in customer accounts. For more information, see information about working with GSM accounts in the Customer Center Help.

About Creating SIM Cards

Use SIM Administration Center to order SIM cards from a vendor. For complete instructions on using SIM Administration Center, see the SIM Administration Center Help.

To order SIM cards:

Create an order in SIM Administration Center.

The order is stored in the BRM database and can be updated or canceled.
Create one or more vendor request files. This file specifies the quantity of SIM cards, the starting SIM card and IMSI numbers, and the SIM card attributes, such as the carrier name and SIM card format. This text file follows the standard GEMPLUS file format for SIM card orders.

Vendor request files cannot specify more than 5000 SIM cards. If you create an order for more than 5,000 cards, the order is automatically divided into multiple files. For example, if you create an order for 50,000 SIM cards, SIM Administration Center creates 10 vendor request files of 5,000 SIM cards each. (See "About SIM Card Request and Response Files".)

You can create a maximum order of 499,995,000 SIM cards, which would create 99,999 vendor request files.

You can change the default values for maximum quantity of SIM cards in an order and maximum number of SIM cards in a request file. See "Customizing SIM Administration Center".
Send the vendor request files to the vendor. You can use any file transfer method, such as FTP or email.
Receive the vendor response files and process them in SIM Administration Center. This creates a /device/sim object for each SIM card.

Note:
Multiple vendor request files are created automatically, based on the size of the order. However, you need to process each vendor response file individually.

You can pre-provision SIM cards when you process the vendor response files. When you pre-provision a SIM card, the SIM card is assigned a SIM card number and an IMSI number on the network. For more information, see "About SIM Card Pre-Provisioning".

Figure 36-1 shows the process for creating SIM cards:

Figure 36-1 SIM Card Creation Process

Description of ''Figure 36-1 SIM Card Creation Process''

About SIM Card Orders

Note:

Contact your SIM card vendor for information about the SIM card attributes. For example, you need to define your graphic elements (the logo and graphics that are printed on the card).

When you create an order, you can specify the following order attributes:

Customer name and address information. This can be your company, or a Branded service management site.

The name and address information for the vendor who creates the SIM cards.

Note:

There are limitations on how many characters you can use for each piece of customer or vendor information. However, these limitations allow for more characters than you will probably use. For more information, see the /order object definition.

The quantity of SIM cards in the order. By default, the maximum is 499,995,000 SIM cards.
Starting SIM card number and IMSI.
Brand.
SIM card attributes:
- SIM card format, for example, ISO or Plug-in
- Carrier name
- Transport key
- Electrical profile
- Graphical reference, for example, a company logo
- SIM card number prefix
- IMSI prefix
- Network element

Figure 36-2 shows the Order Details tab used for specifying SIM card attributes in SIM Administration Center:

Figure 36-2 Order Details Tab

Description of ''Figure 36-2 Order Details Tab''

About Managing Orders

When you create and manage SIM card orders, BRM assigns a status to the order. SIM Administration Center displays the order status.

When you create an order, the status is New. You can save a new order, or cancel it. When you cancel an order, the order status is set to Canceled. You can also modify an order if it is in the New status. You cannot delete an order.
After you create a request file, the order status is set to Requested. When an order has the Requested status, you cannot cancel or modify it.
When you begin processing vendor response files, the order status is set to Partially Received.
After you process all the vendor response files in an order, the order status is set to Received.

When the order has a Received or Partially Received status, you cannot change the order attributes. However, after you process the vendor response file, you can change the SIM card brand and network element.

You can search for orders of any status. Figure 36-3 shows the attributes you use when searching for an order:

Figure 36-3 Order Search Attributes

Description of ''Figure 36-3 Order Search Attributes''

Note:

SIM card orders are stored in the database as /order/sim objects.

About SIM Card Request and Response Files

You manage orders with your SIM card vendor by exchanging request and response files. The request files include information about the order, and are used by the vendor to create the SIM cards. The response files contain information from the vendor about the SIM cards.

SIM Administration Center automatically generates request files using the following naming convention:

Customer_abbreviationXXXXX.inp

The customer abbreviation is the first three letters from the name in the Customer name field when creating the order.
The customer abbreviation is followed by five digits, incremented for each file in the order. The first file in an order uses 00001.

For example, if the customer name is ”Oracle,” the first file in an order is named Ora00001.inp.

Important:

All orders that you create for the same customer use the same file names. Therefore, when creating request files, you should always put them in a new or empty folder for each order, so files from previous orders are not overwritten.

The vendor response files use the following naming convention:

Customer_abbreviationXXXXX.out

The customer abbreviation is the first three letters from the name in the Customer name field when creating the order.
The customer abbreviation is followed by five digits, incremented for each order. The first file in an order uses 00001.

For example, if the customer name is ”Oracle,” the first file in an order is named Ora00001.out.

About SIM Card Pre-Provisioning

When you process vendor response files, you can also pre-provision SIM cards. This allows a customer to perform tasks such as calling a service center with their new phone.

Note:

You can create brand-specific pre-provisioning services. In that case, all SIM cards for a brand are associated with the same service.

Important:

If you pre-provision SIM cards, you must define the pre-provisioning service. See "Specifying the Pre-Provisioning Service".
If you do not pre-provision SIM cards, you must change the device state transition. See "Customizing How to Pre-Provision SIM Cards".

When a SIM card is pre-provisioned, the following actions occur:

BRM sends information about each SIM card to the Provisioning Data Manager (dm_prov_telco). This information includes the IMSI, SIM card number, an encrypted KI value, the network element, and a dummy MSISDN number.

Note:
The dummy MSISDN number is a placeholder. You can change the MSISDN number if you customize pre-provisioning. See "Customizing How to Pre-Provision SIM Cards".
The Wireless Provisioning DM sends the provisioning request to the provisioning system, which communicates with the network to provision the SIM card.
BRM updates the SIM card device state to one of the following:
- If provisioning succeeds, the SIM card device state is set to Released. A CSR can assign this SIM card to a customer. Because the customer does not need to know about the pre-provisioning service, the SIM card device in the BRM database is disassociated from the pre-provisioning service object.
- If provisioning fails, the SIM card device state is set to Failed Provisioning.

Enabling SIM Card Pre-Provisioning

To enable SIM card pre-provisioning:

Configure PCM_OP_SIM_DEVICE_PROVISION (opcode number 2403) in state transition 0 (Raw) -> 1 (New) by editing the pin_device_state_sim file and loading it with the load_pin_device_state utility.

This example shows how to enable pre-provisioning:
```
New -> Assigned or Provisioning 
1: 1: 1: 1: 2403: 0 
2: 0: 0 
5: 0: 0 
3: 0: 0 
```
Configure the following information in the BRM_Home/sys/data/config/pin_notify file (if not already configured) for state transition and load it with load_pin_notify.
```
2706    0       /event/notification/device/state 
```
In the BRM_Home/sys/data/config/pin_telco_provisioning configuration file, specify the pre-provisioning information for each device type using the following syntax. A separate line is required for each field, even for the same device type.
```
Device provisioning info:
DeviceType, DeviceState, ProvAction, Field1, ”String1”,
DeviceType, DeviceState, ProvAction, Field2, ”String2” 
```
where:
- DeviceType specifies the type of device to be pre-provisioned.
- DeviceState specifies the device state that triggers the generation of a service order. If you do not specify the DeviceState value, service orders are generated for all device state transitions.
- ProvAction specifies the provisioning action for the device objects in the service order. In this case, you always use the value P, for provisioning.
- FieldX specifies the name of a field that contains a device attribute to include in the service order. Field names are replaced by actual values when you run pin_telco_provisioning.
- StringX specifies a string that is used in the service order to identify the attribute specified by the corresponding Field value. You can query for the string in the service order.
For example, the following lines add the authentication key, IMSI, and device ID values to the service order when a SIM card is pre-provisioned.
```
/device/sim, 3, P,PIN_FLD_DEVICE_SIM.PIN_FLD_KI "KI",
/device/sim, 3,P,PIN_FLD_DEVICE_SIM.PIN_FLD_IMSI "IMSI",
/device/sim, 3,P,PIN_FLD_DEVICE_SIM.PIN_FLD_DEVICE_ID "SIM" 
```
Load the file into the provisioning configuration object by using the load_pin_telco_provisioning utility.

About Managing SIM Cards in a Branded System

When you log in to SIM Administration Center, your login associates you with a brand. When you create and process an order, you can assign the order to the login brand, or any sub-brand. All SIM cards in the order are also associated with the same brand.

You cannot change the brand of an order.

You can change the brand of SIM card devices if the device state is Released. After a SIM card has been assigned to a customer, you cannot change the brand, even if the device state is Unassigned. See "Changing the Brand or Network Element of SIM Cards".

You cannot create brand-specific sets of network elements or SIM card formats. All network elements and SIM card formats can be used by all brands.

See "About Branding" in BRM Managing Customers.

Managing SIM Cards in a Multischema System

If you manage SIM cards in a multischema system:

You cannot change the brand of a SIM card to a brand that is hosted in a different database schema from the schema that the current brand is hosted in. For example, if a SIM card belonging to Brand A is in schema 0.0.0.1, you cannot change the SIM card to Brand B if Brand B is in schema 0.0.0.2.
If you log in as a brand host administrator and select Brand Host as the brand to create an order, you can create orders only in the schema that you logged in to. If you select any other brand, the order is created in the schema that hosts the selected brand.
When searching for SIM cards or orders, if you log in as a brand host administrator and you select the top-level brand without including sub-brands in the search criteria, the search results include only SIM cards or orders from the schema you logged in to.
In a multischema environment that is not brand enabled, you can create SIM cards only in the schema you are logged in to.

About Associating a SIM Card with a Customer's Service

When an account is created with a GSM service, or a SIM card is added to an existing account, the SIM card is provisioned, and associated with a service. The SIM card device state is set to Assigned.

When you associate a SIM card with a service, you usually also associate a number. See "About Associating SIM Cards and Numbers with Services".

About SIM Card Device States

When you manage SIM cards, the SIM card devices have the following device states:

When you process a vendor response file, you create SIM card devices in the database. The device state of the SIM cards is New.
While a SIM card is being provisioned, the device state of the SIM cards in the file is set to Provisioning. After provisioning, a card is in one of two states:
- If provisioning succeeds, the device state is set to Released.
- If provisioning fails, the device state is set to Failed Provisioning. The device object is created in the database, but it cannot be assigned. (You can change the device state transitions to enable failed SIM cards to be assigned. See "Customizing SIM Card Device States".)
When an account is created and assigned a SIM card, the device state is set to Assigned. If the account is inactive, the SIM card status remains Assigned.
When all services associated with the SIM card are canceled, the SIM card is disassociated from all services and the device state is set to Unassigned. (If the SIM card is associated with multiple services, the SIM card remains Assigned as long as one service is active.) By default, you cannot assign a SIM card when it is in the Unassigned state. (You can change the device state transitions to allow unassigned SIM cards to be assigned. See "Customizing SIM Card Device States".)

Figure 36-4 shows the progression of SIM card device states:

Figure 36-4 SIM Card Device State Progression

Description of ''Figure 36-4 SIM Card Device State Progression''

Changing the Brand or Network Element of SIM Cards

You use SIM Administrator to change the following SIM card attributes:

The network element.
The brand associated with the SIM cards.

Note:
You cannot use the SIM Administration Center to associate SIM cards with accounts and services, or change the status of a SIM card. To do those tasks, use Customer Center.

To change the SIM card brand or network element, you search for the SIM card. You can base your search on the SIM card attributes, as shown in Figure 36-5:

Figure 36-5 SIM Card Search Attributes

Description of ''Figure 36-5 SIM Card Search Attributes''

From the search results, select the SIM cards that you want to modify. You can only change the brand and network elements for SIM cards in the Released state.

For complete instructions on using SIM Administration Center, see the SIM Administration Center Help.

About SIM Card Customization Options

You can customize how you manage SIM Card inventory as follows:

You can customize network elements.

Important:
By default, there are only sample network elements; you must add your own. See "Creating Network Elements".
You can customize SIM card device and service associations. See "Customizing SIM Card and Service Associations".
You can customize SIM card device states. See "Customizing SIM Card Device States".
You can create custom SIM card formats. See "Creating SIM Card Formats".
You can choose to not pre-provision SIM cards, or to pre-provisioning them with a different service, for example, a prepaid service. See "Customizing How to Pre-Provision SIM Cards".
You can customize how SIM Administration Center works. See the following:

Getting Information about SIM Card Usage

You can get information about SIM card inventory and status by running the SIM Manager reports. See "SIM Card Inventory Management Report" in BRM Reports.

In addition, you can display the history of a customer's SIM card in Customer Center. See information about displaying SIM card history in the Customer Center Help.

About the SIM Manager Opcodes

To create SIM cards in the BRM database, SIM Manager uses the following opcodes:

PCM_OP_SIM_CREATE_ORDER. See "Creating and Updating SIM Card Orders".
PCM_OP_SIM_UPDATE_ORDER. See "Creating and Updating SIM Card Orders".
PCM_OP_SIM_PROCESS_ORDER_RESPONSE. See "Creating SIM Cards".
PCM_OP_SIM_DEVICE_PROVISION. See "Provisioning SIM Cards".

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.

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

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. See "About SIM Card Pre-Provisioning".
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.

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. See "Customizing How to Pre-Provision SIM Cards".

Customizing SIM Card Manager

Use the following opcodes to customize SIM Manager:

PCM_OP_SIM_POL_DEVICE_ASSOCIATE. See "Customizing SIM Card Service Association".
PCM_OP_SIM_POL_DEVICE_CREATE. See "Customizing SIM Card Number Changes".
PCM_OP_SIM_POL_DEVICE_SET_ATTR. See "Customizing SIM Card Validation".
PCM_OP_SIM_POL_DEVICE_SET_BRAND. See "Customizing SIM Card Brand Association".

Customizing SIM Card Service Association

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

If the service is being associated, this opcode 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, this opcode disassociates the service and calls PCM_OP_DEVICE_SET_STATE to change the status from Assigned to Unassigned.

To allow Pipeline Manager to find an account based on the IMSI or MSISDN in the CDR, this opcode 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.
It returns an error when the device and the service to be associated with it are not associated with the same brand.

Customizing SIM Card Validation

Use the PCM_OP_SIM_POL_DEVICE_CREATE policy opcode 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 the PCM_OP_SIM_POL_DEVICE_SET_ATTR policy opcode 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_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).

Customizing SIM Card Brand Association

Use the PCM_OP_SIM_POL_DEVICE_SET_BRAND policy opcode to change how SIM cards can be associated with brands.

When changing the SIM card brand, this opcode validates that the SIM card device state is Released. See "About Managing SIM Cards in a Branded System".

This opcode returns an error if the device state is anything other than Released.