2 About Managing Customers

This chapter provides an overview of Oracle Communications Billing and Revenue Management (BRM) customer management.

Caution:

Do not use or modify this product except as explicitly instructed in this documentation. Assumptions should not be made about functionality that is not documented or use of functionality in a manner that is not documented. Use or modification of this software product in any manner or for any purpose other than as expressly set forth in this documentation may result in voidance or forfeiture of your warranties and support services rights. Please consult your software license agreement for more details. If you have any questions regarding an intended use or modification of this product, please contact Oracle.

For more information on customer management procedures, see "Typical Customer Management Tasks".

About Accounts

Each of your customers has an account in the BRM database. BRM accounts include or are linked to information about the customer's name and address, product and services, and current balance.

In addition to customer accounts, the database includes the following special-purpose accounts:

  • The root account is used by system administrators to set permissions for customer service representatives (CSRs).

    Note:

    BRM excludes the root account from billing. Therefore, BRM does not permit the root account to purchase services, deals, or plans for itself.

  • CSR accounts enable CSRs to log in to the BRM system. You also use CSR accounts to track CSR activity. See "Setting Up Permissions in BRM Applications" in BRM System Administrator's Guide.

  • Remittance accounts are used to track commissions for business-to-business relationships. See "Remitting Funds to Third Parties" in BRM Configuring and Running Billing.

  • The verification account is used to track customer login failures. See "Tracking Customer Authentication and Authorization Records".

For more information on creating accounts, see "About Registering Customers".

About Accounts and Services

When a customer purchases a service, BRM keeps a record of the service information for the customer's account in the BRM database. For example, the email service includes information about the customer's login name and password, the maximum message size, and the maximum number of messages allowed in a mailbox.

An account can have multiple services, such as Internet access and email. An account can also have multiple services of the same type, such as multiple email accounts.

You can create customer accounts without charging for any services. For example, you can have customers pay a monthly fee for an account with no services. In that case, a customer can add and cancel services and still be charged a consistent amount just for owning an account.

About Account Balances

Account balances keep track of how much a customer owes, or is credited with, for each resource. For example, if a customer uses products that charge US dollars for Internet access hours, the balances track US dollars and, depending on your price list, might track Internet access hours.

Accounts can have multiple balances, which are stored in a balance group. A balance group contains a collection of sub-balances that are grouped by the type of resource they track. A resource includes more than one sub-balance when portions of the resource are valid at different times. For example, a resource of free minutes might include 300 minutes that are valid only for the current month and 1000 free minutes that never expire.

A balance group can contain any number of currency and non-currency sub-balances. The sub-balance for a currency resource is normally zero or a debit balance, which means the customer owes you. The sub-balance for a non-currency resource is normally zero or a credit balance, which means you owe the customer. A debit sub-balance is represented as a positive number. A credit sub-balance is represented as a negative number.

For example, if a customer pays $10 per month for Internet access and receives 15 free hours per month, the balances at the start of the month are:

  • A currency sub-balance of 10 US dollars

  • A non-currency sub-balance of -15 Internet hours

An account can also have multiple balance groups. Each balance group keeps track of how much a customer owes or is owed for one or more specific services. This means an account can own two services of the same type and each service can have its own credit limit.

For more information on how resources are tracked and updated in account sub-balances, see "About Tracking Resources in Account Sub-Balances" in BRM Setting Up Pricing and Rating.

About Account Locking

Some transactional processes require that an account be locked to maintain data integrity. For these operations, the account is locked and unlocked automatically. When an account is locked, no other opcode can perform operations on the account.

Making Notes about Customers

You can add notes to accounts to record information obtained from customers and to explain why you performed various actions. To do so, see "Creating and Reviewing Notes in Customer Center".

Creating and Reviewing Notes in Customer Center

Customer Center categorizes notes to differentiate them when they are displayed in the Notes dialog box and to enable other tools, such as reporting applications, to gather a specific type of note from your BRM database. Note categories include the following: General Notes, A/R Charge Credit Card, A/R Credit Account, A/R Credit Item, A/R Debit Account, A/R Open Dispute, A/R Set Credit Limit, A/R Settle Dispute, A/R Write-Off, and Account/Service Status Change.

General notes, such as notes about the best time of day to call a customer, apply to the entire account. See "Creating General Account Notes".

Notes in all other categories apply to specific actions, such as adjustments, charges, credits, disputes, credit limit changes, write-offs, and status changes. See "Creating Notes about Specific Actions".

To review existing notes, see "Displaying Notes in Customer Center".

Note:

Text entered in the Comments box of the Account Creation or Purchase wizard is not saved as a note. Instead, it appears in the Comments box in an account's Product Detail panel.

Creating General Account Notes

Notes that apply to the entire account, such as notes about the best time of day to call a customer, are categorized as general notes, as shown in Figure 2-1:

Figure 2-1 Example of a General Note

Description of Figure 2-1 follows
Description of ''Figure 2-1 Example of a General Note''

To review general notes, see "Displaying Notes in Customer Center".

