7 Synchronizing Data Between ECE and the BRM Database

You synchronize data with the Oracle Communications Billing and Revenue Management (BRM) database to ensure that Oracle Communications Elastic Charging Engine (ECE) is rating service usage events with the most current pricing data.

Topics in this document:

• About Synchronizing Data Between BRM and ECE

• Setting Up Synchronization Between BRM and ECE

• How ECE Gets Historical Data from the BRM Database

• Determining the Discount Sharing Group Owner for Rating

About Synchronizing Data Between BRM and ECE

When customer data is updated in the BRM database, the updates must be applied synchronously (in real time) to ECE. For example, when a CSR adds, cancels, or modifies an account or when an adjustment such as a cycle fee is applied to an account balance, that information must be updated in ECE so that ECE can properly rate service usage events.

The Oracle Data Manager (DM) synchronizes customer data between BRM and ECE. The Oracle DM sends customer data in a business event to an Advanced Queuing (AQ) database queue, where ECE Customer Updater retrieves the business event and updates the information in ECE cache, allowing ECE to rate events using the latest customer information. For more information, see "Synchronizing Account Data Between BRM and ECE" in BRM System Administrator's Guide.

You can view or modify the list of BRM business events that are sent to ECE by using the ECE_home/brm_config/payloadconfig_ece_sync.xml file.

Setting Up Synchronization Between BRM and ECE

To set up your system to synchronize customer data between BRM and ECE:

1. Create and configure your AQ database queues. See "Configuring Your AQ Database Queues" in BRM System Administrator's Guide.

2. Configure BRM to send account data updates to ECE in real time. See "Enabling Real-Time Synchronization of BRM and ECE Customer Data Updates".

3. Configure BRM to retrieve real-time balances for a service from ECE. See "Configuring the Connection Manager to Get Real-Time Balances for a Service from ECE".

4. Configure BRM to enable post-commit behavior and tune the timeout used for BRM update requests to reduce the likelihood of inconsistencies between BRM and ECE customer data synchronization. See "Configuring Post-Commit BRM-to-ECE Synchronization Behavior"

Enabling Real-Time Synchronization of BRM and ECE Customer Data Updates

When customer data is updated in the BRM database, the updates must be applied synchronously (in real time).

To enable real-time synchronization of BRM and ECE customer data updates:

1. Open the BRM_home/sys/cm/pin.conf file in a text editor.

2. Add the following entries to the end of the file:

   -cm ece_real_time_sync_db_no 0.0.0.0
   -cm em_group ece PCM_OP_ECE_PUBLISH_EVENT
   -cm em_pointer ece ip emGateway_host emGateway_port

   where:

   • emGateway_host is the name or IP address of the server on which External Manager (EM) Gateway is running.

   • emGateway_port is the number of the port through which EM Gateway connects to the host.

   Note:

   By default, the publisher database number for EM Gateway is 0.0.9.8.

3. If the publisher database number of EM Gateway in your system is not 0.0.0.0, replace it with the correct publisher database number in the following entry:

   -cm ece_real_time_sync_db_no 0.0.9.8

4. Save and close the file.

5. If you changed the EM Gateway publisher database number in your CM pin.conf file, do the following:

   1. Open the BRM_home/sys/eai_js/payloadconfig_ifw_sync.xml file in a text editor (or the merged file if you merged payload configuration files).

   2. Locate the PublisherDefs section.

   3. In the Publisher DB="DB_number" entry, replace DB_number with the publisher database number of your EM Gateway.

6. Save and close the file.

7. If you changed the EM Gateway publisher database number, restart the Payload Generator External Module (also called the Enterprise Application Integration (EAI) Java Server or eai_js).

8. Restart the CM.

Configuring the Connection Manager to Get Real-Time Balances for a Service from ECE

The CM connects to ECE through EM Gateway.

To configure the CM to get real-time balances for a service from ECE:

1. Open the BRM_home/sys/cm/pin.conf file in a text editor.

2. Add the following entry:

   - cm em_group ece_bal PCM_OP_BAL_GET_ECE_BALANCES

3. Set the following entry to match your environment:

   - cm em_pointer ece_bal ip emGateway_host emGateway_port

4. Save and close the file.

5. Stop and restart the CM.

Configuring Post-Commit BRM-to-ECE Synchronization Behavior

In some deployments, BRM completes a transaction successfully while the BRM-to-ECE synchronization for the same transaction fails or times out. This can leave ECE updated while BRM rolls back, or BRM updated while ECE does not receive the update. You can reduce the likelihood of these inconsistencies by enabling the post-commit behavior and tuning the timeout used for BRM update requests.

