1. Managing Customers
  2. Sending Messages to Customers
  3. Sending Messages to Customers through External Notification Applications

13 Sending Messages to Customers through External Notification Applications

Learn how to set up Oracle Communications Billing and Revenue Management (BRM) to send messages to your customers through an external notification application such as Oracle Communications Convergent Charging Controller.

Topics in this document:

Note:

To be able to send messages to your customers, BRM must be integrated with an external notification application through an Apache Kafka Server. For more information, see "About Integrating BRM with an Apache Kafka Server" in BRM Developer's Guide.

About Sending Messages to Customers through External Notification Applications

You can set up your system to send messages to your customers through an external notification application, such as Oracle Communications Convergent Charging Controller, when triggering events occur in BRM. For example, Convergent Charging Controller could send messages to your customers when they create an account, purchase a product, or cancel a subscription in BRM.

To do so, you configure BRM to send notifications containing details about the triggering event and the message to your external notification application. Your external notification application can use this information to send messages to your customers via email, text, or interactive voice response (IVR).

To set up BRM to send notifications to an external notification application, you configure the following:

  • The types of events that trigger messages to be sent to your customers, such as product purchases.

  • Which accounts can receive each type of message. For example, which accounts can receive account creation messages or which accounts can receive product purchase messages.

  • When to send messages to your customers, such as immediately or at 15:00.

  • How to send messages to your customers, such as through email or text messages.

  • Whether to send messages several hours, days, weeks, or months before or after an event occurs in BRM. For example, you could send a reminder message to customers that their bill is due in four days or that their bill is one week past due.

  • Whether customers are automatically opted in to receive a specific notification message type.

  • Whether to enrich messages with your customers' preferences, such as their preferred language.

About the Types of BRM Events that Trigger Notifications

BRM sends notifications to your external notification applications when the following triggering events occur in BRM:

  • Customer-created and BRM-initiated events that impact a customer's account immediately. For example, a customer creates an account, a customer purchases a product, BRM successfully processes a payment, or BRM issues a refund.

  • Events that will impact a customer's account in the future, such as a bill becoming due. When configured to do so, BRM searches for the following types of events and generates a notification a specified amount of time before the event occurs:

    • A customer's balance is about to expire.

    • A customer's bill is almost due.

    • A collections action is about to be performed against a customer.

    • A customer's installment payment is almost due.

    • A customer's subscription is about to expire.

    • A customer's subscription is almost due for renewal.

    • A customer's service lifecycle state is about to change.

    • A custom event is almost due.

  • Events that impacted a customer's account in the past and haven't been resolved, such as a bill being past due. When configured to do so, BRM searches for the following types of events and generates a notification a specified amount of time after the event occurs:

    • A customer's balance expired, and new funds still need to be added.

    • A customer's bill is past due.

    • A collections action was performed, but the customer has yet to respond.

    • A customer's installment payment is past due.

    • A customer's subscription has expired and hasn't been renewed.

    • A customer's subscription is past the renewal date and has yet to be renewed.

    • A customer's service lifecycle state was changed.

    • A custom event has expired and still needs to be resolved.

You specify the types of BRM events that can trigger notifications to be sent to your customers by editing the BRM_home/sys/data/config/payloadconfig_kafka_sync.xml and BRM_home/sys/data/config/pin_notify_kafka_sync files. For more information, see "Configuring BRM to Publish Notifications to Kafka Servers" in BRM Developer's Guide for more information.

You specify which accounts can receive each notification type when you create notification specifications. See "Creating Notification Specifications".

About Message Delivery Times

You specify when to deliver messages to your customers by configuring the settings shown in Table 13-1.

Table 13-1 Delivery Time Configuration

Setting Description

Preferred Time

The preferred time is unique to each account and is specified in 24-hour format, such as 08:00, 14:00, or 16:30. Your CSRs collect a customer's preferred time when they create or modify an account in Billing Care or a custom client application.

A customer's preferred time is defined in an account's subscriber preferences. See "Defining Subscriber Preferences".

Scheduled Time

A scheduled time applies to a group of accounts that meet your criteria. BRM uses it only if an account does not have a preferred time. The scheduled time can be set to one of the following:

  • Real Time: Messages are sent immediately.

  • Predefined Time: Messages are sent at a specified time, such as at 15:00.

  • Fixed Time In-Advance: Messages are sent at a specified time, several minutes, hours, days, weeks, or months before a triggering event occurs. For example, at 12:00, one week before a bill is due.

  • Fixed Time After Due Date: Messages are sent at a specified time, several minutes, hours, days, weeks, or months after a triggering event occurs. For example, at 13:00, five days after an unpaid bill was due.

Note: For Fixed Time In-Advance and Fixed Time After Due Date, you can specify only to enforce the systemwide silent period. This means that messages are sent immediately unless they occur during the silent period. For example, assume that the silent period is 23:00 – 08:00. If a triggering event occurs at 04:00, the message would be sent at 08:01 (after the silent period ends). If the triggering event occurs at 11:00, the message would be sent at 11:00.

You define scheduled times by creating notification specifications in Billing Care or a custom client application. See "Creating Notification Specifications".

Allowable Delay

An allowable delay specifies that messages can still be delivered to your customers a few minutes or hours after their preferred time or scheduled time.

For example, assume a customer's preferred time is 15:00, and the allowable delay is 45 minutes. In this case, messages can be sent to the customer between 15:00 and 15:45.

You configure the allowable delay by using a business parameter. See "Setting Systemwide Values for Notifications".

Silent Period

A systemwide silent period, such as 24:00 – 06:00, during which messages cannot be sent to your customers. Messages scheduled for the silent period are sent after the silent period ends.

Note: Silent periods are used when a preferred time and scheduled time are not defined. They can also be enforced by the fixed time in advance and fixed time after due date options (when configured to do so).

You configure the systemwide silent period by using a business parameter. See "Setting Systemwide Values for Notifications".

Silent Days

Silent days are dates, such as 1 January 2030, when messages cannot be sent to your customers. Messages scheduled for silent days are sent on the next available non-silent day.

Note: Silent days are enforced for only the predefined time, fixed time in advance, and fixed time after due date options. They are ignored for the preferred time and real-time options.

You configure the systemwide silent days by using a business parameter. See "Configuring Silent Days".

If you have configured when to deliver messages using all of these methods, BRM determines a message's delivery time using the settings in the following order:

  1. Your customers' preferred time (plus any allowable delay).

  2. The scheduled time (plus any allowable delay). The scheduled time enforces the silent period if configured to do so.

  3. The systemwide silent period.

Table 13-2 shows when messages would be delivered to your customers based on the delivery times configured in the account's subscriber preferences, notification specifications, and business parameters. In this example:

  • All fixed times in advance and fixed times after the due date enforce the systemwide silent period

  • The silent period is from 23:00 through 09:00

  • The allowable delay is one hour

Note:

The message delivery times shown are simplified. The actual delivery times would be later due to the processing time.

Table 13-2 Sample Delivery Times

Triggering Event Time Subscriber's Preferred Time Notification Specification Scheduled Time Message Delivery Time Description

08:30 Monday

08:00

 Predefined Time: 10:00

08:30 Monday

Sent immediately, because the one-hour allowable delay for the subscriber's preferred time means that messages can be sent between 8:00 and 9:00.

09:00 Monday

 07:00 Predefined Time: 10:00

07:00 Tuesday

Sent the next day at the subscriber's preferred time, because messages can only be sent between 07:00 and 08:00.

10:00 Monday

22:00

 Predefined Time: 14:00

22:00 Monday

Sent at the subscriber's preferred time.

08:30 Monday