Creating Notes about Specific Actions

Many Customer Center dialog boxes and panels contain a Notes box as shown in Figure 2-2:

Figure 2-2 Note Associated with a Specific Action

Description of Figure 2-2 follows
Description of ''Figure 2-2 Note Associated with a Specific Action''

When you enter text in a Notes box and save your changes, Customer Center creates a note and saves it in an action-specific category. The category is identified when the note is displayed in the Notes dialog box as shown in Figure 2-3:

Figure 2-3 Action-specific Note Stored by Customer Center

Description of Figure 2-3 follows
Description of ''Figure 2-3 Action-specific Note Stored by Customer Center''

The category in which a note is saved depends on the action performed. For example, if the action in Figure 2-3 was a debit instead of a credit, it would be categorized as A/R Debit Account.

To review notes about specific actions, see "Displaying Notes in Customer Center".

Note:

Text entered in the Comments box of the Account Creation wizard or the Purchase wizard is not saved as a note. Instead, it appears in the Comments box in an account's Product Detail panel.

Displaying Notes in Customer Center

Notes can be created in several places in Customer Center. For example, you enter general notes about an account in the Notes dialog box, and you enter notes about credits and debits in the Account Adjustment dialog box.

No matter where notes are created in Customer Center, however, they are all displayed in the same place: the Notes dialog box.

Note:

Text entered in the Comments box of the Account Creation wizard or the Purchase wizard is not saved as a note. Instead, it appears in the Comments box in an account's Product Detail panel.

To display all notes created for an account in Customer Center, see the discussion on displaying notes in the Customer Center Help.

Storing a Summary of Activities Performed on an Account

This section describes how to enable storing a summary of activities performed on an account as News Feed in BRM.

About News Feed

News Feed is a summary of activities performed on an account, which are stored in the BRM database. To store a summary of activities performed on a customer account, enable News Feed for each event you want a summary of. See "Enabling News Feed".

You can enable News Feed for the following events:

  • Accounts receivable (A/R), which includes currency adjustments, noncurrency adjustments, open disputes, closed disputes, refunds, write-offs, and collections.

  • Payments, which includes payments, payment method changes, and payment reversals.

  • Account, which includes name or contact information changes, account status changes, service status changes, and services (for example, a SIM card) attached or detached from the account, and billing information changes.

  • Charges, which includes one-time charges, recurring charges, cycle charges, purchase charges, purchase and cancellation of a plan or deal, bill issued, and bill issued midcycle.

Enabling News Feed

To enable News Feed for an event:

  1. Open the BRM_Home/sys/data/config/pin_notify file in a text editor.

  2. Uncomment the entry for the events for which you want to enable News Feed:

    180  0   event_name

    where event_name is the name of the event for which you want a summary.

    For example:

    180  0    /event/billing/account/adjustment

    This example means that opcode 180 (PCM_OP_ACT_PROCESS_EVENTS) is called when the /event/billing/account/adjustment event occurs.

  3. Save and close the file.

  4. Run the following command, which loads the event notification file into the BRM database:

    load_pin_notify   pin_notify_file

  5. Stop and restart the Connection Manager (CM). See the discussion about starting and stopping the BRM system in BRM System Administrator's Guide.

Loading Localized and Customized Strings for News Feed

The strings for News Feed contain the basic text of a message and include the type of activity performed, such as account, dispute, payment, and so on.

You can customize and localize the strings for News Feed (for example, ”Payment reversed”). To do so, you edit a copy of the BRM_Home/sys/msgs/newsfeed/newsfeed.en_US sample file. If you are loading a localized version of this file, use the correct file extension for your locale. You then use the load_localized_strings utility to load the contents of the file into the /strings objects.

When you run the load_localized_strings utility, use this command:

load_localized_strings newsfeed.locale

For information on loading the newsfeed.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.

Loading Customized Strings for News Feed

To load customized strings for News Feed:

  1. Open the BRM_Home/sys/msgs/newsfeed/newsfeed.locale file in a text editor.

  2. To add new strings for News Feed, add the strings and map them to the reason codes from a list of reasons appropriate to the event type that are defined in the newsfeed.locale configuration file.

    For example:

    DOMAIN = "newsfeed"
STR
        ID = 132 ;
       VERSION = 60 ;
        STRING = "Payment reversed" ;
END
STR
        ID = 133 ;
        VERSION = 60 ;
        STRING = "%s original payment, %s" ;
END

    The PCM_OP_ACT_POL_PROCESS_EVENTS policy opcode is used to customize values in News Feed and to add new events for News Feed. The placeholder character %s is replaced with the value supplied in the PIN_FLD_MESSAGE field in the input flist of PCM_OP_ACT_POL_PROCESS_EVENTS. See "About Customizing News Feed".

  3. To modify existing strings for News Feed, search for the string and change the string value.

  4. Save and close the file.

  5. Load the strings by using the load_localized_strings utility.

About Customizing News Feed