When you enable the post-commit behavior, ECE commits BRM-synchronized updates only after BRM commits its database transaction. BRM also commits ECE cache updates only after the BRM database commit.

Note:

• If you enable post-commit behavior, plan for a temporary "customer in transaction" lock. Usage requests can fail until BRM completes and the retry limit is reached. The retry count depends on your responseTimeout setting, which is set in the override-values.yaml file for cloud native deployments and the charging-settings.xml file for on-premise deployments.

To configure post-commit behavior and timeouts:

1. Verify that BRM-to-ECE synchronization completes within the configured timeout. Review whether EM Gateway timed out during BRM-to-ECE synchronization (for example, due to slow ECE response or a network disconnect).

2. Set the EM Gateway timeout for BRM update requests. Increase the EM Gateway timeout by setting updateRequestServerTimeout to a value that matches your site load and test results in the override-values.yaml file for cloud native deployments and the charging-settings.xml file for on-premises deployments.

3. Enable post-commit behavior in ECE. Set brmPostCommitEnabled to true in the override-values.yaml file for cloud native deployments and the charging-settings.xml file for on-premises deployments to ensure that ECE commits only after BRM commits.

4. Enable post-commit behavior in BRM. Set ece_post_commit_enabled to 1 in the BRM_home/sys/cm/pin.conf file to ensure that BRM commits ECE cache updates only after the BRM database commit.

About Processing Customer Updates When the ECE Persistence Database Is Unavailable

ECE stores customer data in cache and persists selected cache updates to the ECE persistence database. By default, ECE uses write-through persistence. You can configure ECE to use write-behind persistence so that it can continue processing specified customer update operations during a temporary ECE persistence database outage.

Note:

Write-behind persistence lets ECE complete customer update operations without waiting for the ECE persistence database. It can improve latency and let ECE operate during a temporary database outage. However, if a cache partition is lost before queued updates are written to the database, those updates can be lost and BRM and ECE data can become inconsistent.

When configured to use write-behind persistence, ECE can continue processing the following operations during a temporary ECE persistence database outage:

• Creating subscribers

• Deleting existing subscribers

• Changing IMSIs

Note:

ECE does not support deleting a subscriber that was created while the ECE persistence database was unavailable and whose queued write-behind operations have not yet been persisted. In that scenario, the delete operation might fail.

During customer update processing, ECE assembles product-level, customer-level, and internal balances from cache. To avoid unnecessary access to the persistence database, ECE assembles an internal balance only when it is already in cache. If the internal balance is not in cache, ECE does not retrieve it from the persistence database during the update flow.

ECE uses write-behind persistence for public user identity updates. This prevents public user identity update processing from waiting for the ECE persistence database when the database is temporarily unavailable. When the persistence database becomes available, ECE persists the queued write-behind operations to the database.

Configuring Write-Behind Persistence for Customer Updates

To support customer update processing when the ECE persistence database is temporarily unavailable, configure write-behind persistence for the PublicUserIdentity cache.

Note:

When making the changes in the procedure below, ensure that you add the snippets below into the delivered cache configuration. Do not replace the file's entire contents with these snippets.

To configure write-behind persistence for customer updates:

1. Open the charging-cache-config-persistence.xml file. For cloud native deployments, the ECE Helm chart provides this file through the charging-settings.yaml ConfigMap.

2. In the existing cache-scheme-mapping section, add the following mapping for the PublicUserIdentity cache:

   <cache-mapping>
       <cache-name>PublicUserIdentity</cache-name>
       <scheme-name>near-federated-wb</scheme-name>
       <init-params>
           <init-param>
               <param-name>transient</param-name>
               <param-value>true</param-value>
           </init-param>
           <init-param>
               <param-name>write-delay</param-name>
               <param-value>1s</param-value>
           </init-param>
       </init-params>
   </cache-mapping>
   

3. In the existing caching-schemes section, add the following write-behind federated scheme:

   <federated-scheme>
       <scheme-name>xref-federated-persisted-wb</scheme-name>
       <scheme-ref>xref-federated</scheme-ref>
       <backing-map-scheme>
           <transient>{transient false}</transient>
           <read-write-backing-map-scheme>
               <scheme-ref>rw-persist-wb</scheme-ref>
               <internal-cache-scheme>
                   <local-scheme>
                       <unit-calculator>BINARY</unit-calculator>
                   </local-scheme>
               </internal-cache-scheme>
           </read-write-backing-map-scheme>
       </backing-map-scheme>
   </federated-scheme>
   