Not Defined

Predefined Time: 12:00

12:00 Monday

Sent at the predefined time, because the subscriber's preferred time is not set.

06:00 Monday

Not Defined

Real Time

06:00 Monday

Sent immediately after the event occurs. The silent period is ignored, because the real time option doesn't support silent periods.

23:59 Monday

Not Defined

Fixed Time In Advance: Silent Period Enabled

09:01 Tuesday

Sent after the silent period ends.

08:00 Monday

Not Defined

 Fixed Time In Advance: 10:30 10:30 Monday

Sent at the fixed time in advance.
10:00 Monday Not Defined Fixed Time After Due Date: Silent Period Enabled 10:00 Monday Sent immediately after the event occurs, because the triggering event occurred outside of the silent period.

08:10 Monday

Not Defined

Not Defined

09:01 Monday

Sent after the silent period ends.

About Message Delivery Methods

By default, BRM supports the following message delivery methods: email, SMS, and Interactive voice response (IVR). You can also create custom delivery methods. To do so, see "Creating Custom Delivery Methods".

Note:

If your company supports email delivery methods, you must configure Billing Care or your client application to collect your customers' email addresses. Likewise, if your company supports the SMS or IVR delivery methods, you must configure Billing Care or your client application to collect your customers' phone numbers.

You specify how to deliver messages to your customers by configuring the settings shown in Table 13-3. BRM determines the delivery methods for a customer by using the settings in the priority order shown.

Table 13-3 Delivery Method Configuration

Priority Order Setting Description

1

Preferred Delivery Method

The preferred delivery methods are unique to each account. Your CSRs collect customers' preferred delivery methods when they create or modify an account in Billing Care or a custom client application.

A customer's preferred delivery methods are defined in an account's subscriber preferences. See "Defining Subscriber Preferences".

2

System Delivery Method

A system delivery method applies to a group of accounts that meet your criteria and is used only if an account does not have a preferred delivery method associated with it.

You define the system delivery method when you create notification specifications in Billing Care or a custom client application. See "Creating Notification Specifications".

About Generating Notifications In Advance

You generate notifications in advance by running the pin_gen_notifications utility. The utility searches for objects that will expire during a specified time range, such as between 1 May 15:00:00 and 2 May 15:00:00, and then generates a notification event for each object meeting the criteria.

The utility determines the time range to search for by doing the following:

  1. Retrieving a customer's offset value, which specifies how far in advance to generate notifications, from the /config/notification_spec object. For example, the offset value could be 5 hours, 3 days, or 1 week.

  2. Calculating the starting expiration date and time to search for by adding the offset value to today's date and time:

    Starting expiration = Today's date and time + Offset value

    For example, if the utility runs on 10 January at 12:00:00 and the offset is 10 hours, the starting expiration would be 10 January at 22:00:00. If the offset is 7 days, the starting expiration would be 17 January at 12:00:00.

  3. Determining the ending expiration date and time to search for by adding the time range associated with the offset unit to the starting expiration:

    Ending expiration = Starting expiration + Time range

    where Time range is:

    • 1 minute if the offset value is in minutes. For example: 12:00:00 through 12:01:00.

    • 1 hour if the offset value is in hours. For example: 12:00:00 through 13:00:00.

    • 24 hours if the offset value is in days, weeks, months, or years. For example: 10 January at 12:00:00 through 11 January at 12:00:00.

The utility then searches for all objects due or expiring between the starting and ending expiration. For example, if the utility runs on 10 January at 12:00:00 and the offset value is 6 hours, the utility would search for objects that expire between 10 January 18:00:00 and 10 January 19:00:00.

Table 13-4 shows examples of when a notification event would be generated if the pin_gen_notifications utility was run on 1 May at 15:00:00 with the specified offset values.

Table 13-4 Sample Search Dates and Times for In-Advance Times

Offset Value Search Date

30 Minutes

1 May 15:30:00 – 1 May 15:31:00

5 Hours

1 May 20:00:00 – 1 May 21:00:00

3 Days

4 May 15:00:00 – 5 May 15:00:00

5 Days

6 May 15:00:00 – 7 May 15:00:00

1 Week

8 May 15:00:00 – 9 May 15:00:00

1 Month

1 June 15:00:00 – 2 June 15:00:00

10 Minutes (1)

1 May 15:10:00 – Current time

Note:

  1. There is a special case for 10 minutes or less in advance. In this case, the time range is the current time plus the offset value. For example, for 8 minutes in advance, the time range would be the current time until 8 minutes later. Likewise, for 5 minutes in advance, the time range would be the current time until 5 minutes later.

Alternatively, you can use command-line options to specify an expiration time range when pin_gen_notifications searches for objects. See "pin_gen_notifications" for more information.

About Generating Notifications After an Event Occurs

You use the pin_gen_notifications utility to generate notifications after an unresolved event occurs, such as after an installment payment is 5 days past due. The utility determines the time range to search for by using the same process as for generating notifications in advance, except it calculates the starting expiration date and time by subtracting the offset value from today's date and time:

Starting expiration = Today's date and time – Offset value

For example, if the utility runs on 10 January at 14:00 and the offset value is 4 days, the utility would search for objects that expired between 6 January 14:00 and 7 January 14:00. If the offset value is 1 week, the utility would search for objects that expired between 3 January 12:00:00 and 4 January 12:00:00.

Table 13-5 shows examples of when a notification event would be generated if the pin_gen_notifications utility was run on 1 May at 15:00:00 with the specified offset values.

Table 13-5 Sample Search Dates and Times for After Events Occur

Offset Value Search Date and Time

45 Minutes

1 May 14:15:00 – 1 May 14:16:00

8 Hours

1 May 07:00:00 – 1 May 08:00:00

5 Days

26 April 15:00:00 – 27 April 15:00:00

2 Weeks

17 April 15:00:00 – 18 April 15:00:00

1 Month

1 April 15:00:00 – 1 April 15:00:00

10 Minutes (1)

1 May 14:50:00 – 1 May 15:00:00

Note:

  1. There is a special case for 10 minutes or less. In this case, the time range is when the utility was run minus the offset value. For example, for 8 minutes, the time range would be from when the utility was run until 8 minutes before. Likewise, for 5 minutes, the time range would be when the utility was run until 5 minutes before.

Alternatively, you can use command-line options to specify an expiration time range when pin_gen_notifications searches for objects. See "pin_gen_notifications" for more information.

About Events Occurring Outside of Delivery Times

Sometimes, triggering events occur when messages cannot be sent to your customers. For example, a customer's subscription is canceled at noon, but the customer's preferred delivery time is 10:00.

In these situations, BRM does not generate a notification for the triggering event. Instead, BRM creates a /schedule/notification object that specifies the type of notification to generate, the date and time to generate it, and the account to generate it for.

To generate notifications for these /schedule/notification objects, you must run the pin_deferred_act utility frequently. When the utility is run, it finds all /schedule/notification objects with a delivery time (plus any allowable delay) that matches the current time and then generates the specified notifications. For information about the utility, see "pin_deferred_act".

For example, John Baker creates an account on Monday at 14:00. Because his preferred delivery time is 09:00, BRM creates /schedule/notification object 12345 that specifies to generate an /event/notification/account/create notification on Tuesday at 09:00 for John Baker. When pin_deferred_act is run on Tuesday at 09:00, it finds /schedule/notification object 12345 and generates the /event/notification/account/create notification.

About Enriching Notifications with Additional Information

BRM adds the notification type and message body to all notifications. However, you can have BRM add more information to notifications before they are sent to your external notification application by enabling notification enrichment. See "Enabling Notification Enrichment".

