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".
In addition to installing the SIM Manager software, you need to configure data 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.You must define and load network elements. (If you already installed Number Manager, you might have already done this.) See "Creating Network Elements".
You must 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".
You must define SIM device and service associations. See "Customizing SIM Card and Service Associations".
You must define SIM card formats. See "Creating SIM Card Formats".
If you pre-provision 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".
You must specify whether to pre-provision SIM cards, and if so, the pre-provisioning service. See "Customizing How to Pre-Provision SIM Cards".
You must 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, you must allow for encrypted fields. (By default, the KI value is encrypted.) See "Supporting Encrypted KI Values with Oracle".
SIM Manager is supported on the HP-UX IA64, Linux, Solaris, and AIX operating systems. For information on disk space requirements for these operating systems, see "Disk Space Requirements" in BRM Installation Guide.
SIM Administration Center is supported on the Windows platform and requires approximately 100 MB of disk space to download, extract, and install the software.
Note:
SIM Administration Center requires the Java Runtime Environment (JRE). It is included in the SIM Administration Center package and is approximately 50 MB. If the JRE was already installed with another BRM client application, it will not be reinstalled.Before installing SIM Manager, you must install:
Third-Party software, which includes the PERL libraries and JRE required for installing BRM components. See "Installing the Third-Party Software" in BRM Installation Guide.
BRM. See "Putting Together Your BRM System" in BRM Installation Guide.
Oracle 10g or Oracle 11g.
Before installing SIM Administration Center, you must install:
BRM. See "Putting Together Your BRM System" in BRM Installation Guide.
(Windows only) An application such as WinZip for extracting compressed files.
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".
Note:
If you have already installed the product, features that are already installed cannot be reinstalled without uninstalling them first. To reinstall a feature, uninstall it and then install it again.To install SIM Manager on UNIX:
Download the software to a temporary directory (temp_dir).
Important:
If you download to a Windows workstation, use FTP to copy the .bin file to a temporary directory on your UNIX server.
You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid ”Out of Memory” error messages in the log file. For information, see "Increasing Heap Size to Avoid 'Out of Memory' Error Messages" in BRM Installation Guide.
Go to the directory where you installed the Third-Party package and source the source.me file.
Caution:
You must source the source.me file to proceed with installation, otherwise ”suitable JVM not found” and other error messages appear.Bash shell:
source source.me.sh
C shell:
source source.me.csh
Go to the temp_dir directory and enter this command:
7.5.0_SIMMgr_platform_opt.bin
where, platform is the operating system name.
Note:
You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.Follow the instructions displayed during installation. The default installation directory for SIM Manager is opt/portal/7.5.
Note:
The installation program does not prompt you for the installation directory if BRM or SIM Manager is already installed on the machine and automatically installs the package at the BRM_Home location.Go to the directory where you installed the SIM Manager package and source the source.me file:
Bash shell:
source source.me.sh
C shell:
source source.me.csh
Go to the BRM_Home/setup directory and run the pin_setup script.
Note:
The pin_setup script starts all required BRM processes.Your SIM Manager installation is now complete.
To install SIM Administration Center on Windows:
Download the SIM Administration Center software from the BRM Software Web site to a temporary directory (temp_dir).
Extract the downloaded .zip file to a temporary directory (temp_dir).
Go to temp_dir and run the setup.exe program. The installation wizard for SIM Administration Center starts.
Answer the prompts in the installation wizard screens.
Your SIM Administration Center installation is now complete.
Important:
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:
If your system has multiple configuration files for event notification, merge them. See "Merging Event Notification Lists" in BRM Developer's Guide.
Ensure that the merged file includes the entire event notification list in the BRM_Home/sys/data/config/pin_notify file.
(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.
(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.
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.
Important:
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.
Important:
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 "Encrypting Fields" in BRM Developer's Guide.Open the Oracle DM configuration file (BRM_Home/sys/dm_oracle/pin.conf).
Uncomment the appropriate line for your operating system:
#- crypt md5| libpin_crypt.extension "Abracadabra dabracaabrA"
where extension is so for Solaris, Linux, and HP-UX IA64; and a for AIX.
Save the file.
Restart the Oracle DM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Important:
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.
Note:
You cannot define network elements by brand; all network elements can be used by any brand.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.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
Caution:
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.Save the pin_network_elements file.
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"
Important:
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.
Note:
You cannot create brand-specific SIM card formats. SIM card formats displayed in SIM Administration Center are available to all brands.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.
When you run the load_localized_strings utility, use this command:
load_localized_strings sim_card_types.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.For information on loading the sim_card_types.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.
For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.
Important:
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".
You can create brand-specific device states. See "Device Management and Brands" in BRM Developer's Guide. However, you need to be careful to create device state mappings that work if you change the brand of a SIM card. For example, if a device is in state 2 in one brand, it is still in that state when you change brands, but state 2 might be defined differently.
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.
If a SIM card has no status displayed in SIM Administration Center, the device states for the SIM card's brand have not been loaded. The brand administrator for the brand in question must do the following:
Load the pin_device_state_sim file for that brand.
Load the sim_device_states.locale file if it changed or was not previously loaded.
Restart the Connection Manager (CM).
Restart the SIM Administration Center.
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.
When you run the load_localized_strings utility, use this command:
load_localized_strings sim_device_states.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.For information on loading the sim_device_states.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.
For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.
Important:
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.
Important:
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
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".
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 (or all SIM cards in a brand) 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.
Important:
The load_pin_sim_config utility needs a configuration file in the directory from which you run the utility. The login that you enter in the configuration file specifies the brand that the SIM card pre-provisioning service applies to. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide and "Running Utilities with a Branded Database" in BRM Managing Customers.To use a different service, you need the POID of a service object created by using your custom service subclass:
(Optional) If you use a custom service, create the service. See "Adding Support for a New Service" in BRM Developer's Guide.
Create a plan that uses the service: for example, /service/telco/gsm/telephony: and create an account using that service. You can use the root account.
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.
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
Save the pin_sim_config file.
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
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.
Important:
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.
Important:
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.
When you run the load_localized_strings utility, use this command:
load_localized_strings order_sim_status.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.For information on loading the order_sim_status.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.
For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.
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 Information You Want to Receive about SIM Cards
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.
Open the SIMAdmin.properties file in the following folder:
C:\Program Files\Common Files\Portal Software
Edit the RequestFileCardsPerBatch entry:
Important:
The value must be a multiple of 50.
RequestFileCardsPerBatch=5000
Save and close the file.
Restart SIM Administration Center.
By default, the maximum quantity of SIM cards in a single order is 499,995,000.
Open the SIMAdmin.properties file in the following folder:
C:\Program Files\Common Files\Portal Software
Edit the MaxOrderQuantity entry:
MaxOrderQuantity=499995000
Save and close the file.
Restart SIM Administration Center.
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:
Open the SIMAdmin.properties file in the following folder:
C:\Program Files\Common Files\Portal Software
Edit the Var_Out entry:
Var_Out=PIN1/PIN2/PUK1/PUK2/ADM1/Ki
Save and close the file.
Restart SIM Administration Center.
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:
Open the SIMAdmin.properties file in the following folder:
C:\Program Files\Common Files\Portal Software
Edit the ResponseContainsCheckDigit entry:
ResponseContainsCheckDigit=false
Save and close the file.
Restart SIM Administration Center.
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.
Open the SIMAdmin.properties file in the following folder:
C:\Program Files\Common Files\Portal Software
Edit the searchStepSize entry:
searchStepSize=100
Save and close the file.
Restart SIM Administration Center.
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.Open the SIMAdmin.properties file in the following folder:
C:\Program Files\Common Files\Portal Software
Edit the maximumStandardLength entry:
maximumStandardLength=true
Save and close the file.
Restart SIM Administration Center.
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:
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
Generate the request file.
Open the request file in a text editor. The file name is Sam00001.inp.
Save the file as Sam00001.out. This file will be the vendor response file.
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
Save the file.
Load the response file.