The PCM_OP_ACT_POL_PROCESS_EVENTS policy opcode is used to process the events and updates the database with the corresponding News Feed entries. The PCM_OP_ACT_POL_PROCESS_EVENTS policy opcode is called by the PCM_OP_PROCESS_EVENTS standard opcode.

Use the PCM_OP_ACT_POL_PROCESS_EVENTS policy opcode to customize values in News Feed and to add new events for News Feed.

As input, this opcode takes the following information:

  • PIN_FLD_EVENT: Specifies the events.

  • PIN_FLD_TYPE: Specifies the type of news feed, which differentiates the News Feed category from other News Feeds.

  • PIN_FLD_REASON_ID: Specifies the reason code for News Feed, which links to the localized name of the News Feed category.

  • PIN_FLD_MESSAGE: Specifies the summary information for News Feed. The message has the following format:

    numeric_ID1;;numeric_ID2|~|placeholder_value1|~| placeholder_value2

    where:

    • numeric_IDN is a unique identifier that maps to the reason code in the localization message. You can add multiple numeric IDs separated by ;;.

    • placeholder_valueN is the value that replaces the placeholder character in the localization message for the corresponding numeric ID. The placeholder values are separated by |~|.

    For example:

    132;;133|~|P1-1|~|10003

    which displays the following message:

    Payment reversed
P1-1 original payment, 10003

  • PIN_FLD_FLAGS: Specifies whether to create a /newsfeed object:

    • When set to 1, the opcode creates a /newsfeed object.

    • When set to 0, the opcode does not create a /newsfeed object.

Customizing the List of Reasons for Account Changes

When making changes to accounts, CSRs can choose from a list of reasons for making the change. Figure 2-4 shows how Customer Center displays a list of reasons for inactivating an account:

Figure 2-4 Default Reasons for Account Changes

Description of Figure 2-4 follows
Description of ''Figure 2-4 Default Reasons for Account Changes''

Reasons for changing an account are stored in the BRM database. You can edit the list of reasons for the following changes:

  • Activating or inactivating an account

  • Closing an account

  • Crediting, debiting, or adjusting an account

  • Charging an account

  • Changing credit limits

Customer Center displays the reasons in lists. You can add, edit, or delete the text for these reasons by modifying the reason objects stored in the BRM database.

To modify the reasons file, edit the BRM_Home/sys/msgs/reasoncodes/reasons.en_US sample file, where BRM_Home is the directory in which BRM is installed. You then use the load_localized_strings utility to load the contents of the file into the /strings objects. See "load_localized_strings" in BRM Developer's Guide.

When you run the load_localized_strings utility, use the following command:

load_localized_strings reasons.locale

where locale is the file suffix (for example, en_US). If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.

Caution:

The load_localized_strings utility overwrites existing /config/map_glid and /config/reason_code_scope objects. If you are updating these objects, you cannot load new general ledger (G/L) ID maps and reason code scopes only. You must load complete sets of data each time you run the utility. This is also true when using the /strings object, but only if you specify the -f parameter. Otherwise, the utility appends the new data to the object.

Note:

If you add your own reason codes to the reasons.locale file, use IDs above 100,000.

For more information on loading the reasons.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.

For more information on creating strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.

About Finding Accounts

In Customer Center, the first step in any customer management task is to find the account. To find an account, you search for customers based on one or more account attributes (for example, name, account number, or credit card number, or token if credit card tokenization is enabled. See the description for creating and finding accounts in the Customer Center Help.

How Searching Handles Text Characters

For Latin 1 languages, BRM searches by using a simplified form of any entries in the Name and Company Name boxes. This means that the search ignores capital letters, accents, and diacritical marks in the search box and the account. Latin 1 languages include those of Western Europe, Canada, and the United States.

Customizing Search

You can customize Customer Center search functions.

Finding Customer Accounts Using Opcodes

In addition to using the base search opcodes to find accounts, you can use the PCM_OP_CUST_FIND opcode.

This opcode replaces the PCM_OP_SEARCH and PCM_OP_STEP_SEARCH opcodes. Given an account number, PCM_OP_CUST_FIND finds the /account storable object in question and returns the Portal object ID (POID) of the storable object and any other information that you request. If no results array is specified, the entire contents of the storable object are returned.

You can specify an array of account numbers in an input flist and have an array of results returned.

For more information on these opcodes and the /account storable object, see BRM Developer's Guide.

About Exporting Customer Information to a Non-BRM Database

BRM can automatically export registration information to a database other than the BRM database. You might want to do this to support a legacy system or to collect additional information about customers. (A better way to collect information about customers is by using profiles.)

For more information on exporting registration information, see "Exporting Registration Information to a Non-BRM Database".

Typical Customer Management Tasks

Most customer management tasks are accomplished by using Customer Center.

You can also set up Web-based customer self-administration so that your CSRs can focus on customer problems. See "Ways to Implement a Web Interface".

Typical Customer Problems:

Typical Customer Requests:

  • Change an address or phone number.

  • Change an email address, password, or login name.

  • Add or cancel services.

  • Find out the current balance.

What Your CSRs Need to Know about BRM Customer Management

Customer Center includes online help for accomplishing tasks; however, you need to give your CSRs information that is specific to your business. For example:

  • CSRs need to be able to tell your customers the following information about plans and deals:

    • Which services are included in each plan

    • The sign-up fee, monthly fees, and usage fees

    • Discounts, and when they apply

    • What happens when the plan is canceled; for example, is there a cancellation fee, and are fees paid in advance prorated and reimbursed

    • Expiration dates

  • If CSRs can change service properties, they need to know what changes they are allowed to make; for example, if they can enter blocked numbers for a telephony service.

  • CSRs need to know which information is required for registration. They also need to know the valid formats for entering information; for example, how to enter a telephone number, salutation, or title. For more information, see "Standard Registration Information" and "Specifying How to Validate Customer Contact Information".)

  • Customers often have questions about changes to their account status. CSRs should know the reasons why an account can be inactivated and what needs to be done to activate an inactive account.