When enrichment is enabled, BRM also adds the following information to notifications:

  • The preferred language for messages, such as English

  • The message delivery method, such as SMS, Email, or IVR

  • The phone number to use for SMS and IVR messages

You can also have custom information added to notifications during the enrichment process. To do so, you must specify the fields to add to notifications using a business parameter. See "Adding Custom Fields during Enrichment".

Note:

If your system supports the Email delivery method, you must configure BRM to add a customer's email address during the enrichment process.

The following shows a sample outgoing notification for a customer whose balance of 200 MB is about to expire. The non-bold fields contain the message type and message body, and the bold fields are added to the notification during the enrichment process.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Notification version="1.0.0.0.0">
    <BalanceExpiryNotification>
        <NotificationType>BALANCE_EXPIRY_NOTIFICATION_EVENT</NotificationType>
        <PublicUserIdentity>0049100073</PublicUserIdentity>
        <Balances>
            <ResourceId>1000009</ResourceId>
            <ResourceSymbol>Mbu</ResourceSymbol>
            <ResourceName>MB Used</ResourceName>
            <ValidTo>1588291200</ValidTo>
            <CurrentBalanceQuantity>200</CurrentBalanceQuantity>
            <RecId>0</RecId>
        </Balances>
        <BalGrpObj>0.0.0.1 /balance_group 134546 0</BalGrpObj>
        <ServiceObj>0.0.0.1 /service 134546 0</ServiceObj>
        <AccountObj>0.0.0.1 /account 134546 0</AccountObj>
        <SubscriberPreferences>
            <SubscriberPreferencesInfo>
                <PreferenceName>Language</PreferenceName>
                <PreferenceValue>English</PreferenceValue>
            </SubscriberPreferencesInfo>
            <SubscriberPreferencesInfo>
                <PreferenceName>Channel</PreferenceName>
                <PreferenceValue>SMS,IVR,EMAIL:abcd@example.com</PreferenceValue>
            </SubscriberPreferencesInfo>
            <SubscriberPreferencesInfo>
                <PreferenceName>Customer Level</PreferenceName>
                <PreferenceValue>Gold</PreferenceValue>
            </SubscriberPreferencesInfo>
        </SubscriberPreferences>
    </BalanceExpiryNotification>
</Notification>

In this example, the information added during the enrichment process specifies:

  • Language: English

  • Channel: SMS, IVR, and Email (to abcd@example.com)

  • PublishUserIdentity: Phone number for SMS and IVR is 0049100073

  • Customer Level: Gold

During enrichment, BRM populates the fields in the notification from an account's subscriber preferences, which are stored in /profile/subscriber_preferences objects. If no subscriber preferences exist for an account, BRM populates the fields from your notification specifications, which are stored in a /config/notification_spec object.

Note:

If a phone number is not provided in an account's subscriber preferences, BRM populates the <PublicUserIdentity> field using the information from a CM pin.conf entry. See "Enabling Notification Enrichment".

Configuring BRM to Send Notifications to External Notification Applications

To configure BRM to send notifications to your external notification applications:

  1. Specify which products, subscriptions, and balances can trigger notifications in advance or after an event occurs when you define balance elements and products in Pricing Design Center (PDC):

    Note:

    BRM automatically generates notifications for bills that are almost due.

  2. Add subscriber preferences to your customers' accounts. See "Defining Subscriber Preferences".

  3. Create notification specifications. See "Creating Notification Specifications".

  4. (Optional) Specify the days of the year not to send messages to customers. See "Configuring Silent Days".

  5. (Optional) Specify systemwide settings, including the silent period, the acceptable delay time, and the notification calendar for silent days. See "Setting Systemwide Values for Notifications".

  6. (Optional) Create any custom delivery methods for your customers. See "Creating Custom Delivery Methods".

  7. (Optional) Enable notification enrichment. See "Enabling Notification Enrichment".

  8. (Optional) Specify any custom information to add during the notification enrichment process. See "Adding Custom Fields during Enrichment".

  9. Integrate BRM with an external notification application through a Kafka Server. See "Integrating BRM with External Notification Applications".

  10. To generate notifications for events occurring in the future or the past, run the pin_gen_notifications utility hourly. See "Running the pin_gen_notifications Utility".

  11. Run the pin_deferred_act utility frequently, such as hourly or every 15 minutes, to generate notifications for events that occurred outside of delivery times. See "pin_deferred_act".

Specifying Which Balance Elements Trigger Notifications

You can configure any currency or noncurrency balance element to trigger notification events when its validity period is about to expire or has expired and new funds haven't been added. For example, a notification event can be triggered three days before a customer's balance of free minutes expires, or one week after a customer's $20 credit has expired.

To do so, specify your expiration preferences when you create a balance element or resource in one of the following ways:

  • Using PDC.

    When creating a balance element in PDC, select Notify Before Expiration. For more information, see "Creating Currency Balance Elements" and "Creating Noncurrency Balance Elements" in PDC Online Help.

  • Using the ImportExportPricing utility.

    For each balance element defined in your import XML file, set the <expiryNotification> element to true to enable notifications, or to false to disable notifications. For example, the following shows how to enable notifications for Australian Dollar balances: 

    <balanceElements>
   <name>Australian Dollar</name>
   <description>Australian Dollar</description>
   <priceListName>Default</priceListName>
   <code>AUD</code>
   <numericCode>36</numericCode>
   <symbol>$</symbol>      
   <expiryNotification>true</expiryNotification>
   ...
</balanceElements>

    For more information, see "Importing and Exporting Pricing and Setup Components" in PDC Creating Product Offerings.

  • Using the load_pin_beid utility.

    For each resource defined in your pin_beid file, set the <ENABLE_EXPIRY_NOTIFICATION> element to 1 to enable notifications, or to 0 to disable notifications. For example, the following shows how to enable notifications for Canadian Dollar balances: 

    <BALANCES elem="124">		
   <APPLY_MODE>1</APPLY_MODE>		
   <BEID_STR_CODE>CAD</BEID_STR_CODE>		
   <CONSUMPTION_RULE>0</CONSUMPTION_RULE>		
   <NAME>Canadian Dollar</NAME>		
   <STATUS>1</STATUS>		
   <SYMBOL>Can$</SYMBOL>
   <ENABLE_EXPIRY_NOTIFICATION>1</ENABLE_EXPIRY_NOTIFICATION>
   ...
</BALANCES>

    For more information, see "load_pin_beid" in BRM Configuring Pipeline Rating and Discounting.

Specifying Which Expiring Products Trigger Notifications

You can configure a subscription to trigger notification events before or after it expires. For example, a notification event can be triggered one week before a customer's one-year mobile telephony subscription expires.

To do so, specify your expiration preferences when you create a charge offer or product in one of the following ways:

  • Using PDC.

    When configuring a charge offer, select Notify subscriber prior to offer expiration. See "Specifying Charge Offer Settings" in PDC Online Help.

  • Using the ImportExportPricing utility.

    For each charge offer defined in your import XML file, set the <expiryNotification> element to true to enable notifications or to false to disable notifications. For example, the following shows how to enable subscription expiration notifications for a sample charge offer: 

    <chargeOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
    <name>Sample Charge Offer</name>
    <pricingProfileName>Product Offering</pricingProfileName>
    <priceListName>Default</priceListName>
    <obsolete>false</obsolete>
    <timeRange>0/inf</timeRange>
    <productSpecName>TelcoGsmTelephony</productSpecName>
    <offerType>SUBSCRIPTION</offerType>
    <priority>1</priority>
    <partial>false</partial>
    <expiryNotification>true</expiryNotification>
