69 Managing Persisted Data in the Oracle Database

Learn about data persistence and the tasks for managing Oracle Communications Billing and Revenue Management Elastic Charging Engine (ECE) data stored in an Oracle database.

Topics in this document:

• About Persisting Data in the Oracle Database

• Accessing ECE Configuration MBeans

• Enabling Multischema Support in the Persistence Database

• About Persisting Rated Events and Customer Data

• About Persisting POIDs

• Enabling ECE Cache Override from Original Source

• Enabling Partition Recovery

• Enabling Partial Loading of Data

• Querying Persistence Database

About Persisting Data in the Oracle Database

ECE persists ECE cache data in the Oracle database (referred to as ECE persistence database) to create a permanent backup of the cache data (in-memory data). ECE recovers data automatically from the persistence database in case of a node failure or partition loss.

You enable data persistence and create the schema and tablespaces for storing the ECE data during the ECE installation or upgrade process.

Note:

If you are enabling data persistence, Oracle NoSQL Database is not required. Rated events are directly persisted in the ECE persistence database.

When data persistence is enabled, the parameters for connecting to the persistence database are set by default in the OraclePersistenceConnectionConfiguration section of the ECE_home/config/management/charging-settings.xml file (where ECE_home is the directory in which ECE is installed). You can reset these parameters based on your business requirements by editing the charging.connectionConfigurations.Connection_Name MBean attributes using a JMX editor, where Connection_Name is the name of the persistence database connection such as oraclePersistence1.

When you start the ECE core components, such as Customer Updater, Pricing Updater, and configLoader, the data published from BRM, PDC, and the mediation specification data loaded into the ECE cache are stored in the persistence database by default.

Data that is synchronized from BRM is stored in the persistence database. Other data, such as balance, topup history, recurring bundle history, rated events, and Portal object IDs (POIDs), are also stored in the persistence database.

Active sessions in ECE are not persisted. If ECE restarts or partition loss occurs, active session cache data is lost. The corresponding expired balance reservations are cleaned up so that reserved balances can be used for future usage requests.

Accessing ECE Configuration MBeans

For all configurations, start by accessing the ECE configuration MBeans:

1. Log on to the driver machine.
2. Start the ECE charging servers (if they are not started).
3. Connect to the ECE charging server node enabled for JMX management.

   This is the charging server node set to start CohMgt = true in the ECE_home/config/eceTopology.conf file, where ECE_home is the directory in which ECE is installed.

4. Start a JMX editor that enables you to edit MBean attributes, such as JConsole.
5. In the editor's MBean hierarchy, find the ECE configuration MBeans.

Enabling Multischema Support in the Persistence Database

By default, the ECE persistence database supports only one schema, but you can configure it to support multiple schemas to distribute the database load. When deploying ECE as multischema, the number of schemas in BRM and ECE must be the same.

Note:

ECE migration from a single-schema persistence database to a multischema persistence database is not supported through a rolling upgrade. To migrate data from a single schema persistence database to a multischema persistence database, you must clear all data from the ECE schema, do a cold restart, and then reload the data from BRM and PDC.

To enable multischema support in the persistence database:

1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".

2. Expand the ECE Configuration node.

3. Do the following for each secondary schema in your database:

   1. Expand charging.connectionConfigurations.

   2. Expand Operations.

   3. Click addOraclePersistenceConnection.

   4. Set the name attribute to oraclePersistenceN, where N is the number that represents the instance number. For example, oraclePersistence2.

4. Do the following for each schema in your database:

   1. Expand charging.connectionConfigurations.oraclePersistenceN, where N is the number that represents the instance number. For example, oraclePersistence1 or oraclePersistence2.

   2. Expand Attributes.

   3. Set schemaNumber to the schema number, such as 1 for the primary schema, 2 for the second schema, and so on.

5. Expand charging.cachePersistenceConfigurations.Cluster_Name, where ClusterName is the name of the ECE cluster that you want to update.

6. Expand Attributes.

7. Set persistenceConnectionName to include the name of each persistence connection, delimited by colons and arranged in ascending schema number order. For example, if your database contains three schemas, you would set it to oraclePersistence1:oraclePersistence2:oraclePersistence3.

About Persisting Rated Events and Customer Data

Rated events are loaded directly into the persistence database and initial customer data is loaded into the ECE cache and persisted in the persistence database.

To extract rated events and customer data updates, configure your Rated Event Formatter and Customer Updater instances to connect to the persistence database.

Configuring Rated Event Formatter and Customer Updater to Connect to the Database

To configure the Rated Event Formatter (RE Formatter) and Customer Updater instances to connect to the persistence database for storing the rated events and customer data, you must perform this for each RE Formatter and Customer Updater instance. For more information about configuring the RE Formatter, see "Configuring RE Formatter" in Loading Rated Events.

To connect a Rated Event Formatter instance to the persistence database:

1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".

2. Expand the ECE Configuration node.

3. Expand charging.ratedEventFormatters.Instance_Name, where Instance_Name is the name of the instance you want to configure, for example, ratedEventFormatter2.
4. Expand Attributes.
5. Set the connectionName attribute to the persistence database connection name, for example, oraclePersistence1.
6. Under the ECE Configuration node, expand charging.CustomerUpdaters.Instance_Name, where Instance_Name is the name of the instance you want to configure, for example, customerUpdater2.
7. Expand Attributes.
8. Set the connectionName attribute to the persistence database connection name, for example, oraclePersistence1.
9. Go to the ECE_home/bin directory.
10. Start ECC:

    ./ecc