About Maintaining an Audit Trail of BRM Activity

BRM provides support for auditing any object class in the BRM database so that a record is kept of every version of the object for future reference. This can be used to track changes to customer profiles, customer payment information, and so on. An audit trail can also be used to track internal changes, such as changes to your price list.

BRM usually determines the fields that must be marked for auditing.

Note:

You can also log CSR activities if you have included them in the pin_notify file. For more information, see "Logging Customer Service Representative Activities" in BRM System Administrator's Guide.

About Using Audit Trails

Enabling an audit trail promotes good customer service. For example, customers can call your CSRs and find out when they changed the credit card number for their accounts. Assuming you are not encrypting credit card numbers, CSRs can also tell customers the credit card number they were using before the change. Another reason to enable an audit trail is to handle customer billing disputes. For example, a CSR can find which pricing plan a customer was signed up for during a certain billing period.

Tip:

Enabling an audit trail decreases system performance significantly. Keep an audit trail only for the BRM activity you feel is absolutely necessary.

About Accessing Audit Trails

To access audit trail information for a customer, you must write an application. Your application would take the pertinent customer account information (such as the customer account number and the general time the audit occurred) and find and retrieve the requested audit trail data.

See the following topics in BRM Developer's Guide:

About Customer Center

Customer Center is a fully customizable Java application that CSRs use to manage interactions with your customers. Customer Center includes the following features:

  • Centralized installation: You deploy Customer Center from a central Web server, making it available to each CSR to download and use locally. Each time a CSR starts Customer Center, the application checks the server and downloads any updates, using Java Web Start technology.

  • Customization: You can add new panels to the Customer Center interface, make certain modifications to existing panels, and customize other aspects of Customer Center by using the Customer Center SDK.

Who Uses Customer Center?

CSRs and accounts receivable (A/R) personnel are the primary Customer Center users. BRM implementers can also use Customer Center as part of testing BRM; for example, checking the balance impacts of price plans.

Customizing Customer Center

One of the advantages of Customer Center and its modular framework is that you can customize it. You can customize Customer Center in the following ways:

  • Rename or remove fields

  • Change its basic look and feel

  • Add functionality, such as entirely new fields or custom services (this type of customization requires programming)

For more information, see "Customizing the Customer Center Interface" in BRM Developer's Guide.

About Using Customer Center

This section shows you the default tabs in Customer Center and explains how you work with account data on each tab.

Note:

You can manage CSR access to Customer Center data and functionality. For more information, see "Setting Up Permissions in BRM Applications" in BRM System Administrator's Guide.

Summary Tab

By default, this tab is active when you first open an account.

This tab gives you an overview of the open account, including the following:

  • Name, address, and other contact information for the account holder

  • Account summary, including the status, creation date, number of deferred actions, customer type, security codes, and if the account was created by the user

  • Current balance

  • Credit limit

  • Number of unresolved disputes

  • Payment method

  • Current billing cycle dates

You can take the following actions by clicking links on the Summary tab:

  • Change the account holder's information or create more contacts for the account

  • Change the status of either the account or any service the account owns

  • Display self-registration information, such as promotional codes, if your customer created the account on the Web

  • Change the account's credit limit

  • Resolve a dispute

  • Change the account's payment method

Balance Tab

This tab displays an overview of the account's balance and bills, including the following:

  • Current balance for the account and for the bill in progress, or the bill for the current billing cycle

  • Credit limit

  • Summary of non-currency resources, if the account uses any

  • List of the account's bills including the payment received for each bill

You can also do the following from this tab, by clicking links and using commands:

  • Adjust the account; for example, to give the customer credit for a service problem

  • Allocate adjustments or payments

  • Display the bill in progress

  • Change the account's credit limit

  • Resolve a dispute

  • View details of a bill

  • View the invoice for a selected bill

  • View A/R actions: adjustments, write-offs, and disputes, for all bills

  • Search for and adjust events associated with a selected bill

  • Write off a bill or an item

  • Adjust an item for a selected bill

  • Adjust an event

  • Open and settle a dispute

  • Refund a bill