4. In the existing caching-schemes section, add the following near-cache scheme:

   <near-scheme>
       <scheme-name>near-federated-wb</scheme-name>
       <front-scheme>
           <local-scheme>
               <eviction-policy>HYBRID</eviction-policy>
               <high-units>20500000</high-units>
           </local-scheme>
       </front-scheme>
       <back-scheme>
           <federated-scheme>
               <scheme-ref>xref-federated-persisted-wb</scheme-ref>
           </federated-scheme>
       </back-scheme>
       <invalidation-strategy>all</invalidation-strategy>
       <autostart>true</autostart>
   </near-scheme>
   

5. Add the following Coherence JVM property:

   -Dcoherence.rwbm.writebehind.remove.default=true

   • For on-premises deployments, add this property to the ECE JVM tuning profile (defaultTuningProfile.properties).

   • For cloud native deployments, add this property to charging.ecs.jvmOpts in the ECE override-values.yaml file for oc-cn-ece-helm-chart, then run a Helm upgrade to apply the change.

6. Restart ECE to apply the configuration changes.

How ECE Gets Historical Data from the BRM Database

Because a gap can occur between usage and rating, customer information can change during that time. ECE might need historical customer information to rate the usage correctly. For example, a customer might change the phone number before a call is rated, in which case ECE must look up the account data associated with the previous phone number.

Historical information is also important when the owner of a discount sharing group changes. When discount sharing group owner determination is enabled, ECE uses sharing agreement ownership information to determine which owner was effective when the usage occurred. This enables ECE to rate delayed or backdated usage against the owner that was effective at the time of the usage. For more information, see "Determining the Discount Sharing Group Owner for Rating".

To retrieve historical information, ECE gets data from audited objects. ECE uses current and audited sharing agreement data when loading customer information so that historical sharing agreement information is available for event-time processing.

By default, BRM auditing is disabled for most objects. After you install the account synchronization components, you must run the object_auditing.pl script to turn on auditing for the objects and fields that ECE requires. See "object_auditing.pl" in BRM System Administrator's Guide.

Determining the Discount Sharing Group Owner for Rating

If a discount sharing group has had an ownership change, ECE determines whether to apply a usage event to the previous owner or the new owner.

By default, the sharingAgreementOwnerResolutionEnabled attribute is set to false. When the attribute is set to false, ECE uses the owner ID stored in the member-side UsedSharingAgreement data to identify the discount sharing group owner.

You can configure ECE to determine the owner based on the effective time of the usage event. When this behavior is enabled, ECE rates usage that occurs before the owner change based on the previous owner and usage that occurs at or after the owner change based on the new owner.

For delayed or backdated usage, ECE uses the owner that was effective when the usage occurred.

For example, if an owner change is effective at 10:30:

• ECE rates usage with an effective time of 10:20 based on the previous owner regardless of whether the usage is received before or after 10:30.

• ECE rates usage with an effective time of 10:30 based on the new owner.

• ECE rates usage with an effective time of 10:40 based on the new owner.

Note:

Before changing the owner of a discount sharing group, terminate all active sessions for group members. ECE does not support sessions that continue across the owner-change time.

To configure how ECE determines the discount sharing group owner for rating, set the sharingAgreementOwnerResolutionEnabled ECE attribute to one of the following in the charging-settings.xml file for on-premises or the override-values.yaml file for cloud native:

• true: ECE determines the owner based on the effective time of the usage event.

• false (default): ECE uses the existing sharing-customer discovery behavior and does not determine the owner based on the effective time of the usage event.

You can configure discount sharing group owner determination in one of two ways:

• At installation or before restart: see "Configuring Discount Sharing Group Owner Determination at Installation or Before Restart".

• During runtime: see "Configuring Discount Sharing Group Owner Determination During Runtime".

Configuring Discount Sharing Group Owner Determination at Installation or Before Restart

You can configure the sharingAgreementOwnerResolutionEnabled attribute during installation by editing the charging-settings.xml file. To do so:

1. Open the ECE_home/config/management/charging-settings.xml file.

2. Set the sharingAgreementOwnerResolutionEnabled attribute to true.

3. Restart ECE. See "Starting and Stopping ECE" in BRM System Administrator’s Guide.

Configuring Discount Sharing Group Owner Determination During Runtime

You can use a JMX editor to configure the sharingAgreementOwnerResolutionEnabled attribute when ECE is running.

To configure the sharingAgreementOwnerResolutionEnabled attribute:

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.server.

4. Expand Attributes and select sharingAgreementOwnerResolutionEnabled.

5. Set the value of the attribute to true.

Note:

Changes to the sharingAgreementOwnerResolutionEnabled attribute take effect for subsequent requests. You do not need to restart ECE. If the owner cache does not contain the required timeline entry, ECE uses the member-side owner ID. Reload or rebuild the cache only to populate missing historical owner data.