11. Restart any Rated Event Formatter and Customer Updater instances that you configured. See "Starting ECE".

About Persisting POIDs

For tracking the bill items created in ECE, ECE persists the POID pool received from BRM in the persistence database. Even after ECE restarts, the reserved POID pool is retained in ECE and the POID allocation is continued without interruption.

You configure the frequency at which ECE persists POIDs in the persistence database and the count after which the POIDs are persisted by using the poidPersistenceSafecount attribute. By default, this attribute is set to 12000, but you can reset it to meet your business requirements.

To update the count for persisting POIDs:

1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".

2. Expand the ECE Configuration node.

3. Expand charging.itemAssignmentConfig.

4. Expand Attributes.

5. Set the poidPersistenceSafecount attribute as needed.

Enabling ECE Cache Override from Original Source

After initial loading of data, when you restart the core components, the data in the persistence database are reloaded into the ECE cache by default. If you want the data to be reloaded directly from BRM, PDC, or any files into the ECE cache, you must configure ECE to override the cache data from the original source before restarting the core components.

You can also reload the customer data incrementally from BRM into ECE if required. For more information, see "Loading Customer Data Incrementally with customerLoader".

To enable ECE cache override from the original source:

1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".

2. Expand the ECE Configuration node.

3. Expand charging.cachePersistenceConfigurations.Cluster_Name, where Cluster_Name is the name of the ECE cluster you want to update such as BRM.

4. Expand Attributes.

5. Set the following attributes as appropriate:

   • configLoadFromPersistence: Set this attribute to false to load data from files, BRM, and PDC at the time of restart.

     Setting this attribute to false sets the pricingLoadFromPersistence and customerLoadFromPersistence attributes to false.

   • pricingLoadFromPersistence: Set this attribute to false to load data from PDC at the time of restart.

   • customerLoadFromPersistence: Set this attribute to false to load data from BRM at the time of restart.

Enabling Partition Recovery

In case of partition loss or a node failure, you can recover the data from lost partitions by enabling partition recovery. However, ECE cannot recover data from persistence if:

• The number of nodes in the ECE system is less than the number of nodes specified in the DegradedModeThreshold parameter in the ECE_home/config/management/charging-settings.xml file.

• The status of the ECE system is none of the following:

  • USAGE_PROCESSING

  • INCREMENTAL_CONFIG_DATA_LOADING_IN_PROGRESS

  • INCREMENTAL_PRICING_DATA_LOADING_IN_PROGRESS

  • INCREMENTAL_PRODUCT_OFFERING_CROSS_REF_DATA_LOADING_IN_PROGRESS

  • DEGRADED_MODE

• All of the server nodes or all of the nodes in ECE are shutdown by running the stop server or stop command.

To enable partition recovery:

1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".

2. Expand the ECE Configuration node.

3. Expand charging.cachePersistenceConfigurations.Cluster_Name, where Cluster_Name is the name of the ECE cluster you want to update; for example, BRM.

4. Expand Attributes.

5. Set the partitionLossRecoverFromPersistence to true to recover the data from lost partitions.

Enabling Partial Loading of Data

You can enable partial loading of data, such as customer data, into the ECE cache by setting the following for each charging server node in your server:

• The maximum limit, such as HighUnits, for loading the data into ECE cache.

• The minimum limit, such as LowUnits, for loading or reloading data into ECE cache from the persistence database.

When partial loading is enabled, the initial data load includes only specific data units. When processing usage requests for a customer, if the required data is not available in ECE cache, ECE loads that data into ECE cache from the persistence database and evicts some other data from ECE cache. This ensures that the maximum limit is not exceeded. Later, when you restart the ECE system, ECE loads the specified number of most recently used data into the ECE cache. In case of a node failure, ECE ensures high availability by distributing the data in the failed node to other nodes that are up and running.

For example, consider the following scenario:

• There are 1000 customers, and you want to load only 60 percent of your customers' data into ECE cache (that is, data from 600 customers).

• There are three ECE server machines and each machine has two charging server nodes up and running. In total, there are 6 charging server nodes that are available to load data.

In this case, you can set the HighUnits to 150 and LowUnits to 100. When the charging server nodes are started, each node loads data for only 100 customers into ECE cache, which is in total 600 customers data, the minimum limit. The remaining quota (which is 50 per node) is reserved for the data migrated from other nodes in case of machine or node failures. If one of the machines fails, the data from the two charging server nodes in that machine, which is for 200 customers, is distributed evenly to the nodes in the other two machines. This increases the load of each node to 150 units, which is the maximum limit for loading data into ECE cache. In case of ECE restart, each node loads only 100 of the most recently used customer data into ECE cache.

To enable partial loading of data:

1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".

2. Expand the ECE Configuration node.

3. Expand BRMFederatedCache.

4. Expand the cache for which you want to enable partial loading such as Customer.

5. Expand back.

6. Expand Attributes.

7. Specify the following values:

   • HighUnits: Specify the maximum units (for each node) of data that can be stored in ECE cache.

     To enable partial loading, specify a positive numerical value. Setting this zero (0) specifies to store all data in the cache.

   • LowUnits: Specify the minimum number of records (for each node) to be loaded into the cache at the time of initial loading or ECE restart. This value must be less than the HighUnits value.

     If this entry is set to zero (0) and HighUnits is set to a non-zero value, 80 percent of the HighUnits value is considered for reloading the data.

Querying Persistence Database

To query the persistence database, run the following command:

./query.sh -p

For example, you can use this utility to verify if the data is loaded from persistence or the original source.

See "query" in BRM Implementing Charging for more information.