</chargeOffering>

    For more information, see "Importing and Exporting Pricing and Setup Components" in PDC Creating Product Offerings.

  • Using the loadpricelist utility.

    For each product defined in your price list file, set the <expiry_notification> element to yes to enable notifications or to no to disable notifications. For example, the following shows how to enable subscription expiration notifications for a sample product: 

    <product type="subscription" partial="no" date_range_impact_type="INSTANTIATED_DATE">
    <product_name>Sample Product</product_name>
    <product_code>code</product_code>
    <priority>1</priority>
    <permitted>/service/telco/gsm/telephony</permitted>
    <expiry_notification>yes</expiry_notification>
</product>

    For more information, see "Using the XML Pricing Interface to Create a Price List" in BRM Configuring Pipeline Rating and Discounting.

Specifying Which Subscription Renewals Trigger Notifications

You can configure a subscription to trigger notification events before or after it is due for renewal. For example, a notification event can be triggered one month before a customer's one-year mobile telephony subscription is due for renewal.

To do so, specify your renewal preferences when you create a charge offer or product in one of the following ways:

  • Using PDC.

    When configuring a charge offer, select Notify subscriber prior to offer renewal. See "Specifying Charge Offer Settings" in PDC Online Help.

  • Using the ImportExportPricing utility.

    For each charge offer defined in your import XML file, set the <subscriptionDueNotification> element to true to enable notifications or to false to disable notifications. For example, the following shows how to enable subscription renewal notifications for a sample charge offer: 

    <chargeOffering xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing">
    <name>Sample Charge Offer</name>
    <pricingProfileName>Product Offering</pricingProfileName>
    <priceListName>Default</priceListName>
    <obsolete>false</obsolete>
    <timeRange>0/inf</timeRange>
    <productSpecName>TelcoGsmTelephony</productSpecName>
    <offerType>SUBSCRIPTION</offerType>
    <priority>1</priority>
    <partial>false</partial>
    <subscriptionDueNotification>true</subscriptionDueNotification> 
</chargeOffering>

    For more information, see "Importing and Exporting Pricing and Setup Components" in PDC Creating Product Offerings.

  • Using the loadpricelist utility.

    For each product defined in your price list file, set the <subscription_due_notification> element to yes to enable notifications or to no to disable notifications. For example, the following shows how to enable subscription expiration notifications for a sample product: 

    <product type="subscription" partial="no" date_range_impact_type="INSTANTIATED_DATE">
    <product_name>Sample Product</product_name>
    <product_code>code</product_code>
    <priority>1</priority>
    <permitted>/service/telco/gsm/telephony</permitted>
    <subscription_due_notification>yes</subscription_due_notification>
</product>

    For more information, see "Using the XML Pricing Interface to Create a Price List" in BRM Configuring Pipeline Rating and Discounting.

Defining Subscriber Preferences

You define your customers' preferences for receiving messages by adding subscriber preferences to their accounts. For example, you could configure BRM to collect the following subscriber preferences:

  • The preferred language for messages, such as English or Spanish

  • The message delivery method, such as SMS, Email, or IVR

  • The preferred time for delivering messages, such as 16:00

  • The phone number for sending SMS and IVR messages

  • The email address for sending email messages

  • Whether to opt out of receiving one or more specific message types

  • Other custom preferences added by your company

For example, a customer could specify to receive messages in French at 15:00 local time through the email address abcd@example.com.

You add subscriber preferences to your customers' accounts by using one of the following:

Configuring Billing Care to Collect Subscriber Preferences

To be able to collect subscriber preferences using Billing Care, you must configure Billing Care to display the Subscriber Preferences dialog box and the fields that you want included in the dialog box. To do so, configure the config_subscriber_preferences_map.xml file and then load its contents into the /config/subscriber_preferences_map object using the load_config utility.

The default config_subscriber_preferences_map.xml file includes sample preferences fields, but you can add, modify, or remove them. Keep the NotificationsOptOutList and NotificationsOptInList preference fields if you want your customers to be able to opt in or out of receiving some message types.

Caution:

If you enabled enrichment, which adds language and channel information to outgoing messages, your file must include entries for Language and Channel. Also include entries for Phone and Email if your system supports the IVR, SMS, and email channels.

To configure Billing Care to collect subscriber preferences:

  1. Open the BRM_home/sys/data/config/config_subscriber_preferences_map.xml file.

  2. In <SUBSCRIBER_PREFERENCES>, define the fields that you want added to the Subscriber Preferences dialog box.

    Table 13-6 describes the elements in <SUBSCRIBER_PREFERENCES>.

    Table 13-6 Subscriber Preferences Elements

    Element Description

    <NAME>

    The name of the preferences field to display in the Billing Care Subscriber Preferences dialog box.

    <SUBSCRIBER_PREFERENCE_ID>

    A user-created ID for this preferences field.

    <STRING_ID>

    Used for localization. Billing Care uses this information to display the localized preference name.

    <STR_VERSION>

    The string field version.

    <DEFAULT>

    The default value for the preference field.

    <TYPE>

    The data type for the preference field value. Possible values include:

    • 1: STR (alphanumeric)

    • 2: INT (integer)

    • 3: ENUM (one of an ordered list of possible values. You must provide an array for this selection.) See the <VALUES> element in this table.

    • 4: DECIMAL

    • 5: TSTAMP (timestamp)

    • 6: TIME (time in 24-hour format HH:mm)

    • 7: MULTI SELECT ENUM (a fixed list that is displayed as a string with check boxes or combo boxes. The list is stored as a string in CSV format.)

    • 262: TIME RANGE (time range in 24-hour format: HH:mm-HH:mm. For example: 16:00-20:00)

    <VALUES>

    An array list of possible values for the field, used only for ENUM types.

    For example, the following entries define a new preference field named Include Current Date with the possible values of True or False (default). 

    <ConfigObject>            
   <DESCR>Subscriber Prefs Map</DESCR>            
   <NAME>Subscriber Prefs Map</NAME>            
   <SUBSCRIBER_PREFERENCES elem="x">              
      <NAME>Include Current Date</NAME>              
      <SUBSCRIBER_PREFERENCE_ID>10</SUBSCRIBER_PREFERENCE_ID>              
      <STRING_ID>10</STRING_ID>              
      <STR_VERSION>1</STR_VERSION>              
      <DEFAULT>909</DEFAULT>              
      <TYPE>3</TYPE>  
         <VALUES elem="0">                        
            <VALUE>True</VALUE>                        
            <STRING_ID>908</STRING_ID>                        
            <STR_VERSION>998</STR_VERSION>                
         </VALUES>                
         <VALUES elem="1">                        
            <VALUE>False</VALUE>                        
            <STRING_ID>909</STRING_ID>                        
            <STR_VERSION>999</STR_VERSION>                
         </VALUES>          
   </SUBSCRIBER_PREFERENCES>
</ConfigObject>

  3. Save config_subscriber_preferences_map.xml.

  4. Load the file into the database by running the load_config utility: 

    load_config config_subscriber_preferences_map.xml

    For more information, see "load_config" in BRM Developer's Guide.

  5. Stop and restart the Connection Manager (CM).

To verify that the updated preference configurations were loaded, you can display the /config/subscriber_preferences_map object by using the Object Browser, or use the robj command with the testnap utility.

For more information about the /config/subscriber_preferences_map object, see BRM Storable Class Reference.

Creating Notification Specifications

