7 Installing and Configuring SIM Manager and SIM Administration Center

This chapter describes how to install and customize Oracle Communications Billing and Revenue Management (BRM) SIM Manager and SIM Administration Center.

For information about SIM Manager and SIM Administration Center, see "About Managing SIM Card Inventory".

Mandatory Configuration Tasks

In addition to installing the SIM Manager software, you must perform the following configuration tasks before you can use SIM Manager and SIM Administration Center:

Note:

You can perform these tasks in any order, but you must install SIM Manager first.

• Define and load network elements. (If Number Manager is already installed, this might already be done.) See "Creating Network Elements".

• Define SIM device states. This requires two procedures: defining and loading the state transition model, and loading the localized state descriptions. See "Customizing SIM Card Device States".

• Define SIM device and service associations. See "Customizing SIM Card and Service Associations".

• Define SIM card formats. See "Creating SIM Card Formats".

• Preprovision SIM cards, you must specify the pre-provisioning service. If you do not pre-provision SIM cards, you must change the SIM card device states. See "Customizing How to Pre-Provision SIM Cards".

• Specify whether to pre-provision SIM cards, and if so, the pre-provisioning service. See "Customizing How to Pre-Provision SIM Cards".

• Load the order_sim_status.locale file. You use this file to localize order status descriptions in SIM Administration Center. Even if you do not run a localized version of SIM Administration Center, you need to load this file. See "Loading Order Status Definitions".

• If you use an Oracle database, allow for encrypted fields. (By default, the KI value is encrypted.) See "Supporting Encrypted KI Values with Oracle".

Installing SIM Manager

Note:

If you already installed the product, you must uninstall its features before reinstalling them.

To implement SIM card provisioning, you need to install GSM Manager, including the wireless provisioning opcodes. See "Installing and Configuring GSM Manager and Provisioning Data Manager".

To install SIM Manager, see "Installing Individual BRM Components" in BRM Installation Guide.

Installing SIM Administration Center

To install SIM Administration Center, see "Installing Individual BRM Clients" in BRM Installation Guide.

Configuring Event Notification for SIM Manager

Note:

This is a mandatory configuration task.

Note:

If you already configured event notification for Number Manager, skip this procedure.

To enable SIM card provisioning, BRM uses event notification. Before you can use SIM Manager, 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" in BRM Developer's Guide.

2. Ensure that the merged file includes the entire event notification list in the BRM_home/sys/data/config/pin_notify file.

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" in BRM Developer's Guide.