Payments Tab

This tab displays the following:

  • A list of payments the account has made and how much of each payment has been allocated

  • Payment setup information, which is different for each payment method

  • Tax setup information

You can also do the following from this tab, by clicking links and using commands:

  • View more details about a payment

  • Search for and display payments for different time periods

  • Allocate an unallocated payment

  • Export the current list of payments to an HTML page

  • Change billing information, including the payment method, name and address, and credit card number

  • Add, delete, or change a tax exemption

  • Export a list of payments to an HTML file

Product Tab

This tab displays each product that the account owns and basic information about each product, including the product's service, purchase date, and status. You can click a product name to see more details, such as the product quantity, discounts, and fees, and to customize the product.

You can also do the following from this tab:

  • Purchase new products

  • Cancel a deal or product

  • Customize the display of products on this tab

  • Review the history of a product, deal, or service

Service Tab

This tab displays the services that the account owns. For each service, it lists the login name or ID, status, and number of deferred actions. Some services may be subscription services or member services.

You can click a service's status to change it. You can change the status of a member service without affecting the other members of a subscription group. If you change the status of a subscription service, the status of its member services changes accordingly.

You can also change the login name or ID for a service and the password, if one is required.

Note:

For some BRM services, additional fields appear below New Password.

View Alias

You can view the available alias or aliases for telco services. An alias is an additional identity associated with a service. For example, a service ID can have aliases such as International Mobile Subscriber Identity (IMSI) and Mobile Subscriber Integrated Services Digital Network Number (MSISDN) associated with it.

You use View Alias from the Actions menu to view the available alias or aliases for the selected telco service.

Note:

View Aliases is available only if the selected service is a telco service. If no aliases are available, the dialog box displays a message to that effect.

Hierarchy Tab

For the parent account or member of an account hierarchy, you can see the accounts belonging to the hierarchy.

You can also do the following from this tab:

  • Move any account into a hierarchy

  • Move an account from one hierarchy to another

  • Move an account to a different position within the same hierarchy

  • Remove a child account from a hierarchy

  • Open any account in the hierarchy

Sponsorship Tab

In this tab, you can see whether an account owns a sponsor group or whether it is sponsored by another account.

For an account that owns a sponsor group, this tab displays the following:

  • A list of groups that the account sponsors

  • Products and rate plans for each sponsor group

  • Members of each sponsor group

For a group owner, you can do the following from this tab:

  • Create and delete sponsor groups

  • Add or remove rate plans

  • Add or delete group members

  • Open any member's account

For an account that belongs to a sponsor group, you can display a list of sponsor groups and rate plans that the account belongs to. From that list, you can also display the account of the sponsor group's owner.

For any account, you can create a new sponsor group from this tab.

About Event Browser

You use Event Browser to find events. When you find the event you are looking for, you can perform the following tasks:

  • Summarize the impacts of events on the resource balances in an account. For example, you can see how login events during one month affected the balance of dollars and hours in a customer's account.

  • Cancel the effects of events on resource balances. For example, if a customer was charged the wrong amount, you can cancel the charge by adjusting the event that generated the charge.

  • Review detailed information about a customer's account such as credits, debits, dialup sessions, and name changes.

You access Event Browser from Customer Center. For more information, see "Using the Event Browser to Display and Adjust Events" in BRM Managing Accounts Receivable.

About Dumping and Validating Account-Related Information

The Account Dump utility (ADU) is a diagnostics tool that allows you to validate account information before or after certain business processes. For example, after completion of a migration or upgrade or before billing or payment allocation.

You can use ADU to dump the contents of storable objects for an account into an output file and perform data analysis on the contents of the output file. For example, after an account migration, you can use ADU to dump the /billinfo and /payinfo object information of the account to a file and validate the billing and payment data.

Important:

ADU can be performance intensive, depending on the number of accounts for which data is being retrieved and the volume of data being processed. Avoid running performance-intensive operations, such as billing, while running ADU.

The account dump and data validation process is a follows:

  1. Create an input file with the account search specification. ADU uses the specification to select accounts in the BRM database. See "About ADU Account Search".

  2. ADU searches the accounts in the BRM database, retrieves the related object information, and dumps the information to an output file. See "About ADU Account Dump".

  3. ADU validates the contents of the output file. See "About Account Data Validation".

About ADU Account Search

You can request ADU to dump information for a single account or for multiple accounts. To specify the accounts for which you want to dump information, you provide as input a text file that contains the account search specification. The search specification must be in the form of an flist.

For example, the following search flist requests the dump of the account 0.0.0.1 /account 789888 0:

0 PIN_FLD_POID          POID [0] 0.0.0.1 /account 1 0
0 PIN_FLD_RESULTS       ARRAY [0]
1    PIN_FLD_ACCOUNT_OBJ  POID [0] "/account" 789888 0

The following search flist requests the dump of all the accounts with billing day of month (DOM) as 1:

0 PIN_FLD_POID      POID [0] 0.0.0.1 /search/pin -1 0
0 PIN_FLD_FLAGS     INT [0] 256
0 PIN_FLD_TEMPLATE  STR [0] "select X from /billinfo where F1 = V1 "
0 PIN_FLD_RESULTS   ARRAY [0]
1    PIN_FLD_ACCOUNT_OBJ POID [0] NULL
0 PIN_FLD_ARGS      ARRAY [1]
1    PIN_FLD_ACTG_CYCLE_DOM INT [0] 1

Note:

  • ADU considers each account as a standalone. If a group owner account is specified in the search flist, ADU dumps only the contents of the owner account. ADU will not dump the contents of the group member accounts. Similarly, if a group member account is specified in the search flist, only the contents of the member account is dumped. ADU will not dump the contents of the owner account or other group member accounts.

  • The PIN_FLD_RESULTS array in the search flist must contain only PIN_FLD_ACCOUNT_OBJ.

Important:

ADU can be performance intensive, depending on the number of accounts for which data is being retrieved and the volume of data being processed. Run ADU in -report mode first to determine the volume of data to be processed so that you can optimize your account search for best performance. See "pin_adu_validate" in BRM Developer's Guide.

About ADU Account Dump

ADU provides the flexibility to choose the object information that you want dumped for an account. For example, you can request ADU to dump the /account, /service, and /invoice object information only.

You can also select the fields of an object that you want dumped. ADU then dumps only those fields into the output file. For example, you can request to dump only the first and last names of the account.

Some storable objects, such as /audit and /event, contain large volumes of data. Searching and retrieving information from these objects can be system intensive. Therefore, ADU provides the option to select data from these objects by specifying a date range. For example, you can configure ADU to dump the /event objects of an account updated between February 1, 2007, and March 1, 2007. For more information on using the date range option, see "Limiting Dump Information by Specifying a Date Range".

A separate output file is generated for each account. ADU uses the format account_Poid_ID0.File_Extension to generate the output file name where Poid_ID is the BRM account object identifier and File_Extension is the extension defined in the ADU configuration file. The file extension can be configured in the ADU configuration file (pin.conf). See "Configuring ADU".

Caution:

The output file is overridden if the dump is requested for the same accounts more than once and is stored in the same output folder.

By default, ADU dumps the object contents in the output file in XML format. If you prefer a different output format (for example, CSV), you can customize the output format by modifying the PCM_OP_ADU_POL_DUMP policy opcode. See BRM Developer's Reference.

Limiting Dump Information by Specifying a Date Range

You can limit the dump for the following storable objects in the BRM database by specifying a date range:

  • /audit

  • /bill

  • /item

  • /event

  • /invoice

  • /balance_group

These objects normally contain large volumes of data. To limit the amount of data retrieved from these objects, use the date range option to select only data updated during a specified period.

For example, if you choose to dump the contents for /account, /service, /bill, and /item and specify February 1, 2007, as the dump_start_time and March 1, 2007, as the dump_end_time, ADU uses that date range for searching and retrieving data from the /bill and /item objects only. The date range is not used for retrieving data from the /account and /service objects.

The date range is mapped to the object date fields as follows:

  • For the /audit object, ADU selects only those objects whose created_t or effective_t is between dump_start_time and dump_end_time.

  • For the /bill object, ADU selects only those objects whose end_t is between dump_start_time and dump_end_time.

  • For the /item object, ADU selects only those objects whose effective_t is between dump_start_time and dump_end_time.

  • For the /event object, ADU selects only those objects whose end_t is between dump_start_time and dump_end_time.

  • For the /invoice object, ADU selects only those objects whose created_t is between dump_start_time and dump_end_time.

  • For the /balance_group object, ADU selects only those objects whose effective_t is between dump_start_time and dump_end_time.

To configure the date range, see "Configuring ADU".

About Account Data Validation

ADU performs two types of validations on the object contents: structural and dynamic.

Structural validation validates the structure of the account. For example, validating that the POID of the parent bill object exists in the subordinate /bill object.

Dynamic validation validates the business logic. For example, validating that the /item due amount is zero after a payment.

Table 2-1 contains the predefined structural and dynamic validations. Each validation is associated with a validation code.

Table 2-1 Predefined Structural and Dynamic Validations

Validation Type Validation Code Description

Structural

struct_valid_01

Validates that /event objects point to the correct /item objects based on the mappings configured in /config/item_tags and /config/item_types.

Structural

struct_valid_02

Validates that the PIN_FLD_PARENT field of the subordinate account's last bill points to the parent /bill object.

Validates that the bill number of the subordinate account and the bill number of the parent account are the same.

Structural

struct_valid_03

Validates that the DOM of the subordinate account and the DOM of the parent account are the same.

Structural

struct_valid_04

Validates that the AR_BILLINFO_OBJ of the subordinate account points to the /billinfo object of the parent account.

Dynamic

dynamic_valid_01

Validates that the /item due amount is zero after payment.