You create notification specifications to define which customers can receive a particular message. Each notification specification defines the following:

  • The business event associated with the specification, such as CustCreate, ProductTermination, or BillDue. This indicates whether the message is generated when an account is created, when a product is canceled, when a bill is almost due, or so on.

  • The delivery window, such as within 24 hours after the event occurs, several days before the event occurs, or several days after the event occurs.

  • The specification's validity period, such as from June through December.

  • Whether customers are automatically opted in, by default, to receive this notification message type.

  • The criteria an account must meet to receive the message, such as the customer type, zip code, or payment method.

  • For in-advance and post-expiration notifications, whether to aggregate multiple events for the same notification type into one notification message for the customer.

  • The delivery method, which can be one or more of the following: text, email, or IVR.

  • The scheduled time for delivery, such as immediately, at 14:00, or any time outside of the silent period.

    Note:

    BRM uses the scheduled time and delivery method only when they are not defined in an account's subscriber preferences.

For example, you can specify that account creation messages are sent to Canadian customers via email at 15:00 local time. Likewise, you can specify that bill due messages are sent to all customers via text at noon, five days before the bill is due.

You create notification specifications by using one of the following:

After you create a notification specification, its information is stored in a /config/notification_spec object. BRM can use the information from this object when generating notification events and when enriching messages.

Configuring Billing Care to Display Business Events

You can configure which business events are displayed in the Billing Care Notification screens and can be associated with a notification specification. To do so, you configure an XML file and then load its contents into a /config/business_events object using the load_config_business_event utility.

For more information about the utility, see "load_config_business_event".

To configure Billing Care to display business events:

  1. Create a config_business_events.xml file by running the following command: 

    load_config_business_event -w config_business_events.xml

    The contents from the /config/business_events object are written into the XML file.

  2. Open the XML file in a text editor.

  3. Add an <EVENTS> element for each business event that you want displayed in Billing Care.

    Table 13-7 describes the elements to configure under the <EVENTS> element.

    Table 13-7 Business Event Elements

    Element Description

    <DESCR>

    A brief description of the business event.

    <EVENT_NAME>

    The business event name. This name is displayed in Billing Care.

    For in-advance message delivery times, only these business events are supported:

    • BalanceExpiry
    • ProductExpiry
    • SuscriptionRenewalDue
    • BillDue
    • CollectionsActionDue
    • InstallmentDue
    • ServiceLifeStateChangeExpiry
    • A custom business event
    For post-expiration message delivery times, only these business events are supported:
    • PostBalanceExpiry
    • PostBillDue
    • PostProductExpiry
    • PostSubscriptionRenewalDue
    • PostCollectionsActionDue
    • PostInstallmentDue
    • PostServiceLifeStateChangeExpiry
    • A custom business event

    <EVENT_TYPE>

    Billing Care reads this field to determine which options to display in its Trigger Time list for the business event. The valid values are:

    • IN-ADVANCE: The business event is eligible for only the Fixed Time In Advance trigger time.

    • REGULAR: The business event is eligible for only these trigger times: Predefined Time and Real Time.

    • AFTER-DUE-DATE: The event is eligible for only the Fixed Time After Due Date trigger time.

    <FLAGS>

    Whether this business event can be published to the Kafka Server:

    • 1: Enables the publishing of this business event to the Kafka Server.

    • 0: Prevents this business event from being published to the Kafka Server.

    <NAME>

    A user-friendly name for the business event.

    <STATUS_FLAGS>

    An integer that specifies the external status. This field is not currently supported.

    <NOTIFY_OPCODE>

    The number of the opcode to call for creating the notification event. To find an opcode's number, see the opcode header files in BRM_home/include/ops.

    Note: This field applies to in-advance and after-due-date trigger times only.

    <NOTIFY_SEARCH_LEVEL>

    The search query level for displaying the aggregation mode option in the Billing Care GUI:

    • 1: Self-only level
    • 2: Account level
    • 3: Balance group level
    • 4: Service level
    • 5: Bill unit level

    This field applies only if <EVENT_TYPE> is set to IN-ADVANCE or AFTER-DUE-DATE.

    Note: You configure whether to send aggregated notifications for a specific business event in the notification specification.

    The following shows sample entries for displaying the WelcomeMsg, BalanceExpiry, and PostInstallmentDue business events in Billing Care: 

    <ConfigObject>            
   <POID>0.0.0.1 /config/business_events -1 0</POID>        
   <ACCOUNT_OBJ>0.0.0.1 /account 1 0</ACCOUNT_OBJ>        
   <DESCR>Publishing state (Enable/Disable) of individual business events</DESCR>        
   <HOSTNAME>-</HOSTNAME>        
   <NAME>Business Events</NAME>        
   <PROGRAM_NAME>-</PROGRAM_NAME>        
   <EVENTS elem="0">            
      <DESCR>Welcome Mail</DESCR>            
      <EVENT_NAME>WelcomeMsg</EVENT_NAME>            
      <EVENT_TYPE>REGULAR</EVENT_TYPE>            
      <FLAGS>1</FLAGS>            
      <NAME>Welcome Mail</NAME>            
      <STATUS_FLAGS>0</STATUS_FLAGS>        
      <NOTIFY_OPCODE>1301</NOTIFY_OPCODE>
      <NOTIFY_SEARCH_LEVEL>2</NOTIFY_SEARCH_LEVEL>
   </EVENTS>
   <EVENTS elem="1">                
      <DESCR>Balance Expiration</DESCR>
      <EVENT_NAME>BalanceExpiry</EVENT_NAME>
      <EVENT_TYPE>IN-ADVANCE</EVENT_TYPE>                
      <FLAGS>1</FLAGS>                
      <NAME>BalanceExpiry</NAME>                
      <STATUS_FLAGS>0</STATUS_FLAGS>  
      <NOTIFY_OPCODE>3787</NOTIFY_OPCODE>
      <NOTIFY_SEARCH_LEVEL>2</NOTIFY_SEARCH_LEVEL>      
   </EVENTS>
   <EVENTS elem="2">                
      <DESCR>Installment payment past due</DESCR>
      <EVENT_NAME>PostInstallmentDue</EVENT_NAME>
      <EVENT_TYPE>AFTER-DUE-DATE</EVENT_TYPE>                
      <FLAGS>1</FLAGS>                
      <NAME>Installment payment past due</NAME>                
      <STATUS_FLAGS>0</STATUS_FLAGS>    
      <NOTIFY_OPCODE>3626</NOTIFY_OPCODE>
      <NOTIFY_SEARCH_LEVEL>1</NOTIFY_SEARCH_LEVEL>    
   </EVENTS>
</ConfigObject>

  4. Save config_business_events.xml.

  5. Load the XML file into the database by running this command:

    load_config_business_event -n config_business_events.xml

  6. Stop and restart the Connection Manager (CM).

To verify that the configurations details were loaded, you can display the /config/business_events object by using the Object Browser, or by using the robj command with the testnap utility.

For more information about the /config/business_events object, see BRM Storable Class Reference.

Configuring Silent Days

You can prevent messages from being sent to your customers on certain days of the year. For example, you could prevent messages from being sent on special holidays, such as Diwali or New Year's Day. To do so, you create a notification calendar that lists the dates, such as 1 June 2023 or 4 October 2023, which BRM considers as "silent days".

When a silent day occurs, messages are delayed until the next non-silent day. For example, if 1 January is a silent day, a message scheduled for 1 January at 14:00 would instead be sent on 2 January at 14:00.

Note:

Silent days are enforced for only predefined times, fixed times in advance, and fixed times after due date. They are ignored for preferred times and real times. See "About Message Delivery Times".

You configure silent days by editing the config_silent_days_calendar.xml file and then loading it into the /config/calendar/silent_days object using the load_config utility.