4. (Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger. See "Triggering Custom Operations" in BRM Developer's Guide.

5. Load your final event notification list into the BRM database. See "Loading the Event Notification List" in BRM Developer's Guide.

For more information, see "Using Event Notification" in BRM Developer's Guide.

Customizing SIM Card and Service Associations

Note:

This is a mandatory configuration task.

By default, SIM card devices can be associated with the following services:

• /service/telco/gsm/telephony

• /service/telco/gsm/fax

• /service/telco/gsm/data

• /service/telco/gsm/sms

To change the services that a SIM card device can be associated with, edit the pin_device_permit_map file and load it by using the load_pin_device_permit_map utility. See "Defining Device-to-Service Associations" in BRM Developer's Guide.

Supporting Encrypted KI Values with Oracle

Note:

This is a mandatory configuration task.

By default, the field in the /device/sim object that stores the KI value (PIN_FLD_KI) is encrypted. If you use an Oracle database, you must edit the Oracle DM configuration file to allow for encrypted fields. Otherwise, you cannot create SIM cards.

Note:

Alternatively, you can unencrypt the PIN_FLD_KI field, but this is not recommended for security reasons. See BRM Developer's Guide.

1. Open the Oracle DM configuration file (BRM_home/sys/dm_oracle/pin.conf).

2. Uncomment the appropriate line for your operating system:

   #- crypt md5| libpin_crypt.extension "Abracadabra dabracaabrA"
   

   where extension is so for Solaris and Linux.

3. Save the file.

4. Restart the Oracle DM.

Creating Network Elements

Note:

This is a mandatory configuration task.

Note:

If you already created network elements for telephone numbers, you do not need to create them again. The same network elements are used for numbers and SIM cards.

By default, there are only sample network elements. Before creating SIM cards, you need to add the network elements that you will use with your GSM services.

To customize network elements, you edit the pin_network_elements file, then run the "load_pin_network_elements" utility to load the contents of the file into a /config/network_element object in the BRM database.

Note:

The utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

1. Edit the pin_network_elements file in BRM_home/sys/data/config. The pin_network_elements file includes examples and instructions.

   The file includes a list of network elements. For example:

   sample_network_element_1
   sample_network_element_2

   Note:

   The load_pin_network_elements utility overwrites existing network elements. If you are updating network elements, you cannot load new network elements only. You must load complete sets of network elements each time you run the load_pin_network_elements utility.

2. Save the pin_network_elements file.

3. Use the following command to load the pin_network_elements file:

   load_pin_network_elements pin_network_elements
   

To verify that the network elements were loaded, you can display the /config/network_element 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" in BRM Developer's Guide.) This example shows a network element in the /config/network_element object:

PIN_FLD_NETWORK_ELEMENT   STR  [0]  "Sample_Network_Element"

Creating SIM Card Formats

Note:

This is a mandatory configuration task.

You can customize the list of SIM card formats displayed in SIM Administration Center. The default SIM card formats are ISO and Plug-in.

To customize SIM card formats, you edit the sim_card_types.en_US sample file in the BRM_home/sys/msgs/simcardtypes directory. You then use the load_localized_strings utility to load the contents of the file into the /strings objects. See load_localized_strings in BRM Developer's Guide.

Customizing SIM Card Device States

Note:

This is a mandatory configuration task.

You can customize SIM card device states to support custom business logic. For example, you can change how SIM cards are pre-provisioned by adding custom device states. See "Customizing How to Pre-Provision SIM Cards".

To customize device states, you edit the pin_device_state_sim file in BRM_home/sys/data/config, and load it by running the load_pin_device_state utility. See "Defining the Device Life Cycle" in BRM Developer's Guide.

Adding Device State Names

When you customize device states, you need to add the new device state name to the list of device states that is displayed in SIM Administration Center. To do so, you edit the sim_device_states.en_US sample file in the BRM_home/sys/msgs/simdevicestates directory. You then use the load_localized_strings utility to load the contents of the file into the /strings objects. See "load_localized_strings" in BRM Developer's Guide.

Customizing Service Types

Note:

This is a mandatory configuration task.

You can change the services that are allowed to be associated with SIM card devices. For example, you can associate customized services or restrict the list of services.

To change service types, edit the pin_device_permit_map_sim file and load it by running the load_pin_device_permit_map utility. See "Defining Device-to-Service Associations" in BRM Developer's Guide.

Customizing How to Pre-Provision SIM Cards

Note:

This is a mandatory configuration task.

You can customize pre-provisioning as follows:

• You can bypass pre-provisioning. To do so, change the device state transition by editing the pin_device_state_sim file and loading it with the load_pin_device_state utility.

  This example shows how to configure SIM card device states without provisioning:

  # The storable class to be loaded
  /config/device_state/sim
  # The type of device for this config file
  /device/sim
  # Raw -> Released 
  0: 0: 0: 1: 0: 0
           2: 0: 0
  # Release -> Assigned
  2: 2: 2: 1: 0: 0
           5: 0: 0
  # Assigned -> Unassigned
  5: 2: 5: 1: 0: 0
           6: 0: 0
  # Unassigned -> Unassigned
  6: 3: 6: 1: 0: 0
  

  See "Customizing SIM Card Device States".

• You can change the default pre-provisioning service to use your custom pre-provisioning service. See "Specifying the Pre-Provisioning Service". You can also change the dummy MSISDN used for pre-provisioning. See "Changing the Pre-Provisioning MSISDN".

Specifying the Pre-Provisioning Service

By default, there is no pre-provisioning service. If you pre-provision SIM cards, you must create a pre-provisioning service object so you can associate pre-provisioned SIM cards with a service.

When you pre-provision SIM cards, all SIM cards are associated with a service by using a pre-provisioning service object. When you assign a SIM card to an account, the SIM card is associated with the customer's service object. (See "About Associating a SIM Card with a Customer's Service".)

To change the pre-provisioning service, you edit the pin_sim_config file and run the load_pin_sim_config utility to load the contents of the file into the /config/pre_provisioning_sim object in the BRM database.

Note:

The load_pin_sim_config utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

1. To use a different service, you need the POID of a service object created by using your custom service storable subclass:

   1. (Optional) If you use a custom service, create the service. See "Adding Support for a New Service" in BRM Developer's Guide.

   2. Create a package that uses the service (for example, /service/telco/gsm/telephony), and create an account using that service. You can use the root account.

   3. Use the testnap application or the Object Browser to find the POID of the service object.

      If you use the testnap application, use the robj command. See "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

2. Edit the pin_sim_config file in BRM_home/sys/data/config:

   • Add the POID of the default pre-provisioning service.

   • Remove the comment character (#) from the beginning of the line.

   The default entry is:

   # Service_Poid:0.0.0.1 /service/telco/gsm/telephony 0 0
   

   Example of a customized entry:

   Service_Poid:0.0.0.1 /service/telco/gsm/telephony 1 0
   

3. Save the pin_sim_config file.

4. Use the following command to load the pin_sim_config file:

   load_pin_sim_config pin_sim_config
   

   For more information, see "load_pin_sim_config".

To verify that the pre-provisioning service POID was loaded, you can display the /config/pre_provisioning_sim 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" in BRM Developer's Guide.) The /config/pre_provisioning_sim object shows the pre-provisioning service in the PIN_FLD_SERVICE_OBJ field:

1  PIN_FLD_SERVICE_OBJ  POID [0] 0.0.0.1 /service/telco/gsm/telephony 1 0

Changing the Pre-Provisioning MSISDN

To change the MSISDN used for pre-provisioning, change the following value in the fm_prov_wireless_pol_create_svc_order.c policy source code file and recompile it:

#define msisdn_val "4085551212"

For more information, see "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide.

Loading Order Status Definitions

Note:

This is a mandatory configuration task.

The status of SIM card orders is displayed in SIM Administration Center. You cannot change the functionality of the order status: for example, you cannot add a custom status: however, you can localize the status definitions that are displayed.

Note:

Even if you do not use localized order status definitions, you need to load the order_sim_status.locale file.

To localize the file, you edit a copy of the order_sim_status.en_US sample file in the BRM_home/sys/msgs/ordersimstatus directory and save the edited version with the correct locale file extension. To load the file, you use the load_localized_strings utility to load the contents of the file into the /strings objects. See "load_localized_strings" in BRM Developer's Guide.

Customizing SIM Administration Center

You can edit the SIMAdmin.properties file to customize how SIM Administration Center works. See the following topics:

• Specifying the Maximum Quantity of SIM Cards in a Request File

• Specifying the Maximum Quantity of SIM Cards in an Order

• Specifying the Information You Want to Receive about SIM Cards

• Specifying whether the Response File Includes a Check Digit

Specifying the Maximum Quantity of SIM Cards in a Request File

You can customize the quantity of SIM cards per vendor request file. By default, the quantity is 5,000. Contact your SIM card vendor to find out if they have a maximum quantity of SIM cards per file.

1. Open the SIMAdmin.properties file in the following folder:

   C:\Program Files\Common Files\Portal Software

2. Edit the RequestFileCardsPerBatch entry:

   Note:

   The value must be a multiple of 50.

   RequestFileCardsPerBatch=5000
   

3. Save and close the file.

4. Restart SIM Administration Center.

Specifying the Maximum Quantity of SIM Cards in an Order

By default, the maximum quantity of SIM cards in a single order is 499,995,000.

1. Open the SIMAdmin.properties file in the following folder:

   C:\Program Files\Common Files\Portal Software

2. Edit the MaxOrderQuantity entry:

   MaxOrderQuantity=499995000
   

3. Save and close the file.

4. Restart SIM Administration Center.

Specifying the Information You Want to Receive about SIM Cards

The information returned about SIM cards from the vendor is specified in the Var_Out field in the vendor request file. By default, this field is formatted in the request files as follows:

Var_Out:PIN1/PIN2/PUK1/PUK2/ADM1/Ki

To change how the entry is formatted in the request files:

1. Open the SIMAdmin.properties file in the following folder:

   C:\Program Files\Common Files\Portal Software

2. Edit the Var_Out entry:

   Var_Out=PIN1/PIN2/PUK1/PUK2/ADM1/Ki
   

3. Save and close the file.

4. Restart SIM Administration Center.

Specifying whether the Response File Includes a Check Digit

In some cases, the SIM card vendor requires a check digit in the response file. By default, SIM Administration Center assumes that the vendor response file does not include a check digit.

To include a check digit in the response file:

1. Open the SIMAdmin.properties file in the following folder:

   C:\Program Files\Common Files\Portal Software

2. Edit the ResponseContainsCheckDigit entry:

   ResponseContainsCheckDigit=false
   

3. Save and close the file.

4. Restart SIM Administration Center.

Specifying the Size of Searches

You can change the value of the step search that SIM Administration Center uses. For slower systems, a smaller step search size can return results faster.

1. Open the SIMAdmin.properties file in the following folder:

   C:\Program Files\Common Files\Portal Software

2. Edit the searchStepSize entry:

   searchStepSize=100
   

3. Save and close the file.

4. Restart SIM Administration Center.

Specifying SIM and IMSI number maximum length

You can determine whether SIM Administration Center prepends zeroes to SIM and IMSI numbers to make them the maximum standard length (19 characters for SIM and 15 for IMSI). This property applies to numbers created in request files and to numbers specified in searches in SIM Administration Center.

By default, zeroes are not prepended to the numbers. Setting the maximumStandardLength property to true causes SIM Administration Center to prepend zeroes to SIM and IMSI numbers.

Note:

In previous versions, the default behavior was to prepend zeroes to the numbers. Therefore, if you need to search on SIM card inventory created in earlier versions, you should set the maximumStandardLength property to true.

1. Open the SIMAdmin.properties file in the following folder:

   C:\Program Files\Common Files\Portal Software

2. Edit the maximumStandardLength entry:

   maximumStandardLength=true
   

3. Save and close the file.

4. Restart SIM Administration Center.

Creating SIM Cards for Testing

To test your wireless integration, you need SIM card devices in your database so you can create accounts. You can create a set of SIM cards to test with.

Note:

This procedure creates an order with five SIM cards. The standard file format uses multiples of 50 SIM cards.

To create a set of SIM cards to test with:

1. In SIM Administration Center, create an order using the following entries:

   • Customer Info tab:

     Customer name: Sample

     Address: 100 Main St

     City: Anytown

     State/Province: CA

     Zip/Postal: 99999

     Country: USA

   • Order Details tab:

     Quantity: 5

     SIM prefix: 1000

     Start SIM: 3000

     IMSI prefix: 1000

     Start IMSI: 4000

     SIM card format: Plug-in

     Transport key: 255

2. Generate the request file.

3. Open the request file in a text editor. The file name is Sam00001.inp.

4. Save the file as Sam00001.out. This file will be the vendor response file.

5. Add the following lines after the last line in the file:

   10004000 10003000 7349 6215 37177972 11267846 83307381 1A73DFCD69F6E11DF3678DC81C9E8057
   10004001 10003001 6604 3374 84688421 63029874 91983041 B6FB4A9029FFB2139A2828CF541A566B
   10004002 10003002 3708 9818 35042443 24656819 46904714 BB5EA7413C9C237DE94ECC6A55ECA7A6
   10004003 10003003 4856 6049 92238513 12035890 92454872 B2888B7F6471501D4AFA1E6D67853581
   10004004 10003004 3315 5878 94466890 55544514 19668055 7EC49FD7144221295F2E1090AD92D623

6. Save the file.

7. Load the response file.

Uninstalling SIM Manager

To uninstall SIM Manager, see "Uninstalling Optional Components" in BRM Installation Guide.