You enable these validations by setting the corresponding validation code in the ADU pin.conf file. ADU logs the results of the validations in the Connection Manager (CM) log file.

You can customize additional validations by modifying the PCM_OP_ADU_POL_VALIDATE policy opcode.

Configuring ADU

To configure ADU, set the entries in the ADU configuration file (BRM_Home/sys/diagnostics/pin_adu_validate/pin.conf) shown in Table 2-2:

Table 2-2 Entries in the ADU Configuration File

Entry Description

- pin_adu input_file file_name

Set file_name to the name of the input file that contains the account search specification. For example:

- pin_adu input_file opt/portal/7.5/sys/diagnostics/pin_adu_validate/in/input.txt

- pin_adu output_file file_name

Set file_name to the name of the output folder where ADU should write the output file. For example:

- pin_adu output_file /opt/portal/7.5/sys/diagnostics/pin_adu_validate/out

- pin_adu out_file_ext.ext

Set ext to the output file extension. For example:

- pin_adu out_file_ext.xml

- pin_adu obj_list object1 [; object2]...

Specify the objects to dump for the selected accounts. For example:

To dump /billinfo and /payinfo objects:

- pin_adu obj_list /billinfo; /payinfo

Note: Use a semicolon to separate items in the object list.

- pin_adu obj_flds object1:field1, field2, ...

[object2:field1, field2, ...] ...

Specify the fields in the objects to dump. For example:

To dump the first and last name of an account:

- pin_adu obj_flds /account: PIN_FLD_NAMEINFO.PIN_FLD_FIRST_NAME, PIN_FLD_NAMEINFO.PIN_FLD_LAST_NAME

To dump account invoice information:

- pin_adu obj_flds /payinfo/invoice: PIN_FLD_INV_INFO

Note: Use a colon to separate the items in the object list.

- pin_adu dump_start_time time

- pin_adu dump_end_time time

Set time in these entries to the times to use for selecting most commonly updated objects. For example:

- pin_adu dump_start_time 1175385600

- pin_adu dump_end_time 1177977600

Note: time must be in UTC format.

- pin_adu struct_valid_01 n

- pin_adu struct_valid_02 n

- pin_adu struct_valid_03 n

- pin_adu struct_valid_04 n

- pin_adu dynamic_valid_01 n

Use these entries to enable (1) or disable (0) the predefined validations. For example:

- pin_adu struct_valid_01 1

- pin_adu dynamic_valid_01 1

- pin_mta logfile file_name

Set file_name to the ADU log file. All the debug and error messages generated by ADU are logged to this file.

- pin_mta logfile /opt/portal/7.5/sys/diagnostics/pin_adu_validate/adu.pinlog

- pin_mta loglevel n

Set n to the level of information to log in the ADU log file.

Log level values are as follows:

0: no logging

1: log error messages only

2: log error messages and warnings only

3: log error messages, warnings, and debug messages

- pin_mta loglevel 2

About Securing Sensitive Customer Data with Masking

You can prevent access to and logging of sensitive customer data, such as banking information and passwords, by masking the string data fields that store this information. BRM client applications, transaction messages, and logs can contain sensitive information. Enabling data masking protects this data by hiding it.

Enabling Data Masking

The pin_fld_mask_file file contains information about which data fields to mask.

To enable data masking:

  1. Open the BRM_Home/sys/cm/pin_fld_mask_file file in a text editor.

  2. For each field requiring masking, add the following line:

    Field_Name Length [Masking_Character]

    where:

    • Field_Name is the field to be masked.

    • Length is either the number of characters to mask or the number of characters at either end of the field to unmask.

      To specify the number of characters to mask, enter a numerical value. Masking a field with a set number of characters is useful when you do not want to reveal the length of a field.

      To unmask a set number of characters at either end of the field, specify the Length including a dash (-), the number of characters to unmask, and either an L or R to indicate whether to unmask the beginning (L) or end (R) of a field's string value.

    • Masking_Character is the character used to mask the original value. If no masking character is specified, BRM uses * by default.

    Example 2-1 shows a sample pin_fld_mask_file file.

    Example 2-1 Sample pin_fld_mask_file File

    # This file controls the masking of certain field values in flists the CM returns