To configure silent days:

  1. Open the BRM_home/sys/data/config/config_silent_days_calendar.xml file.

  2. Edit the file to include one or more calendars.

    Table 13-8 describes the elements in the file.

    Table 13-8 Silent Calendar Day Elements

    Element Description

    <DESCR>

    A brief description of the calendar.

    <NAME>

    The name of the calendar, which must be unique. The default calendar name is NotificationSilentDays.

    You can create one or more calendars. For example, you could create a North American calendar, a European calendar, and so on.

    <CALENDAR_DOM>

    The day of the month. Valid values are 1 through 31.

    <CALENDAR_MOY>

    The number representing the month. Valid values are 1 through 12.

    <CALENDAR_YEAR>

    The calendar year, such as 2023.

    Enter 0 to indicate the current year and every year in the future. For example, a value of 0 could mean 2022, 2023, 2024, 2025, and so on.

    For example, the following entries create a calendar named NotificationSilentDays with the following silent days: 10 August 2023 and every New Year's Day (1 January). 

    <ConfigObject>    
   <DESCR>Default Notification Silent Days</DESCR>    
   <NAME>NotificationSilentDays</NAME>    
   <CALENDAR_DATE elem="1">      
      <!-- Random Holiday -->      
      <CALENDAR_DOM>10</CALENDAR_DOM>      
      <CALENDAR_MOY>8</CALENDAR_MOY>      
      <CALENDAR_YEAR>2023</CALENDAR_YEAR>    
   </CALENDAR_DATE>
   <CALENDAR_DATE elem="2">      
      <!-- New Year's Day -->      
      <CALENDAR_DOM>1</CALENDAR_DOM>      
      <CALENDAR_MOY>1</CALENDAR_MOY>      
      <CALENDAR_YEAR>0</CALENDAR_YEAR>    
   </CALENDAR_DATE>      
</ConfigObject>

  3. Save the config_silent_days_calendar.xml file.

  4. Load the file into the database by running the load_config utility: 

    load_config config_silent_days_calendar.xml

    For more information, see "load_config" in BRM Developer's Guide.

  5. If you have created multiple notification calendars, specify which one BRM should use. See "Setting Systemwide Values for Notifications".

To verify that the calendar days were loaded, you can display the /config/calendar/silent_days object by using the Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Fields" in BRM Developer's Guide.

For more information about the /config/calendar/silent_days object, see BRM Storable Class Reference.

Setting Systemwide Values for Notifications

You can set systemwide values for all notifications generated by BRM. To do so, you use the pin_bus_params utility to change the value of the following System business parameters:

  • NotificationSilentPeriod: Specifies the systemwide silent period during which messages cannot be sent to customers. The default is 21:00 through 07:00.

  • AcceptableDelayTime: Specifies how long after the delivery time that messages can still be delivered to your customers. For example, if a customer's delivery time is 15:00 and the allowable delay is 45 minutes, messages can be delivered to the customer between 15:00 and 15:45. The default is 2 hours.

  • SilentDaysCalendarName: Specifies the name of the notification calendar to be used for Silent Days. The default is NotificationSilentDays.

See "pin_bus_params" in BRM Developer's Guide for information about the utility's syntax and parameters.

To set systemwide values for notifications:

  1. Go to the BRM_home/sys/data/config directory.

  2. Create an XML file from the /config/business_params object: 

    pin_bus_params -r BusParamsSystem bus_params_system.xml

  3. Set the silent period during which messages cannot be sent to your customers:

    <NotificationSilentPeriod>silent</NotificationSilentPeriod>

    where silent is the time span in 24-hour time and HH:mm-HH:mm format. For example, to prevent messages from being sent from 11:00 p.m. to 8:00 a.m., set silent to 23:00-08:00.

  4. Set how long after the delivery time that messages can be sent to your customers: 

    <AcceptableDelayTime>delay</AcceptableDelayTime>

    where delay is the amount of time in HH:mm format. For example, enter 00:45 for 45 minutes, and enter 02:30 for 2 hours and 30 minutes.

  5. Specify the notification calendar to use for determining the silent days:

    <SilentDaysCalendarName>calendar</SilentDaysCalendarName>

    where calendar is the name of the calendar.

  6. Save the file as bus_params_system.xml.

  7. Load the XML file into the BRM database:

    pin_bus_params bus_params_system.xml

  8. Stop and restart the Connection Manager (CM).

Creating Custom Delivery Methods

By default, BRM supports the following message delivery methods: email, SMS, and IVR. You can add custom delivery methods or modify the existing ones. To do so, edit the config_notification_delivery_methods.xml file and then load its contents into the /config/delivery_methods object using the load_config utility.

To create custom delivery methods:

  1. Open the BRM_home/sys/data/config/config_notification_delivery_methods.xml file.

  2. Add or modify delivery methods by using the <DELIVERY_METHODS> element.

    Table 13-9 describes the elements under <DELIVERY_METHODS>.

    Table 13-9 Delivery Method Elements

    Element Description

    <NAME>

    The name of the delivery method.

    <TYPE>

    The type number, which must be unique.

    <DELIVERY_IDENTIFIER_TAG>

    The subscriber preference name where BRM can look up the identifier for the delivery method. For example, where BRM can look up a customer's email address for the email delivery method.

    The subscriber preference name must match a value in the /profile/subscriber_preferences object's PIN_FLD_SUBSCRIBER_PREFERENCES.PIN_FLD_NAME field.

    For example, the following entries create a Twitter delivery method. BRM will look up a customer's Twitter handle under the TwitterHandle preference name of the /profile/subscriber_preferences object: 

    <DELIVERY_METHODS elem="0">                
   <NAME>Twitter</NAME>                
   <TYPE>1</TYPE>		
   <DELIVERY_IDENTIFIER_TAG>TwitterHandle</DELIVERY_IDENTIFIER_TAG>        
</DELIVERY_METHODS>

  3. Save the config_notification_delivery_methods.xml file.

  4. Load the file into the database by running the load_config utility: 

    load_config config_notification_delivery_methods.xml

    For more information, see "load_config" in BRM Developer's Guide.

To verify that the delivery methods were loaded, you can display the /config/delivery_methods object by using the Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Fields" in BRM Developer's Guide.

For more information about the /config/delivery_methods object, see BRM Storable Class Reference.

Adding Rollover Details to Subscription Renewals

You can configure BRM to add rollover details to /event/notification/subscription/renewal notification events before they are sent to the Kafka DM. To do so, you use the pin_bus_params utility to change the value of the ApplyRolloverBeforeCycleFees business parameter.

See "pin_bus_params" in BRM Developer's Guide for information about the utility's syntax and parameters.

To add rollover details to subscription renewals:

  1. Go to the BRM_home/sys/data/config directory.

  2. Create an XML file from the /config/business_params object: 

    pin_bus_params -r BusParamsSubscription bus_params_subscription.xml

  3. Set the <ApplyRolloverBeforeCycleFees> element: 

    <ApplyRolloverBeforeCycleFees>value</ApplyRolloverBeforeCycleFees>

    where value is one of the following:

    • enabled: Rollover details are added to /event/notification/subscription/renewal notification events.

    • disabled: Rollover details are not added. This is the default.

  4. Save the file as bus_params_subscription.xml.

  5. Load the XML file into the BRM database:

    pin_bus_params bus_params_subscription.xml

  6. Stop and restart the Connection Manager (CM).

Enabling Notification Enrichment

You can configure BRM to enrich outgoing notifications by adding or editing the following parameters in your Connection Manager (CM) configuration file (BRM_home/sys/cm/pin.conf):

  • To enable or disable enrichment:

    - fm_publish enable_preferences_enrichment value

    where value is set to 1 to enable enrichment, or to 0 to disable enrichment. The default is 0 (disabled).

  • To allow enrichment for specific publishers:

    - fm_publish prefs_enabled_publisher_list publisher

    where publisher is a comma-separated list of the publisher database numbers for which enrichment is enabled. For example, you would enter 0.0.9.6 for the Kafka DM. This parameter is effective only when enable_preferences_enrichment is set to 1. By default, enrichment is enabled for all publishers.

  • To set where BRM can find an account's phone number when it is not set in an account's subscriber preferences:

    - fm_publish prefs_phone_no_location location

    where location is one of the following values:

    • -1: Retrieves an account's phone number from the /service object's PIN_FLD_LOGIN field.

    • 0 through 4294901760: Retrieves an account's phone number from the /service object's PIN_FLD_NAME field under the PIN_FLD_ALIAS_LIST array. The number entered corresponds to the array index number. For example, 25 specifies to retrieve the account's phone number from ARRAY [25].

Restart the CM for the changes to take effect.

Adding Custom Fields during Enrichment

When notification enrichment is enabled, BRM enriches outgoing notifications with the following information:

  • Preferred language

  • Channel

  • Phone number (for SMS and IVR messages only)

You can configure BRM to add custom information during the enrichment process, such as a customer's email address and streaming threshold. To do so, specify the custom fields to add to the notification by using the NotificationSubscriberPreferences business parameter.

Note:

If the email channel is supported, you must configure BRM to add a customer's email address during enrichment.

To specify the custom information to add to outgoing notifications:

  1. Go to the BRM_home/sys/data/config directory.

  2. Create an XML file from the /config/business_params object: 

    pin_bus_params -r BusParamsSystem bus_params_system.xml

  3. Set the list of fields to add to outgoing notifications:

    <NotificationSubscriberPreferences>preference</NotificationSubscriberPreferences>

    where preference is a comma-separated list of field names from the /profile/subscriber_preferences object. For example, to add a customer's phone number, email address, and streaming threshold, you could enter the following: 

    <NotificationSubscriberPreferences>Phone,Email,Streaming Threshold</NotificationSubscriberPreferences>

    By default, this field is empty. If this field is missing or empty, BRM adds only the preferred language, channel, and phone number (for SMS and IVR) to outgoing notification messages.

  4. Save the file as bus_params_system.xml.

  5. Load the XML file into the BRM database:

    pin_bus_params bus_params_system.xml

  6. Stop and restart the Connection Manager (CM).

Integrating BRM with External Notification Applications

To be able to send messages to your customers, you must integrate BRM with an external notification application through an Apache Kafka Server. During the integration process, ensure that you configure:

  • The pin_notify_kafka_sync file to include the notifications that your company supports.

  • The payloadconfig_kafka_sync.xml file to include only the business events that you want to send to your end customers through the external notification application.

  • The dm_kafka_config.xml file to map each business event included in your notification specifications to a Kafka topic.

    If your external notification application is Oracle Communications Convergent Charging Controller, create Kafka topics with the <TopicDefinition> element's format set to XML, and style set to OC3CNotification. For example: 

    <TopicDefinition name="NotificationTopic" format="XML" style="OC3CNotification"/>
   <PayloadName>BillDue</PayloadName>
</TopicDefinition>

For more information, see "About Integrating BRM with an Apache Kafka Server" in BRM Developer's Guide.

Running the pin_gen_notifications Utility

To generate notifications for objects expiring in the future, run the following command:

pin_gen_notifications parameter [-search_level self|account|bal_grp|service|billinfo]

To generate notifications for objects that have already expired, run the following command:

pin_gen_notifications parameter -after_expiry [-search_level self|account|bal_grp|service|billinfo]

where parameter is one of the following:

  • -balance_expiry: Balance that will expire

  • -product_expiry: Products that will expire

  • -subscription_renewal_due: Subscriptions that are due for renewal

  • -bill_due: Bills that are due

  • -installment due_date|end_date: Installment payments that are due or about to end

  • -svc_lifestate_change: Service lifecycle states that will change

  • -collections_action [action]: Collections actions that are due

    If you run -collections_action without the action option, the utility generates notification events for all types of collections actions.

    You can include the action option to generate notification events for just one type of collections action, such as closing a bill unit or collecting a payment.

Note:

Include the -search_level parameter to consolidate multiple events that expire at the same time into a single notification that is sent to your external notification application. The external notification application can then send information about multiple expiring events in one reminder message to your customers.

For example, if you run the following command on 10 July and the in-advance time is 3 days, the utility generates notifications for all subscriptions that are due for renewal on 13 July:

pin_gen_notifications -subscription_renewal_due

Alternatively, you can specify to search for objects that expire between dates and times that you specify. To do so, include the -start timestamp and -end timestamp parameters at the command line, replacing timestamp with the date and time in the format mm/dd/yyyy-HH:mm:ss, such as 12/23/2023-18:22:45. The start and end times are inclusive and can represent times in the future or in the past. 

pin_gen_notifications -bill_due -start timestamp -end timestamp

You can also generate notifications for POIDs listed in a file that expire in a specified amount of time from today. To do so, include the -file filename parameter, replacing filename with the name and location of the file: 

pin_gen_notifications -bill_due -file filename

For information about the content and syntax of filename, see "Creating a File of POIDs".

For more information about the utility's syntax and parameters, see "pin_gen_notifications".

Creating a File of POIDs

When running the pin_gen_notifications utility, you can specify to search through a list of object POIDs in a file for objects that are about to expire or have already expired. To do so, create a file in pin_flist_format that includes the following fields:

  • PIN_FLD_POID set to the type of object to search for

  • PIN_FLD_RESULTS array, with the following fields:

    • PIN_FLD_POID set to the POID of the /bill, /balance_group, /service, /purchased_product, /collections_action, /installment_schedule, or /service object to search for

    • PIN_FLD_ACCOUNT_OBJ set to the POID of the /account object to send the message to

The following sections show sample content for each type of notification.

Sample Product Expiration File

The following shows sample file content for product expiration notifications:

0 PIN_FLD_POID               POID [0] 0.0.0.1 /service/email -1 0
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 1
1       PIN_FLD_POID         POID [0] 0.0.0.1 /service/email 84139 9
1       PIN_FLD_ACCOUNT_OBJ  POID [0] 0.0.0.1 /account 83499 0
0 PIN_FLD_RESULTS           ARRAY [1] allocated 20, used 1
1       PIN_FLD_POID         POID [0] 0.0.0.1 /service/email 107522 9
1       PIN_FLD_ACCOUNT_OBJ  POID [0] 0.0.0.1 /account 106748 0
0 PIN_FLD_RESULTS           ARRAY [2] allocated 20, used 1
1       PIN_FLD_POID         POID [0] 0.0.0.1 /service/email 107522 9
1       PIN_FLD_ACCOUNT_OBJ  POID [0] 0.0.0.1 /account 106748 0

Sample Subscription Renewal File

The following shows sample file content for subscription renewal notifications:

0 PIN_FLD_POID               POID [0] 0.0.0.1 /service/ip -1 0
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 1
1     PIN_FLD_POID           POID [0] 0.0.0.1 /service/ip 84139 9
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 83499 0
0 PIN_FLD_RESULTS           ARRAY [1] allocated 20, used 1
1     PIN_FLD_POID           POID [0] 0.0.0.1 /service/ip 107522 9
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 106748 0

Sample Bill Due File

The following shows sample file content for bill due notifications:

0 PIN_FLD_POID               POID [0] 0.0.0.1 /bill -1 0
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 1
1     PIN_FLD_POID           POID [0] 0.0.0.1 /bill 84139 9
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 83499 0
0 PIN_FLD_RESULTS           ARRAY [1] allocated 20, used 1
1     PIN_FLD_POID           POID [0] 0.0.0.1 /bill 107522 9
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 106748 0

Sample Balance Expiration File

The following shows sample file content for balance expiration notifications:

0 PIN_FLD_POID               POID [0] 0.0.0.1 /balance_group -1 0
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 1
1     PIN_FLD_POID           POID [0] 0.0.0.1 /balance_group 84139 9
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 83499 0
0 PIN_FLD_RESULTS           ARRAY [1] allocated 20, used 1
1     PIN_FLD_POID           POID [0] 0.0.0.1 /balance_group 107522 9
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 106748 0

Sample Collections Action File

The following shows sample file content for collections action notifications:

0 PIN_FLD_POID               POID [0] 0.0.0.1 /collections_action -1 0
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /collections_action/late_fee 135030 8
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130949 0
0 PIN_FLD_RESULTS           ARRAY [1] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /collections_action/late_fee 132750 8
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130459 0
0 PIN_FLD_RESULTS           ARRAY [2] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /collections_action/finance_charge 131830 3
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130949 0
0 PIN_FLD_RESULTS           ARRAY [3] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /collections_action/finance_charge 134542 3
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130459 0

Sample Installment File

The following shows sample file content for installment notifications:

0 PIN_FLD_POID               POID [0] 0.0.0.1 /installment_schedule -1 0
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /installment_schedule 135030 8
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130949 0
0 PIN_FLD_RESULTS           ARRAY [1] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /installment_schedule 132750 8
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130459 0
0 PIN_FLD_RESULTS           ARRAY [2] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /installment_schedule 131830 3
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130949 0
0 PIN_FLD_RESULTS           ARRAY [3] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /installment_schedule 134542 3
1     PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 130459 0

Sample Service Lifecycle State File

The following shows sample file content for service lifecycle state change notifications:

0 PIN_FLD_POID               POID [0] 0.0.0.1 /service/ip -1 0
0 PIN_FLD_RESULTS           ARRAY [0] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /service/ip 3421 6
0 PIN_FLD_RESULTS           ARRAY [1] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /service/ip 5678 6
0 PIN_FLD_RESULTS           ARRAY [2] allocated 20, used 11
1     PIN_FLD_POID           POID [0] 0.0.0.1 /service/ip 8472 6

Adding Custom Business Events for In-Advance and Post-Expiration Notifications

You can configure BRM to send notifications to an external notification application when a custom object is about to expire or is past expiration. For example, you could configure it to send in-advance or post-expiration notifications based on the value of the PIN_FLD_DUE_T field in a custom storable class. To do so, perform the following procedure:

  1. Add the following fields to your custom storable class (named /custom_class_1 in this procedure):

    • PIN_FLD_LAST_NOTIFICATION_T (timestamp): Specifies the last time this object was processed for expiration notifications.

    • PIN_FLD_LAST_NOTIFICATION_OFFSET (string): Specifies the offset the last time this object was processed.

    See "Creating Custom Fields and Storable Classes" in BRM Developer's Guide for information about adding storable class fields.

  2. Create a custom search opcode, such as CUSTOM_PIN_GEN_SEARCH_OPCODE, that does the following:

    • Retrieves the MTA application configuration flist as input.

    • Copies the entire input flist as the output flist.

    • Forms a custom search flist and replaces PIN_FLD_SEARCH_FLIST in the output flist with the custom search flist.

    • Retrieves the business event name from the PIN_FLD_APPLICATION_INFO.PIN_FLD_CMD_LINE_STR input flist field.

    See "Defining New Opcodes" in BRM Developer's Guide for more information.

  3. Create a custom Notification opcode for generating the following custom notification events: /event/notification/custom/custom_class_1/pre_expiry and /event/notification/custom/custom_class_1/post_expiry.

    Customize the opcode to do the following:

    • Search for objects matching the date ranges in the PIN_FLD_VALUE_RANGES input flist array.

    • Check the PIN_FLD_DELIVERY_STATUS and PIN_FLD_WHEN_T input flist fields.

      If PIN_FLD_DELIVERY_STATUS is true and PIN_FLD_WHEN_T is not passed, call the PCM_OP_ACT_USAGE opcode with the PCM_OPFLG_CALC_ONLY flag set.

    • Call the PCM_OP_NOTIFICATION_GET_LAST_NOTIFY_TSTAMP opcode for each qualified candidate to retrieve the value of the PIN_FLD_LAST_NOTFICATION_T and PIN_FLD_LAST_NOTIFICATION_OFFSET fields.

    • Mark the last notification offset timestamp (PIN_FLD_LAST_NOTIFICATION_OFFSET) in each candidate object to prevent it from being picked up again.

    • Create an input and output flist similar to the ones for PCM_OP_BILL_NOTIFY_BILL_DUE and PCM_OP_BAL_NOTIFY_BALANCE_EXPIRY.

  4. (Optional) Configure the Billing Care Notification screens to display your custom business event. To do so, configure the config_business_events.xml file and load it into the database using the load_config_business_event utility.

    See "Configuring Billing Care to Display Business Events".

  5. Configure the pin_gen_notifications utility to call your custom search opcode during the MTA_INIT_SEARCH stage. To do so, use testnap or Developer Center to populate the PIN_FLD_OPCODE_MAP array in the /config/mta object.

    For example, to configure the utility to call the CUSTOM_PIN_GEN_SEARCH_OPCODE at the MTA_INIT_SEARCH stage, you would write the following to the /config/mta object: 

    0 PIN_FLD_POID                  POID [0] 0.0.0.1 /config/mta 203607 0
0 PIN_FLD_CONFIG_MTA           ARRAY [0] allocated 3, used 3
1    PIN_FLD_NAME                STR [0] "pin_gen_notifications"
1    PIN_FLD_OPCODE_MAP        ARRAY [0]
2        PIN_FLD_FUNCTION        STR [0] "MTA_INIT_SEARCH"
2        PIN_FLD_NAME            STR [0] "CUSTOM_PIN_GEN_SEARCH_OPCODE"

    See "Configuring the MTA Policy Opcodes" in BRM Developer's Guide for more information.

  6. Configure the event notification system to send your custom notification events to the Payload Generator EM:

    1. Add the following lines to your BRM_home/sys/data/config/pin_notify_kafka_sync file: 

      1301 0 /event/notification/custom/custom_class_1/pre_expiry
1301 0 /event/notification/custom/custom_class_1/post_expiry

    2. Load the pin_notify_kafka_sync file into the BRM database: 

      load_pin_notify -v pin_notify_kafka_sync

    See "Configuring Event Notification for Kafka Servers" in BRM Developer's Guide for more information.

  7. Configure the Payload Generator EM to build your custom business event (Custom1BusinessEvent) for the Kafka server. To do so, define the Custom1BusinessEvent business event in the BRM_home/sys/eai_js/payloadconfig_kafka_sync.xml file.

    See "Defining Business Events" in BRM Developer's Guide for more information.

  8. Create a notification specification for Custom1BusinessEvent using Billing Care or a custom client application.

    See "Creating Notification Specifications".

  9. Run the pin_gen_notifications utility with the -custom parameter on an hourly basis:

    • For generating in-advance notifications, run this command:

      pin_gen_notifications -custom Custom1BusinessEvent -verbose

    • For generating post-expiration notifications, run this command:

      pin_gen_notifications -custom Custom1BusinessEvent -after_expiry -verbose

    See "pin_gen_notifications" for more information about the utility's syntax and parameters.