# Only fields of type STR can be masked
# Each valid entry is of 1 of 3 types:
# 1.PIN_FLD_XXX   N    c #mask with a string of length N using char c
# 2.PIN_FLD_XXX   -NL  c #mask with char c leaving up to N chars unmasked on left
# 3.PIN_FLD_XXX   -NR  c #mask with char c leaving up to N chars unmasked on right
# In each case N is an integer >= 0 and c is the masking character
# (for type 1, N cannot exceed 128)
# The first type is useful for masking fields where we don't want to reveal how
# many characters make up the field.
# The remaining 2 types are useful for partial masking; note that the integer N # # indicates how many characters are revealed.
#
# FIELD_NAME            LENGTH   MASK_CHAR
PIN_FLD_PASSWD          10           *     
# mask with 10 '*'. Result: "**********"
PIN_FLD_PASSWD_CLEAR    15           -     
# mask with 15 '-'. Result: "---------------"
PIN_FLD_DEBIT_EXP       -0L          0     
# same as -0R, all positions are masked with 0
PIN_FLD_DEBIT_NUM       -4R          *     
# the last 4 positions are not masked. e.g. "*******1234"
PIN_FLD_BANK_ACCOUNT_NO -2L          *     
# the first 2 positions are not masked, e.g. "12***********"

  3. Save the file.

  4. Open the CM pin.conf file in a text editor.

  5. Uncomment the following entry in the CM pin.conf configuration file:

    #- cm pin_fld_mask_file BRM_Home/sys/cm/pin_fld_mask_file

    Note:

    Add this entry in the CM pin.conf file if it does not already exist.

    Uncommenting this entry enables masking of fields listed in the pin_fld_mask_file file.

  6. Restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

    Note:

    You must restart the CM whenever you change the masking configuration specified in pin_fld_mask_file.

Masking Sensitive Data in Logs When Using Client Applications

Portal Communication Module (PCM) C++ and Java client applications may log flists containing sensitive customer data before calling the CM for processing and when returning results. Client application logs can contain flists in either standard BRM format or in XML format. Standard format flist fields configured for masking are automatically hidden before logging by the PIN_FLIST_TO_STR macro. To mask sensitive data in flists stored in XML format during logging, your client application must call the XMLToFlist class included in the pcm.jar file.

For more information on developing PCM C++ and Java client applications, see "Creating Client Applications by Using PCM C++" and "Creating Client Applications by Using Java PCM" in BRM Developer's Guide.

Masking Additional Fields in Client Application Logs

BRM masks the following string data fields in client application logs for standard format flists and XML flists processed by the XMLToFlist class:

  • PIN_FLD_PASSWD

  • PIN_FLD_PASSWD_CLEAR

  • PIN_FLD_DEBIT_NUM

  • PIN_FLD_DEBIT_EXP

  • PIN_FLD_BANK_NO

  • PIN_FLD_BANK_ACCOUNT

  • PIN_FLD_BANK_ACCOUNT_NO

  • PIN_FLD_IBAN

You can add additional fields to be masked, including custom fields, in client application logs based on your security requirements. A list of default BRM fields are defined in the pin_flds.h file while custom fields are found in the cust_flds.h file. See "Creating Custom Fields and Storable Classes" in BRM Developer's Guide for information on adding custom fields.

To mask additional fields in logs of PCM C++ applications:

  1. Open the BRM_Home/include/pin_flds.h file or the BRM_Home/include/cust_flds.h file and obtain the field IDs you want to mask.

  2. For each field requiring masking, add a line at the end of either the pin_flds.h or cust_flds.h file using the following syntax:

    #define Field_Name PIN_MAKE_FLD(Field_Name,ID)
Field_Name masked

    where Field_Name is the string field to mask in PCM C++ client application logging and ID is the BRM assigned ID for the field. For example, mask the PIN_FLD_CHECK_NO field by using the following line:

    #define PIN_FLD_CHECK_NO PIN_MAKE_FLD(PIN_FLDT_STR, 931)
PIN_FLD_CHECK_NO masked

    Note:

    Ensure that your cust_flds.h file does not contain duplicate entries.

  3. Save the file.

  4. If only masking additional fields in pin_flds.h, restart the CM.

To mask fields defined in cust_flds.h, complete the following additional steps:

  1. Make a copy of your cust_flds.h file named masked_fields.

  2. Run the BRM_Home/bin/parse_custom_ops_fields.pl perl script which generates the masked_fields.dat file using the following syntax:

    perl -S parse_custom_ops_fields.pl -L pcmc -I masked_fields -O masked_fields.dat

  3. Add the following entry in the pin.conf file for your PCM C++ client application:

    - - ops_fields_extension_file path/masked_fields.dat

    where path is the path to the masked_fields.dat file.

    Note:

    The pin.conf file must only have one -- ops_fields_extension_file entry. If you already have a cust_flds.h file, append your masking entries in the same file and generate a single masked_fields.dat file.

  4. Restart the CM.

To add additional string data fields for masking in logs of PCM Java applications:

  1. Open the BRM_Home/include/pin_flds.h file or the BRM_Home/include/cust_flds.h file and obtain the field IDs. BRM assigns each field a numerical value listed at the end of each row. Use this field ID in the Infranet.properties file for masking. For example, the field ID for the PIN_FLD_CHECK_NO field is 931:

    #define PIN_FLD_CHECK_NO PIN_MAKE_FLD(PIN_FLDT_STR, 931)

  2. Open the Infranet.properties file for your PCM Java application in a text editor.

  3. Add a line for each additional field to be masked using the following syntax:

    infranet.custom.masked.field.field_id=masked

    where field_id is the field ID for the default or custom field you want to mask.

  4. Save the file.

  5. Verify that the Infranet.properties file is included in the classpath of the PCM Java client application process.