3 Setting Up Collections Manager

This chapter explains how to set up Oracle Communications Billing and Revenue Management (BRM) Collections Manager.

Before you read this chapter, you should be familiar with the following:

  • BRM concepts and architecture. See BRM Concepts.

  • BRM Collections Manager concepts. See "Understanding Collections Manager".

  • Modifying BRM configuration files. See BRM System Administrator's Guide.

If your setup requires the modification of policy opcodes, C programming skills and knowledge of BRM development concepts and procedures are necessary. See BRM Developer's Guide.

For installation information, see "Installing Collections Manager".

About Setting Up Collections Manager

After you install Collections Manager, you must set it up to meet your business needs:

Configuring Collections Manager

To configure Collections Manager, you perform the following general tasks:

Adding Custom Pay Types

When you run the pin_collections_process utility, it considers only bill units (/billinfo objects) with the default pay types, such as 10001, 10002, 10003, 10004, 10005, and 10006.

To add custom pay types:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor, where BRM_home is the directory in which BRM is installed.

  2. Add the following entry:

    - pin_collections_process pay_type PaymentType1[, PaymentType2...]
    

    Note:

    Valid pay type codes are in the BRM_home/include/pin_cust.h file, under PAY_TYPE.

    For example, to add the wire transfer payment type:

    - pin_collections_process pay_type 10013, 10014
    
  3. Save and close the file.

Setting the Minimum Overdue Balance to Process

When you run pin_collections_process, only bill units (/billinfo objects) with overdue balances greater than or equal to the amount you specify are considered.

To set the minimum overdue balance for collections:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor.

  2. Set the minimum_due entry to the minimum overdue balance:

    - pin_collections_process minimum_due Amount
    

    For example, to set the minimum overdue balance to $25:

    - pin_collections_process minimum_due 25.00
    

    Note:

    The default is 0.0.

    Important:

    The value you specify is a system-wide minimum value. Collections scenarios cannot have entry criteria lower than this value. For example, if the minimum value is $25 and a collections scenario has an entry criteria of $10, a bill unit will enter collections only if its overdue balance is $25 or more.
  3. Save and close the file.

Setting the Number of Bill Units Retrieved during Step Searches

The Collections Functional Module (FM) opcodes use step search when searching for bill units. The step size determines the number of bill units retrieved at one time.

To specify the number of bill units to retrieve in step searches:

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

  2. Set the account_search_batch entry to the number of bill units:

    - fm_collections account_search_batch Amount
    

    For example, to retrieve 500 bill units with each step of the search.

    - fm_collections account_search_batch 500
    

    Note:

    The default is 1000.
  3. Save and close the file.

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

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

Setting Up Invoice Reminders

Collections Manager uses the Universal Message Store (UMS) framework to deliver invoice reminders. See "Using BRM Messaging Services" in BRM Developer's Guide for general information.

If you plan to use invoice reminders as part of the collections process, complete the following tasks related to the UMS framework:

  • Enable messaging by modifying the PCM_OP_INV_POL_PREP_INVOICE policy opcode. See "Enabling Messaging" in BRM Developer's Guide.

  • Load a message style sheet (message.xsl) that makes it possible to display messages in invoices. See "Loading the Message Style Sheet" in BRM Developer's Guide.

  • Load invoice reminder templates into /string objects in the BRM database. See "Creating and Loading Message Templates" in BRM Developer's Guide. Collections Manager includes a sample invoice reminder template that you can modify and rename as necessary. The file is BRM_home/sys/msgs/messages/message_invoice_reminder.en_US.

Creating Dependencies between Collections Actions in a Scenario

By default, Collections Manager performs automated collections actions on their due date, regardless of whether the preceding collections actions have been completed or canceled. This can cause collections actions to be completed out of order.

You can configure Collections Manager to create dependencies between collections actions in a scenario and thus perform collections actions in order.

When so configured, Collections Manager performs the following additional steps during scenario processing:

  • Performs a collections action on its due date only if the action's status is set to Pending.

  • After completing or canceling a collections action, Collections Center asks whether to reschedule the due dates of any outstanding collections actions in the scenario. When set, Collections Manager calculates the difference in days between the action's completed or canceled date and the action's due date, and then moves the due dates of all outstanding actions by the calculated number of days. For example, assume a collections scenario contains two collections actions:

    • Action 1: A manual phone call from an agent 5 days after the bill unit enters collections.

    • Action 2: Referring the case to an outside collections agency 10 days after the bill unit enters collections.

    If Action 1 does not occur until day 7, Collections Manager changes the due date of Action 2 from day 10 to day 12. This maintains the interval between Action 1 and Action 2. All outstanding actions are also rescheduled accordingly to maintain the configured intervals. If rescheduled Action 2 falls on a weekend, it is processed the next working day, and outstanding actions are again rescheduled to maintain the interval between the actions. Rescheduling prevents two actions from occurring on the same day unless the actions are configured to do so.

To create dependencies between collections actions in a collections scenario:

  1. Open the CM configuration file (BRM_home/sys/cm/pin.conf) in a text editor.

  2. Set the collections_action_dependency entry to 1.

    - fm_collections collections_action_dependency 1
    

    Note:

    The default is 0, which disables dependencies between collections actions.
  3. Save and close the file.

  4. Stop and restart the CM.

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

Setting Up Dunning Letters

To set up Collections Manager to generate dunning letters, you must run the Email Data Manager (DM) and load your dunning letter templates.

Running Email Data Manager for Dunning Letters

The Email DM must be running before you can send dunning letters, even if you plan to print and mail the letters. For information about configuring the Email DM, see "Sending Email to Customers Automatically" in BRM Managing Customers and "Configuring the Email Data Manager for Printing" in BRM Designing and Generating Invoices.

Loading Dunning Letter Templates

You load dunning letter templates by using the pin_load_template utility. These dunning letter templates are used in Collections Configuration to set the dunning letters action and the invoice reminders action.

Dunning letter templates are XSL documents that provide the basic content of the letter, leaving placeholders for specific information such as the customer's name, overdue balance, and so on. You can design and load multiple dunning letter templates for different brands, scenarios, and situations. For example, if a given brand has three scenarios, you could load two dunning letters for each scenario.

Collections Manager includes two sample dunning letter templates: dunning_first.xsl and dunning_last.xsl. Both templates are stored in BRM_home/sys/data/config/stylesheets. You can use a third-party XSL editor to modify these templates or to create your own templates.

After creating your template, load it into the BRM database by using the pin_load_template utility. Templates are available in Collections Configuration immediately after you load them. See "Defining Collections Actions".

To load a dunning letter template:

  1. Go to a directory that contains a valid configuration (pin.conf) file.

    Tip:

    A configuration file is installed automatically in BRM_home/apps/pin_collections.

    The pin_load_template utility uses information in the configuration file to connect to the BRM database. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  2. Load the XSL template by entering the following command:

    pin_load_template -brand brand_POID - name template_name -type dunning -locale locale_name -template file_name -usexsl 
    

    where:

    • brand_POID is the Portal object ID (POID) of a brand account or the root account. Use a brand account POID to assign the template to a specific brand. Use the root account POID if your system does not use brands or if you want the template to be available to multiple brands. If the brand account POID contains spaces, use quotation marks.

    • template_name is the name of the template as it should appear in Collections Configuration.

    • locale_name is the BRM locale of the template. See "Locale Names" in BRM Developer's Guide.

    • file_name is the name and full path of the template file.

For example, the following command loads the dunning_first.xsl template for the root account:

pin_load_template -brand "0.0.0.1/account 1" -name DunningTemplate -type dunning -locale en_US -template BRM_home/config/dunning_first.xsl -usexsl 

Adding Custom Reason Codes for Collections Center

In Collections Center, you can perform operations such as inserting new actions, rescheduling actions, and exempting bill units from collections. See "Managing Bill Units in Collections" for an overview.

For many of these operations, you choose a reason that is associated with the action. Collections Center includes a default set of reasons, which you can modify.

To modify the default reasons, you can add or change reason codes in each reasons.locale file.

Defining Collections Features

Many Collections Manager configuration tasks are completed with Collections Configuration. Collections Configuration is a GUI application that you can use for:

See "Installing Collections Manager" for information about installing Collections Configuration.

Branding and Collections Configuration

Collections Configuration supports branding. You can choose the active brand to which your configuration choices apply. You have access only to the brands allowed by your access privileges. (See the Collections Configuration Help for information about choosing the active brand.)

For example, if the active brand is Brand A, the profiles, scenarios, and actions you create during your Collections Configuration session will be valid only for Brand A. You must use a different login name to make configuration choices for other brands.

There are exceptions to this rule. The following actions are predefined by BRM, cannot be modified, and are valid across all brands:

  • Inactivate bill unit

  • Refer to collections agency

  • Close bill unit

  • Write off balance

Defining Aging Buckets

Aging buckets define time periods for overdue balances. Each bucket lasts a certain number of days, after which a balance falls into the next bucket. You can create up to 10 aging buckets, which apply systemwide to all scenarios.

For example, you could define 30-day, 60-day, and 90-day buckets. The 30-day bucket holds balances that are 1 to 30 days overdue. The 60-day bucket holds balances that are 31 to 60 days overdue, and the 90-day bucket holds balances that are 61 to 90 days overdue. Balances older than 90 days fall into an implicit fourth bucket.

Aging buckets are used to display information about the age of overdue balances. This information is displayed in Collections Center.

See the Collections Configuration Help for information about defining aging buckets.

Setting Up Collections Profiles

Collections profiles define categories into which you organize bill units for collections purposes. For example, you could organize bill units by credit score. Bill units with a score below a certain number are assigned to one collections profile, and bill units with higher scores are assigned to a different profile.

A bill unit's collections profile helps determine to which collections scenario a bill unit is assigned. (Scenarios define entry and exit criteria for collections as well as what happens to a bill unit while it is in collections. See "Defining Collections Scenarios".)

For example, bill units in the low-credit-score profile might be assigned to scenarios with more aggressive collections actions and lower entry criteria. Customers in the high-credit-score profile could be assigned to scenarios with more lenient policies.

By default, all bill units belong to a single collections profile. If you do not need a more complex system, you do not have to define any additional profiles. You can map all your scenarios to the default profile.

To set up additional profiles, you complete two sets of tasks:

  1. Define names and descriptions for the profiles by using Collections Configuration. See the Collections Configuration Help for step-by-step instructions.

    When you define a new profile, Collections Configuration creates a /config/collections/profile object, which stores definitions of collections profiles.

  2. Customize the PCM_OP_COLLECTIONS_POL_SELECT_PROFILE policy opcode. You need to write code that defines the characteristics of the collections profiles and maps bill units to them.

    Important:

    This step requires programming.

Configuring the Currency Used in Collections

The default profile uses US dollars for the currency. To use a different currency for collections, edit the PCM_OP_COLLECTIONS_POL_SELECT_PROFILE policy opcode.

If a scenario is configured in any other currency, you must customize the PCM_OP_COLLECTIONS_POL_SELECT_PROFILE policy opcode to consider this scenario for collections.

Increasing the Size of the CM Cache for Profiles Data

When setting up additional profiles, you might need to increase the space allocated to the profiles data in the CM cache.

To increase the CM cache size for profiles data:

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

  2. Increase cache_size in the following entry:

    - cm_cache fm_collections_config_profiles_cache number_of_entries, cache_size, hash_size
    

    Note:

    The default is 20480 bytes.
  3. Save and close the file.

  4. Stop and restart the CM.

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

Defining Collections Actions

Collections actions are individual steps that are performed in the process of collecting overdue balances. An action might be applying a late fee or making a phone call.

You can define as many actions as you need. For example, you can define different phone call actions for different situations: courtesy calls, warning calls, and so on. The same action can be included in multiple scenarios. See "Defining Collections Scenarios".

When you define a collections action, you specify the following in Collections Configuration:

  • The collections action name

  • The action type: manual, one of several system types, and custom

  • For bill units in a collections sharing group, the target bill units: the specified bill unit only (Self), the parent and all child bill units (All Members and Parent), or all child bill units (All Members)

Note:

The action target defined for each of the collections actions for a customer is the same for all scenarios. When the action target mode is set for an action, the action target cannot be changed for any newly defined scenarios.

Understanding Manual Actions

Manual actions are completed by collections agents. When a scenario calls for a manual action, BRM saves information about the action in the database. Collections Center displays this information so that a collections agent can complete the action.

For example, suppose that a scenario calls for the customer to receive a courtesy phone call when the account's bill unit is 10 days into the collections process. When a bill unit enters collections, this phone call is included in the list of actions for the bill unit. On the day when the phone call is due, the phone call appears in the list of tasks for the collections agent assigned to the bill unit.

The most common manual action is a phone call, but you can create any others that your business requires.

For more information about manual actions, see the Collections Configuration Help.

Understanding System Actions

System actions are performed automatically by BRM when either of the following two utilities is run:

  • pin_collections_process

  • pin_deferred_act (as a part of the pin_bill_day script)

If an error occurs while performing any collections action when pin_collections_process is run, the status of the collections action object (/collections_action) and the schedule object (/schedule) corresponding to the collections action is updated to Error.

If an error occurs while performing any collections action when pin_deferred_act is run, the status of the collections action remains Pending but the schedule object corresponding to the collections action is updated to Error. When pin_collections_process is run and the collections actions is processed again, if an error occurs, the collections action object is updated to Error.

The status of collections actions is updated to Completed on successful completion of the actions.

By default, Collections Manager supports the following types of system collections actions:

  • Charging a late fee. For late fees, you specify the currency type, such as US dollars, and the late fee type, either a specified amount or a percentage of the overdue amount.

  • Adding a finance charge. For finance charges, you specify to charge a certain percentage of the overdue amount.

  • Sending a dunning letter. For dunning letters, you specify the dunning letter template to use. You can have different templates for different purposes. For example, you could define several dunning letter templates with varying levels of severity. These templates could be used at different times in the same scenario or in separate scenarios.

  • Sending an invoice reminder. For invoice reminders, you specify the invoice reminder template to use. You can have different templates for different purposes. For example, you could define several invoice reminder templates with varying levels of severity. These templates could be used at different times in the same scenario or in separate scenarios.

You can customize each system action's behavior by modifying policy opcodes:

  • To customize the way late fees are assessed, modify the PCM_OP_COLLECTIONS_POL_APPLY_LATE_FEES policy opcode.

  • To customize the way finance charges are calculated, modify the PCM_OP_COLLECTIONS_POL_APPLY_FINANCE_CHARGES policy opcode.

  • To customize the way dunning letter content is gathered, modify the PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA policy opcode.

  • To customize the way invoice reminder content is gathered, modify the PCM_OP_INV_POL_PREP_INVOICE policy opcode.

Important:

Modifying policy opcodes requires programming.

For more information about system actions, see the Collections Configuration Help.

Performing Scheduled Collections Actions after Reinstalling Collections Manager

After reinstalling Collections Manager, running the pin_collections_process utility does not perform the collections actions that have a due date prior to the date on which you reinstalled Collections Manager.

You can perform all the scheduled collections actions after reinstalling Collections Manager and running the pin_collections_process utility irrespective of whether the collections actions have a due date prior to the date or after the date on which you reinstalled Collections Manager and ran pin_collections_process.

To perform all scheduled collections actions irrespective of whether they have a due date prior to the date or after the date on which you reinstalled Collections Manager and ran pin_collections_process:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor.

  2. Add the following entry:

    - pin_collections_process execute_all_actions value
    

    where value is:

    • 1 to perform all collections actions irrespective of whether they have a due date prior to the date or after the date on which you ran pin_collections_process after reinstalling Collections Manager.

    • 0 to perform only those collections actions that have a due date later than the date on which pin_collections_process is run after reinstalling Collections Manager. This is the default.

  3. Save and close the file.

  4. Stop and restart the CM.

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

Understanding Custom Actions

Custom actions are system actions that you create. You define custom actions and descriptions in Collections Configuration and implement the actions by modifying the PCM_OP_COLLECTIONS_POL_EXEC_POLICY_ACTION policy opcode.

See the Collections Configuration Help for information about defining custom actions and see PCM_OP_COLLECTIONS_POL_EXEC_POLICY_ACTION for information about modifying the policy opcode.

Important:

Modifying policy opcodes requires programming.

Increasing the Size of the CM Cache for Actions Data

When defining actions, you might need to increase the space allocated to the action data in the CM cache.

To increase the CM cache size for actions data:

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

  2. Increase cache_size in the following entry:

    - cm_cache fm_collections_config_actions_cache number_of_entries, cache_size, hash_size
    

    Note:

    The default is 40960 bytes.
  3. Save the file.

  4. Stop and restart the CM.

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

Defining Collections Scenarios

When you create a new scenario, you decide which collections profile it applies to. You can define multiple scenarios with different characteristics for the same profile. For example, you could set up one scenario for relatively small overdue balances and another for larger balances.

A single scenario cannot be used with multiple collections profiles. If you want to implement scenarios with the same functionality across several profiles, you can define multiple scenarios with the same characteristics but different names.

A scenario includes an ordered list of actions that are taken against the bill unit. When you define a scenario, you select from a list of actions that you have previously defined and then specify the following characteristics:

  • The order in which the actions should take place

  • The number of days after entering collections that the action should be completed; for example, 5 days after entering collections.

  • Whether an action is optional or mandatory

Note:

If you define a collections scenario that includes both a writeoff and a bill unit inactivation, the writeoff must come before the inactivation. When a bill unit is inactivated, an event with a credit balance is created to cancel the remaining service for the bill unit. The cycle fees are then prorated and the remaining credit is returned to the bill unit, in some cases as a separate item. If the bill unit has already been inactivated, the writeoff will fail because of the unallocated item. In this case, a customer service representative (CSR) must manually allocate the item so that it can be written off.

For more information about defining scenarios, see the Collections Configuration Help.

Loading Additional Parameters for Scenario Assignment

You load additional parameters for a collections scenario assignment by using the load_config utility. See "load_config" in BRM Developer's Guide for more information.

The utility takes an XML file as input and creates or updates the /config/collections/scenario_params object in the BRM database. Collections Configuration reads the /config/collections/scenario_params object and displays the parameters while defining the evaluation formula to associate with a collections scenario.

For more information about defining scenarios, see the Collections Configuration Help.

To load additional collections scenario parameters:

  1. Open the BRM_home/sys/data/config/config_collections_scenario_params.xml file in a text editor.

  2. Edit the file, which includes examples and instructions. Table 3-1 describes the parameters in this file:

    Table 3-1 Elements Used to Store Additional Scenario Parameters

    Element Description

    PARAM_NAME

    Name of the parameter.

    STRING_ID

    The string ID of the parameter name. This field is used for localization.

    STR_VERSION

    The version of the localized string within the domain. This field is used for localization.

    TYPE

    The type of value that the parameter can be assigned, from one of the following types:

    • 1: STR (alphanumeric)

    • 2: INT (integer)

    • 3: ENUM (indicating that the parameter is one of an ordered list of possible values. An array of values must be provided for this selection.)

    • 4: DECIMAL

    • 5: TSTAMP (timestamp)

    For example, to provide a set of possible values, you set the <TYPE> element to 3, and enter an array of values for this parameter in the <VALUES> element

    CLASS_NAME

    The storable class object associated with the parameter.

    FIELD_NAME

    The field inside the storable class referenced in the <CLASS_NAME> element. To enter the field name of a field present under an array or a substruct, use the format <FIELD_NAME>array.field</FIELD_NAME >, which includes the parent field of the attribute separated by periods (.). For example: <FIELD_NAME>PIN_FLD_COLLECTIONS_PARAMS.PIN_FLD_CREDIT_PROFILE</FIELD_NAME >.

    VALUES

    An array list of values that the parameter can assume. The <VALUES> array list is present only if the selection for the <TYPE> element is 3.


    For example, the following entry defines a new parameter called Payment Method:

    <PARAMS elem="0">
         <PARAM_NAME>Payment Method</PARAM_NAME>
         <STRING_ID>1</STRING_ID>
         <STR_VERSION>1</STR_VERSION>
         <TYPE>3</TYPE>
         <CLASS_NAME>/billinfo</CLASS_NAME>
         <FIELD_NAME>pay_type</FIELD_NAME>
         <VALUES elem="0">
                    <NAME>CC</NAME>
                    <VALUE>10003</VALUE>
                    <STRING_ID>100</STRING_ID>
                    <STR_VERSION>1</STR_VERSION>
         </VALUES>
         <VALUES elem="1">
                    <NAME>DD</NAME>
                    <VALUE>10005</VALUE>
                    <STRING_ID>101</STRING_ID>
                    <STR_VERSION>1</STR_VERSION>
         </VALUES>
         <VALUES elem="2">
                    <NAME>CASH</NAME>
                    <VALUE>10011</VALUE>
                    <STRING_ID>102</STRING_ID>
                    <STR_VERSION>1</STR_VERSION>
         </VALUES>
         <VALUES elem="3">
                    <NAME>CHECK</NAME>
                    <VALUE>10012</VALUE>
                    <STRING_ID>103</STRING_ID>
                    <STR_VERSION>1</STR_VERSION>
         </VALUES>
    </PARAMS>
    

    In this example:

    • The name of the parameter is Payment Method.

    • The type of value is 3 (which is ENUM, and so an array of values follows.)

    • The storable class is /billinfo.

    • The field inside the storable class object is pay_type.

    • The Values array lists the four possible payment methods: CC, DD, Cash, and Check.

    For example, the following entry defines a parameter called Credit Profile:

    <PARAMS elem="3">
         <PARAM_NAME>Credit Profile</PARAM_NAME>
         <STRING_ID>4</STRING_ID>
         <STR_VERSION>1</STR_VERSION>
         <TYPE>2</TYPE>
         <CLASS_NAME>/profile/collections_params</CLASS_NAME>
         <FIELD_NAME>PIN_FLD_COLLECTIONS_PARAMS.PIN_FLD_CREDIT_PROFILE</FIELD_NAME>
    </PARAMS>
    

    In this example:

    • The name of the parameter is Credit Profile.

    • The type of value is 2 (which is INT.)

    • The storable class is /profile/collections_params.

    • The field including the path to the storable class object is PIN_FLD_COLLECTIONS_PARAMS.PIN_FLD_CREDIT_PROFILE.

    By default, the config_collections_scenario_params.xml file contains sample data for the following parameters:

    • Payment Method (Credit Card, Direct Debit, cash, check) from the /billinfo class

    • Account Status from the /account class

    • Account Type from the /account class

    To define additional data during scenario evaluation, you can create and maintain the required data (parameters and their values) in a customized data class or by extending the /profile class. This data class should have a link to the bill unit to which the data is applicable. There can be only one record per bill unit. The parameter used should be at the 0th level of the storable class.

  3. Save and close the file.

  4. Open the BRM_home/apps/load_config/pin.conf file in a text editor.

  5. Uncomment the following entry:

    - load_config validation_module libLoadValidCollections  LoadValidCollections_init
    
  6. Save and close the file.

  7. Load the updated file by running the following command:

    load_config -v config_collections_scenario_params.xml
    

    Important:

    • The load_config utility requires a configuration (pin.conf) file.

    • If you do not run the utility from the directory in which the configuration file is located, include the complete path to the file. For example,

      load_config -v BRM_home/sys/data/config/config_collections_scenario_params.xml
      

    For more information on the load_config utility, see BRM Developer's Guide.

  8. Stop and restart the CM.

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

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

    For more information on the /config/collections/scenario_params object, see BRM Storable Class Reference.

Increasing the Size of the CM Cache for Scenario Data

When evaluating scenarios, you might need to increase the space allocated to the scenario data in the CM cache.

To increase the CM cache size for scenario data:

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

  2. Increase cache_size in the following entry:

    - cm_cache fm_collections_config_scenario_cache number_of_entries, cache_size, hash_size
    

    Note:

    The default is 40960 bytes.

    If the file does not have this entry, add it.

  3. Save and close the file.

  4. Stop and restart the CM.

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

Assigning Collections Personnel Roles

If you use Collections Center to manage collections activity, you need to assign personnel roles to collections agents and collections managers. You assign collections roles in Collections Configuration. The tasks that collections personnel can perform and the information they can see depend on their role.

Collections Configuration displays a list of all CSR accounts. You select the accounts that should have a collections role.

See "Creating a Customer Service Representative Account" in BRM System Administrator's Guide for more information about CSR accounts. The login permissions defined for each CSR account determine which brands the collections agents and collections managers have access to. See "Setting Up Access to Brands" in BRM System Administrator's Guide.

See the Collections Configuration Help for detailed instructions about assigning collections personnel roles.

Setting Dunning Letter Delivery Preferences for Non-Invoice Bill Units

You specify how to deliver dunning letters to non-invoice bill units by using the pin_collections configuration file (BRM_home/apps/pin_collections/pin.conf).

For non-invoice bill units, you can set the following delivery options:

  • Whether to deliver the dunning letter as hardcopy or by email.

  • For email delivery, whether to send the dunning letter as part of the message body or as an attachment.

  • For dunning letters sent as email attachments, the file path to use for providing customized content in the email body.

    Note:

    To set delivery options for invoice bill units, use Customer Center.

Setting the Delivery Option

By default, dunning letters are printed and sent as hardcopy.

To set the delivery option for dunning letters:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor.

  2. Change the value of the delivery_preference entry:

    • To deliver dunning letters as hardcopy, enter a non-zero value. This is the default.

    • To deliver dunning letters by email, enter 0.

      For example:

      - pin_collections_send_dunning delivery_preference 0
      
  3. Save and close the file.

Setting the Email Delivery Preference

By default, dunning letters are delivered in the body of the email.

To set the email delivery preference for dunning letters:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor.

  2. Change the value of the email_option entry:

    • To deliver dunning letters as email attachments, enter 1.

    • To deliver dunning letters in the email body, enter 0. This is the default.

      For example:

      - pin_collections_send_dunning email_option 0
      
  3. Save and close the file.

Specifying a File for the Email Body

When you send dunning letters as email attachments, you can include customized information in the email body. You specify the path to a text file for the content of the message.

To specify the path to the message content:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor.

  2. Set the path in the email_body entry:

    - pin_collections_send_dunning email_body Path
    

    For example, the following entry specifies the path to the letter file:

    - pin_collections_send_dunning email_body ./letter
    

    Important:

    This option takes effect only if email_option is set to 1.
  3. Save and close the file.

Configuring How Collections Manager Determines Dates

You can configure how Collections Manager determines the overdue and entry dates it uses (described in Table 3-2). For information about how Collections Manager uses these dates, see "About Overdue and Entry Dates".

Table 3-2 Overdue and Entry Dates

Option Description

Overdue date

  • (Default) The overdue date is the due date of the latest overdue bill when the bill unit enters collections. This date is not updated as long as the bill remains in collections.

  • The overdue date is the due date of the oldest overdue bill when the bill unit enters collections, even if the overdue balance from that bill is not sufficient by itself to meet a scenario's entry criteria.

See "Configuring the Overdue Date" for instructions.

Entry date

  • (Default) The entry date is the overdue date plus the number of days specified in the entry criteria of the scenario. This date is updated if the overdue date changes.

  • The entry date is the actual date on which a bill unit is processed and enters collections. This date is not updated as long as the bill unit remains in collections. If Collections Manager is run at irregular or long intervals with this setting, the entry date can differ significantly from the overdue date.

See "Configuring the Entry Date" for instructions.


The following examples illustrate overdue and entry dates based on the four possible combinations of configuration options. The examples are based on the following assumptions:

  • There is a monthly charge of $15, due on the 15th of the month.

  • The collections scenario specifies a minimum overdue balance of $20, at least 10 days late.

  • No payments are received in January, February, or March, but a $15 payment is received before the due date in April.

  • Collections Manager runs every day.

  • The tables show the overdue and entry dates as of the end of each month.

Case 1: Default Settings for Both Dates

Table 3-3 shows the results of the default setting for both dates. The overdue and entry dates stay the same as long as the bill unit remains in collections.

Table 3-3 Default Date Example

Option Jan. Feb. Mar. Apr.

Payment received

None

None

None

15.00

Overdue amount

15.00

30.00

45.00

45.00

Overdue date

None

Feb. 15

Feb. 15

Feb. 15

Entry date

None

Feb. 25

Feb. 25

Feb. 25


Case 2: Optional Settings for Both Dates

Table 3-4 shows the results of the optional setting for both dates. When the bill unit enters collections, the overdue date is January 15 even though the overdue balance for that month was not sufficient by itself to enter the scenario. Also note that the overdue date changes when a payment eliminates the overdue balance for January.

Table 3-4 Optional Date Example

Option Jan. Feb. Mar. Apr.

Payment received

None

None

None

15.00

Overdue amount

15.00

30.00

45.00

45.00

Overdue date

None

Jan. 15

Jan. 15

Feb. 15

Entry date

None

Feb. 25

Feb. 25

Feb. 25


Case 3: Default Setting for Overdue Date and Optional Setting for Entry Date

In Table 3-5, the dates are identical with those for Case 1, but the entry date is determined by the actual processing date. If the collections process was not run daily, the entry date would not necessarily be the same as the date determined by the scenario's entry criteria.

Table 3-5 Processing Date Example

Option Jan. Feb. Mar. Apr.

Payment received

None

None

None

15.00

Overdue amount

15.00

30.00

45.00

45.00

Overdue date

None

Feb. 15

Feb. 15

Feb. 15

Entry date

None

Feb. 25

Feb. 25

Feb. 25


Case 4: Optional Setting for Overdue Date and Default Setting for Entry Date

In Table 3-6, the entry date changes when the overdue date is updated to reflect the payment. This would have the effect of delaying any remaining collections actions defined in the scenario.

Table 3-6 Varied Date Settings

Option Jan. Feb. Mar. Apr.

Payment received

None

None

None

15.00

Overdue amount

15.00

30.00

45.00

45.00

Overdue date

None

Jan. 15

Jan. 15

Feb. 15

Entry date

None

Jan. 25

Jan. 25

Feb. 25


Configuring the Overdue Date

To configure how Collections Manager determines the overdue date:

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

  2. Change the value of the old_overdue_behavior entry:

    • To use the latest overdue bill date, enter 0. This is the default.

    • To use the earliest overdue bill date, enter 1.

      For example:

      - fm_collections old_overdue_behavior 1
      
  3. Save and close the file.

  4. Stop and restart the CM.

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

Configuring the Entry Date

To determine how Collections Manager determines the entry date:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor.

  2. Change the value of the use_current_time entry:

    • To use the entry date, enter 0. This is the default.

    • To use the current date, enter 1.

      For example:

      - pin_collections_process use_current_time 1
      
  3. Save and close the file.

Integrating Collections Manager with Custom Client Applications

To enable a custom client application to manage collections activities:

Sending Collections Notifications to Custom Client Applications

To configure BRM to send collections notifications:

  1. Install the EAI Framework on your system. See "Integrating BRM With Enterprise Applications" in BRM Developer's Guide.

  2. Install the Synchronization Queue DM on your system. See "Installing and Configuring the Synchronization Queue DM" in BRM Synchronization Queue Manager.

  3. Configure the Synchronization Queue DM to publish the CollectionsAction business event to the database queue by doing the following:

    • Merge the BRM_home/sys/eai_js/payloadconfig_collections.xml file with your existing EAI payload configuration file.

    • Verify that the BRM_home/sys/eai_js/Infranet.properties file points to the correct EAI payload configuration file. You set the path and file name in the infranet.eai.configFile entry.

    • Merge the BRM_home/sys/data/config/pin_notify_collections file with your existing BRM_home/sys/data/config/pin_notify file. Load the merged file into the database by using the load_pin_notify utility.

    • Uncomment the CollectionsAction business event in your BRM_home/sys/dm_aq/aq_queuenames file.

    For more information, see "Installing and Configuring the Synchronization Queue DM" in BRM Synchronization Queue Manager.

  4. Start the Synchronization Queue DM.

    See "Starting and Stopping the Synchronization Queue DM" in BRM Synchronization Queue Manager.

BRM publishes the CollectionsAction business event to the database queue whenever an /event/audit/collections/action notification event occurs.

Using the Collections Manager API

You can add the following functionality to your custom client application by using the Collections Manager API:

Managing Overdue Balance Collection

Collections Configuration calls the following opcodes to configure collections scenarios, actions, and profiles and to configure user roles for collections personnel. To add this functionality to a custom client application, customize it to accept the information required by the target opcode's input flist and pass it to the appropriate opcode:

Creating or Updating Collections Actions

Use the PCM_OP_COLLECTIONS_CONFIG_SET_ACTION opcode to create or update a collections action.

Collections Configuration calls this opcode when a user creates a new action or modifies an existing action.

As input, this opcode takes the POID of the /config/collections/action object to create or update and it takes the action's name and type. This opcode uses the POID ID to determine whether to create a new action object or update an existing action object:

  • If the PIN_FLD_POID field is set to -1, this opcode creates a new /config/collections/action object.

  • If the PIN_FLD_POID field is set to the POID of an existing action object, this opcode updates the object.

This opcode stops processing if the POID of the /config/collections/action object in the input flist is missing or invalid.

If successful, this opcode returns the POID of the /config/collections/action object that was created or updated.

Creating or Updating Collections Profiles

Use the PCM_OP_COLLECTIONS_CONFIG_SET_PROFILE opcode to create or update a collections profile.

Collections Configuration calls this opcode when a user creates or modifies a profile.

As input, this opcode takes the POID of the /config/collections/profile object to create or update and it takes the profile's name, description, and the currency used for the profile. This opcode uses the POID ID to determine whether to create a new profile object or update an existing profile object:

  • If the PIN_FLD_POID field is set to -1, this opcode creates a new /config/collections/profile object.

  • If the PIN_FLD_POID field is set to the POID of an existing profile object, this opcode updates the object.

This opcode stops processing if the POID of the /config/collections/profile object in the input flist is missing or invalid.

If this opcode fails, it returns an error in the error buffer.

If successful, this opcode returns the POID of the /config/collections/profile object that was created or updated.

Getting All Currently Defined Collections Actions

Use the PCM_OP_COLLECTIONS_CONFIG_GET_ACTIONS opcode to get a list of all currently defined collections actions.

Collections Configuration calls this opcode to retrieve a list of actions and their definitions.

As input, this opcode takes a dummy POID used to get the database ID. This opcode then searches the database for the /config/collections/action object that contains definitions of collections actions. The object is created when new actions are defined in Collections Configuration.

If this opcode fails, it returns an error in the error buffer.

If successful, this opcode returns a results array that contains the POID, name, description, and type of the actions returned. It also returns the PIN_FLD_OPCODE field, which shows the opcode to use to execute the actions. If any action involves sending a dunning letter, the output flist returns the POID of the template used by this action.

Getting All Currently Defined Collections Profiles

Use the PCM_OP_COLLECTIONS_CONFIG_GET_PROFILES opcode to retrieve a list of currently defined collections profiles.

Collections Configuration calls this opcode to display all currently defined profiles.

As input, this opcode takes a dummy POID used to get the database ID. This opcode then searches the database for the /config/collections/profile object. This object is created when a new collections profile is defined in Collections Configuration.

If this opcode fails, it returns an error in the error buffer.

If successful, this opcode returns a results array that contains the POID, name, description, and the currency used for each profile found.

Getting All Currently Defined Collections Scenarios

Use the PCM_OP_COLLECTIONS_CONFIG_GET_SCENARIOS opcode to get a list of all collections scenarios and associated profiles in the current brand.

Collections Configuration calls this opcode to list all currently defined scenarios and profiles.

As input, this opcode takes a dummy POID used to get the database ID. This opcode then searches the database for the /config/collections/scenario object. This object is created when a new collections scenario is defined in Collections Configuration.

This opcode also retrieves the /config/collections/profile object, which contains definitions of profiles that are associated with scenarios.

If this opcode fails, it returns an error in the error buffer.

If successful, this opcode returns a results array that contains the POID and name of each scenario and the POID of the brand to which each scenario belongs. It also returns the POID and name of the profile associated with each scenario.

Getting Details of a Collections Scenario

Use the PCM_OP_COLLECTIONS_CONFIG_GET_SCENARIO_DETAIL opcode to get details of a particular collections scenario.

Collections Configuration calls this opcode to display details of the selected scenario.

As input, this opcode takes the POID of the /config/collections/scenario object.

This opcode stops processing if the POID of the /config/collections/scenario object in the input flist is missing or invalid.

If this opcode is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns a results array that contains the POID of the /config/collections/scenario object, the name of the scenario, and the POID of the profile associated with the scenario.

It also returns an array that contains details for the action associated with the scenario, including the action object POID, name, description, type, and the PIN_FLD_OPCODE field, which shows the opcode to use to execute the action. If the action involves sending a dunning letter, the output flist returns the POID of the template used by this action.

Getting a List of Message Templates

Use the PCM_OP_COLLECTIONS_CONFIG_GET_TEMPLATES opcode to get a list of templates for the current brand.

When a user creates or updates an action that requires a template, Collections Configuration calls this opcode to display a list of available templates.

As input, this opcode takes the action type, the template's location, and a dummy POID used to get the database ID.

The opcode performs the following:

  • Reads the action type from the input flist. The PIN_FLD_ACTION_TYPE field specifies DUNNING_LETTER.

  • Reads the /config/invoice_templates/dunning objects to retrieve dunning letter templates. BRM creates these objects and automatically creates subclasses of /config/invoice_templates when loading the dunning letter templates.

If this opcode fails, it returns an error in the error buffer.

If successful, this opcode returns an array containing the POID, brand, and name of each template in the current brand that matches the locale and action type specified in the input flist.

Deleting an Existing Collections Action

Use the PCM_OP_COLLECTIONS_CONFIG_DELETE_ACTION opcode to delete an existing collections action.

Collections Configuration calls this opcode when a user deletes a collections action.

This opcode takes the POID of the /config/collections/action object to delete, verifies that the object is not used by any scenario, and deletes the object.

This opcode stops processing if:

  • The POID of the /config/collections/action object in the input flist is missing or invalid.

  • The action object is used by a scenario.

If this opcode is not successful, it sets the PIN_FLD_RESULT field to Fail in the output flist. If the scenario is in use, an appropriate message is displayed in Collections Configuration.

If successful, this opcode returns the POID of the /config/collections/action object and the PIN_FLD_RESULT field, which shows the results of the deletion.

Deleting an Existing Collections Profile

Use the PCM_OP_COLLECTIONS_CONFIG_DELETE_PROFILE opcode to delete an existing collections profile.

Note:

Users cannot delete a default profile created during the installation of Collections Configuration.

Collections Configuration calls this opcode when a user deletes a collections profile.

This opcode takes the POID of the /config/collections/profile object to delete, verifies that the object is not used by any scenario, and deletes the object.

This opcode stops processing if:

  • The POID of the /config/collections/profile object in the input flist is missing or invalid.

  • The object is used by a scenario.

If this opcode is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns the POID of the /config/collections/profile object and the PIN_FLD_RESULT field, which shows the results of the deletion.

Deleting an Existing Collections Scenario

Use the PCM_OP_COLLECTIONS_CONFIG_DELETE_SCENARIO opcode to delete an existing collections scenario.

Collections Configuration calls this opcode when a user deletes a scenario.

This opcode takes the POID of the /config/collections/scenario object to delete, verifies that the object is not used by any bill units that are currently in collections and was not used by any bill units that were previously in collections, and deletes the object.

This opcode stops processing if:

  • The POID of the /config/collections/scenario object in the input flist is missing or invalid.

  • The object is currently used by one or more bill units in collections.

  • The object was previously used by one or more bill units that entered into collections. The collections scenario cannot be deleted even after a bill unit has exited from collections because the association between the collections scenario and the collections objects still remains.

If this opcode is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns the POID of the /config/collections/scenario object and the PIN_FLD_RESULT field, which shows the results of the deletion.

Retrieving Collections Information

Collections Center calls the following opcodes to retrieve information about collections actions. To add this functionality to a custom client application, customize it to accept the information required by the target opcode's input flist and pass it to the appropriate opcode.

Retrieving a List of Bill Units in Collections

Use the PCM_OP_COLLECTIONS_GET_BILLINFOS opcode to get a list of bill units (/billinfo objects) that are in collections.

Collections Center calls this opcode to display the bill units in collections that meet the criteria defined by a CSR. The search criteria passed in by Collections Center are included in the optional fields that determine the scope of the search.

The input flist must contain a dummy POID, which is used to get the database ID for the search. To retrieve bill units based on specific criteria, you can use the following optional input:

  • The ID of the bill unit

  • The status of the bill unit

  • The payment type of the bill unit

  • A date range; this retrieves bill units whose bills were generated between the specified dates

  • The status of the account

  • The account number (PIN_FLD_ACCOUNT_NO); this narrows the search to a particular account whose bill units are in collections

  • The name of the company to which an account belongs

  • The name of the customer on the account

  • The account POID of the agent assigned to the bill units

  • The name of the collections scenario assigned to the bill units

  • The name of the collections profile associated with the bill units

  • The overdue amount range

  • The overdue days range; this narrows the search to bill units that are overdue for the specified number of days

  • A flag indicating whether to get assigned bill units or unassigned bill units

If the opcode fails, a NULL flist is returned.

If successful, this opcode returns a list of bill units that meet the search criteria and details for the fields specified on the input flist.

Note:

This opcode uses step search when searching for bill units. See "Setting the Number of Bill Units Retrieved during Step Searches" to specify the number of bill units retrieved in each step.

Retrieving Aging Buckets Information

Use the PCM_OP_COLLECTIONS_CALC_AGING_BUCKETS opcode to retrieve a bill unit's aging buckets details.

Collections Center calls this opcode when displaying the distribution of a bill unit's overdue balance over a number of aging buckets.

This opcode takes the POID of the bill unit and performs the following actions:

  • Retrieves aging bucket information, which includes the total number of buckets and the number of overdue days per bucket from the /config/collections/aging_buckets object.

  • Determines the exact number of overdue days per each aging bucket for the specified bill unit.

  • Calculates the amount due in each bucket.

This opcode stops processing if the bill unit information in the input flist is missing or invalid.

If this opcode is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns the POID of the /billinfo object, an array of the aging buckets, the number of overdue days for each bucket, and the amount due in each bucket.

Retrieving Scenario Information

Use the PCM_OP_COLLECTIONS_GET_SCENARIO_DETAIL opcode to retrieve details about a bill unit's collections scenario.

Collections Center calls this opcode to display the collections activity details that CSRs use to work with the collections actions that are scheduled for a bill unit.

This opcode takes the POID of the /collections_scenario object and performs the following actions:

  • Reads the /collections_scenario object information.

  • Retrieves a list of actions for the specified scenario.

  • Retrieves history information for each action.

This opcode stops processing if the input flist does not include a valid POID for a /collections_scenario object.

If this opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns the output flist that contains the POID of the bill unit, the POID of the scenario assigned to the bill unit, scenario details, and an array listing the POID and status of each scheduled action.

Getting All Valid Collections Scenarios

Use the PCM_OP_COLLECTIONS_GET_VALID_SCENARIOS opcode to evaluate all the collections scenarios for the bill unit using the default entry criteria (entry_amount and entry_days), the severity attribute, and additional configurable parameters and list the valid scenarios for the bill unit.

Collections Center calls this opcode to display the list of valid scenarios during scenario assignment or replacement.

This opcode takes the entry criteria (entry_amount and entry_days), the severity attribute, and additional configurable parameters and performs the following actions:

  • Searches for collections scenarios matching the criteria.

  • For each collections scenario, calls the PCM_OP_COLLECTIONS_POL_GET_VALID_SCENARIOS policy opcode. The policy opcode takes the scenario as input, reads the /config/collections/scenario_params object for the additional parameters, and validates whether the scenario is valid for the bill unit in collections. The valid collections scenario is added to the list of valid collections scenarios. If the collections scenario is not valid, the policy opcode evaluates the next collections scenario.

  • Returns a list of all the valid scenarios.

Retrieving a List of Collections Actions

Use the PCM_OP_COLLECTIONS_GET_AGENTS_ACTIONS opcode to retrieve a list of collections actions assigned to collections agents.

Collections Center calls this opcode when collections managers request an overview of the workload for the collections agents they supervise.

The input flist contains the following:

  • The agent's account POID. This returns a list of actions that are currently assigned to the specified agent. If you specify the account POID as type-only, this opcode retrieves the actions for all collections agents.

  • PIN_FLD_START_T and PIN_FLD_END_T are optional. You specify one of these fields to limit the actions returned to those that are due either after the start time or before the end time.

  • The PIN_FLD_THRESHOLD field specifies the number of actions to retrieve. The default is all actions.

This opcode returns an array of details for the collections action. The return data includes the agent's name and account POID, the POID of the action object, the action's name and due date, and the opcode to execute for the action.

Note:

This opcode uses step search when searching for bill units. See "Setting the Number of Bill Units Retrieved during Step Searches" to specify the number of bill units retrieved in each step.

Retrieving Collections Action History Information

Use the PCM_OP_COLLECTIONS_GET_ACTION_HISTORY opcode to find past information about a particular collections action.

Collections Center calls this opcode to display details about when an action was assigned to a collections agent, reassigned, rescheduled, and so on.

As input, this opcode takes the POID of the /collections_action object for which to retrieve historic data.

This opcode stops processing when the input flist does not include a valid POID for a /collections_action object.

If this opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns the POID of the /collections_action object and a results array with history details for the collections action. The array includes the action's status and due date, the assigned agent's name and account POID, the date when the last change occurred, and the description of the change.

Performing System Collections Actions

Collections Manager performs a variety of actions on bill units with overdue balances. Some actions happen automatically, and others require manual intervention.

Automatic actions are performed by the system. They include calculating overdue balances, applying late fees, and updating bill unit balances.

Collections Manager uses the following opcodes to perform system actions on the bill units in collections:

Executing Automatic Collections Actions

Use the PCM_OP_COLLECTIONS_PROCESS_BILLINFO opcode to:

  • Determine whether an account's bill unit should enter or exit the collections process.

  • Perform collections actions, such as sending notices to customers or applying late charges.

The pin_collections_process utility calls this opcode for each bill unit with an overdue balance that meets a minimum amount (see "Setting the Minimum Overdue Balance to Process"). This opcode then processes each bill unit to evaluate its collections status and perform any necessary collections actions.

When this opcode receives a bill unit, it performs the following actions:

  • Calculates the exact overdue balance and days late for the bill unit.

  • Checks the bill unit's current collections status.

    If the bill unit is not in collections, this opcode:

    • Calls the PCM_OP_COLLECTIONS_POL_SELECT_PROFILE policy opcode to assign the bill unit to a collections profile. See "Mapping Bill Units to Collections Profiles".

    • Maps the collections profile to a collections scenario.

    • Creates a /collections_scenario object and a /collections_action object for each collections activity that needs to be performed.

    • Sets the status of all actions in the collections scenario. If collections action dependencies are enabled, sets the first action's status to Pending and all subsequent actions' status to Waiting For Dependents. If multiple actions are scheduled for the first due date, sets the status of those actions to Pending and sets the status of actions scheduled for later due dates to Waiting For Dependents.

      If collections action dependencies are disabled, sets the status of all actions to Pending. See "Creating Dependencies between Collections Actions in a Scenario".

    • Generates the /event/audit/collections/action notification event.

    • Calls the PCM_OP_COLLECTIONS_POL_ASSIGN_AGENT policy opcode to assign a collections agent to the bill unit. See "Assigning Bill Units Automatically".

    If the bill unit is already in collections, this opcode sets the bill unit's action status to REMAIN_IN and updates the bill unit's overdue balance and days late.

  • Determines whether the bill unit meets the exit criteria:

    If it meets the exit criteria, this opcode changes the bill unit's action status to Completed, generates the /event/audit/collections/action notification event, and calls the PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO policy opcode to perform any custom actions that you specify. (See "Performing Custom Actions when a Bill Unit Leaves Collections".) Processing is complete.

    If it does not meet the exit criteria, this opcode:

    • Finds all of the bill unit's actions that are set to Pending.

    • If a manual action is required, generates the /event/audit/collections/action notification event. Processing is complete.

    • If a system or custom action is required, calls the PCM_OP_COLLECTIONS_TAKE_ACTION opcode to execute the action. See "Executing Pending Actions for a Bill Unit".

  • Evaluates the bill unit to determine if it now meets the exit criteria for the scenario:

    If the bill unit does not meet the exit criteria, processing ends for this bill unit.

    If the bill unit does meet the exit criteria, this opcode:

Preparing Invoice Reminders

Use the PCM_OP_COLLECTIONS_SET_INVOICE_REMINDER opcode to prepare a reminder message for customers with overdue payments. This message is later added to your invoices or custom documents via the Universal Message Store (UMS) framework. See "Using BRM Messaging Services" in BRM Developer's Guide.

This opcode is called by the PCM_OP_COLLECTIONS_PROCESS_BILLINFO opcode when a collections scenario calls for an invoice reminder.

This opcode performs the following actions:

  • Calls PCM_OP_UMS_SET_MESSAGE to create a /message object.

  • Returns the POID of the /collections_action/invoice_reminder object and the status to PCM_OP_COLLECTIONS_PROCESS_BILLINFO.

Gathering and Storing Data for Dunning Letters

Use the PCM_OP_COLLECTIONS_SET_DUNNING_LETTER opcode to gather and store data for dunning letters.

This opcode is called by the PCM_OP_COLLECTIONS_TAKE_ACTION opcode when a collections scenario requires a dunning letter.

This opcode performs the following actions:

  • Calls the PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA policy opcode to retrieve data for the dunning letter and to perform any customizations that you implement. See "Customizing Dunning Letters".

  • Converts the data into XML format and saves it as a buffer field in the /collections_action/dunning_letter object for this letter.

  • Returns the POID of the /collections_action/dunning_letter object and the status to the PCM_OP_COLLECTIONS_PROCESS_BILLINFO opcode.

Retrieving Dunning Letters

Use the PCM_OP_COLLECTIONS_GET_DUNNING_LETTER opcode to retrieve dunning letters from the BRM database.

This opcode is called directly by the pin_collections_send_dunning utility.

This opcode performs the following actions:

  • Retrieves the /collections_action/dunning_letter object from the BRM database. This object contains the XML data to be included in the letter.

  • Retrieves the /config/invoice_templates/dunning object from the BRM database. This object contains the XSLT style sheet used to format the dunning letter.

    Note:

    Dunning letter templates are stored as /config/invoice_templates/dunning objects. The /config/invoice_templates class is automatically subclassed when you load a dunning letter template.
  • Calls the PCM_OP_INV_FORMAT_INVOICE opcode to create the final dunning letter.

Executing Pending Actions for a Bill Unit

Use the PCM_OP_COLLECTIONS_TAKE_ACTION opcode to execute pending actions for a bill unit.

This opcode is called by either the PCM_OP_COLLECTIONS_PROCESS_BILLINFO opcode or the pin_deferred_act utility to execute actions.

As input, this opcode takes the POID of the action to execute, the POID of the bill unit to process, and the POID of the account that owns the bill unit. This opcode then determines the type of action that needs to be executed:

Then, this opcode sets the action's status to Completed and updates the bill unit's overdue date and overdue amount. This opcode generates an /event/audit/collections/action notification event.

If collections action dependencies are enabled, this opcode also changes the subsequent action's status from Waiting For Dependents to Pending and reschedules the due dates of any outstanding collections actions in the scenario.

Note:

If multiple actions are scheduled for the same day and are all set to Pending, this opcode waits until all of those actions are completed or canceled before changing the subsequent action's status from Waiting For Dependents to Pending.

If this opcode is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns the POID of the /collections_action object for this action and the status of action.

Passing Information to Custom Client Applications

Use the PCM_OP_COLLECTIONS_PUBLISH_EVENT opcode to append additional information to the /event/audit/collections/action notification event before it is passed to your custom client application.

This opcode is called by the event notification system whenever the /event/audit/collections/action notification event occurs.

This opcode calls the PCM_OP_COLLECTIONS_POL_PUBLISH_EVENT policy opcode and then publishes the notification event to the Payload Generator External Module (EM).

For information about the PCM_OP_COLLECTIONS_POL_PUBLISH_EVENT policy opcode, see "Adding Information that Is Passed to Custom Client Applications".

Performing Manual Collections Actions

Collections Manager performs a variety of actions on bill units with overdue balances. Some actions happen automatically; others require manual intervention.

Manual actions are performed by collections agents or collections managers who use Collections Center to work with bill units. The actions include adding actions to a bill unit scenario, exempting bill units from collections, and assigning bill units to agents. You can configure your client application to call the opcodes to execute manual actions.

Collections Center calls the following opcodes after a manual action is performed. To enable your custom client application to update Collections Manager after manual actions occur, customize it to accept the information required by the target opcode's input flist and pass the information to the target opcode.

Assigning Bill Units to a Collections Agent

Use the PCM_OP_COLLECTIONS_ASSIGN_AGENT opcode to assign bill units to a collections agent.

Collections Center calls this opcode when a collections manager assigns a bill unit to a particular agent.

This opcode takes as input the POID of the agent's account and the PIN_FLD_BILLINFO array, which specifies the bill units to assign to the agent.

This opcode performs the following actions:

  • Assigns each bill unit in the PIN_FLD_BILLINFO array to the agent.

  • Updates bill unit scenarios with the agent's account POID.

  • Returns the account POID of the agent responsible for the bill units and an array of the bill units assigned to the specified agent.

This opcode stops processing if the bill unit information in the input flist is missing or invalid.

If this opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back.

If successful, this opcode returns the account POID of the agent responsible for the bill units and an array of the bill units assigned to the agent.

Adding Actions to a Collections Scenario

Use the PCM_OP_COLLECTIONS_ADD_ACTION opcode to add collections actions to a bill unit's collections scenario.

Collections Center calls this opcode when CSRs add actions to a collections scenario.

This opcode takes as input a dummy POID, the /collections_scenario POID, the CSR's login account POID, the new action object's POID, and the action's due date.

This opcode performs the following actions:

  • Checks the CSR account POID to make sure the user is authorized to add actions.

  • Adds a new action to a scenario and updates the output flist with the new action POID.

  • Sets the new action's status. If collections action dependencies are enabled, checks whether the subsequent action's status is set to Pending. If so, sets the new action's status to Pending and updates the subsequent action's status to Waiting For Dependents. If not, sets the new action's status to Waiting For Dependents.

    Note:

    Actions cannot be inserted before, between, or on the same day as any canceled or completed actions.
  • Checks to see if the PIN_FLD_DAYS field is present in the input flist. If so, this opcode checks the contents of the field to determine whether the actions that follow need to be rescheduled.

    • If PIN_FLD_DAYS is equal to 0, the actions are not rescheduled.

    • If PIN_FLD_DAYS is less than 0, the actions are canceled.

    • If PIN_FLD_DAYS is greater than 0, the value specified indicates the number of days the actions will be delayed.

  • Checks to see if the type of collections action is Collect Payment and the Credit Card or Debit Card credentials are specified and does the following:

    • Creates a /payinfo object with the credentials in the input flist.

    • Creates the /collections_action/collect_payment action to hold the amount to be paid and a link to /payinfo object.

  • Checks to see if the type of collections action is Promise to Pay and does the following:

    • Validates if the promise-to-pay agreement is already called for the bill unit and the due date is not before INVOKE_T of the active promise.

    • Updates the outstanding amount under the /collections_scenario object with the amount for the new payment milestone.

  • Updates the output flist with the new data for each rescheduled action.

This opcode stops processing if:

  • The CSR account POID does not match the POID of a user who has permission to add actions.

  • The action information in the input flist is missing or invalid.

If this opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back.

If successful, this opcode returns PIN_FLD_POID set to the POID of the new action added and updates the output flist with the new data for each rescheduled action.

Exempting Bill Units from Collections

Use the PCM_OP_COLLECTIONS_EXEMPT_BILLINFO opcode to exempt bill units from collections.

Collections Center calls this opcode when a CSR exempts a bill unit from collections.

This opcode takes as input the POID of the bill unit to exempt from collections and the POID of the account that owns the bill unit.

If the bill unit is already in collections, this opcode performs the following actions:

  • Calls the PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO policy opcode to remove the bill unit from the scenario.

  • Cancels all pending and error actions scheduled for this bill unit.

  • Sets the bill unit's PIN_FLD_SCENARIO_OBJ field to NULL to indicate that this bill unit is not in collections.

  • Sets the exemption flag so that the bill unit never enters collections, even if it has an overdue balance.

If the bill unit is not in collections, this opcode sets the exemption flag so that the bill unit never enters collections, even if it has an overdue balance.

This opcode stops processing if the input flist does not include a valid bill unit POID.

If this opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure.

If successful, this opcode returns the POID of the exempted /billinfo object and the POID of the account to which the bill unit belongs.

Rescheduling an Action Scheduled for a Bill Unit

Use the PCM_OP_COLLECTIONS_RESCHEDULE_ACTION opcode to reschedule an action that was scheduled by a bill unit's collections scenario.

Collections Center calls this opcode when a CSR reschedules a particular action to be performed on a bill unit. For example, if a customer promises payment by a certain day, the CSR can reschedule the inactivation of the bill unit.

This opcode takes as input the POID of the action to be rescheduled, the account POID of the CSR that is rescheduling the action, and the new due date for the action.

This opcode performs the following actions:

  • Checks the account POID to verify that the CSR is authorized to reschedule the action. If the account POID matches the account of the agent who originally scheduled the action or if it is the account of a manager, the opcode allows rescheduling.

  • Reads the PIN_FLD_DUE_T input field to obtain a new due date for the action.

  • Checks to see if the PIN_FLD_DAYS field is present in the input flist. If so, this field determines whether the actions that follow are postponed.

    • If PIN_FLD_DAYS is equal to 0, the actions are not postponed.

    • If PIN_FLD_DAYS is less than 0, the actions are canceled.

    • If PIN_FLD_DAYS is greater than 0, the value indicates the number of days to postpone the actions.

  • Updates the output flist with the new data for each action.

This opcode stops processing if:

  • The CSR's account POID does not match the POID of an authorized user.

  • The action information in the input flist is missing or invalid.

If this opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back.

If successful, this opcode returns the POID of the rescheduled action and updates the output flist with the new data for each action affected by the rescheduling.

Changing the Status of a Collections Action

Use the PCM_OP_COLLECTIONS_SET_ACTION_STATUS opcode to change the status of a manual collections action.

Collections Center calls this opcode when a CSR updates the status of a manual action. For example, after finishing a phone call, an agent must update the action's status to Completed.

This opcode takes as input the POID of the action object and the new status for the action.

If collections action dependencies are enabled, this opcode performs the following actions:

  • Checks whether the action's current status is set to Pending. If so, it changes the current action's status and then updates the subsequent action's status from Waiting For Dependents to Pending. If not, it generates an error.

  • If the action's status is changed to Cancelled, checks the value of the PIN_FLD_FLAGS flist field and the /collections_action object's PIN_FLD_ACTION_MODE field:

    • If PIN_FLD_ACTION_MODE is set to 0, the action is mandatory. The action cannot be canceled and system actions cannot be completed from Collections Center. The opcode generates an error.

    • If PIN_FLD_ACTION_MODE is set to 1 and PIN_FLD_FLAGS is set to 0, the opcode changes the action's status to Cancelled.

    • If PIN_FLD_ACTION_MODE is set to 1 and PIN_FLD_FLAGS is set to 1, the opcode changes the action's status to Cancelled and the status of all actions that follow to Cancelled.

  • If the action's status is changed to Completed, checks the status of the PIN_FLD_FLAGS flist field:

    • If it is set to 0, the opcode changes the action's status to Completed and reschedules the due dates of all outstanding actions in the scenario.

    • If it is set to 2, the opcode changes the action's status to Completed and leaves the due dates of all outstanding actions unchanged.

If collections action dependences are disabled:

  • Changes the current action's status.

  • If the action status is changed to Cancelled, checks the value of the PIN_FLD_FLAGS flist field:

    • If it is set to 0, the opcode changes the action's status to Cancelled.

    • If it is set to 1, the opcode changes the action's status to Cancelled and the status of all actions that follow to Cancelled.

This opcode stops processing if the POID of an action is missing or invalid.

If this opcode stops processing, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back.

If successful, this opcode returns the POID of the action whose status was changed.

Replacing a Collections Scenario

Use the PCM_OP_COLLECTIONS_REPLACE_SCENARIO opcode to replace the existing collections scenario for a bill unit with a new collections scenario. You can replace the scenario of a bill unit that is already in collections.

Collections Configuration calls this opcode to replace the scenario of a bill unit that is already in collections.

As input, this opcode takes the POID of the bill unit already in collections.

This opcode creates the /event/activity/collections/replace_scenario activity event object to store the bill unit details such as the bill unit POID, the current collections scenario POID, and the new collections scenario POID. If the new collections scenario object is not specified, this opcode calls the PCM_OP_COLLECTIONS_GET_VALID_SCENARIOS opcode to get a list of all the valid collections scenarios applicable for the bill unit.

After the new scenario is identified, this opcode exits out of the existing collections scenario, cancels all the pending actions, deletes the scheduled objects for the pending actions, and updates the bill unit with the POID of the new collections scenario.

Managing Collections Sharing Groups

Customer Center calls the following opcodes to group bill units into a collections sharing group. For more information, see "About Collections Sharing Groups". To add this functionality to a custom client application, customize it to accept the information required by the target opcode's input flist and pass it to the appropriate opcode:

Creating a Collections Sharing Group

Use the PCM_OP_COLLECTIONS_GROUP_CREATE opcode to group bill units into a collections sharing group.

This opcode is called directly by Customer Center.

This opcode takes as input the /account POID and the /billinfo POID of the group owner, the /billinfo POIDs of the members of the group, and the name of the collections sharing group.

This opcode performs the following actions:

  • Validates that the parent bill unit is not already a parent or member of another collections sharing group.

  • Calls the PCM_OP_GROUP_CREATE_GROUP opcode to create the /group/collections_targets object. When a group is created, events are created.

    The /event/group/collections_targets event contains details of a parent and members in the PIN_FLD_MEMBERS array.

    The /event/group/parent event contains details of a parent.

  • Calls the PCM_OP_GROUP_ADD_MEMBER opcode to add members to the /group/collections_targets object.

If the opcode fails, it returns an error in the error buffer. The transaction is rolled back.

If successful, this opcode returns the POID of the /group/collections_targets object.

Adding Members to a Collections Sharing Group

Use the PCM_OP_COLLECTIONS_GROUP_ADD_MEMBER opcode to add a child member to an existing collections sharing group.

This opcode is called directly by Customer Center.

This opcode takes as input the POID of the /group/collections_targets object, the /billinfo POID of the new member, and the name of the collections sharing group.

This opcode performs the following actions:

  • Validates that the new child member is not a parent or member of the existing collections sharing group.

  • Calls the PCM_OP_GROUP_ADD_MEMBER opcode to add the bill unit to the /group/collections_targets object.

If the opcode fails, it returns an error in the error buffer. The transaction is rolled back.

If successful, this opcode returns the POID of the /group/collections_targets object.

Removing a Member from a Collections Sharing Group

Use the PCM_OP_COLLECTIONS_GROUP_DELETE_MEMBER opcode to remove a member from an existing collections sharing group.

This opcode is called directly by Customer Center.

This opcode takes as input the POID of the /group/collections_targets object and the POID of the /billinfo object to remove the member, and returns the POID of the /group/collections_targets object.

Deleting a Collections Sharing Group

Use the PCM_OP_COLLECTIONS_GROUP_DELETE opcode to delete an existing collections sharing group.

This opcode is called directly by Customer Center.

This opcode takes as input the POID of the /group/collections_targets object to delete, calls PCM_OP_GROUP_DELETE_GROUP opcode to delete the specified object, and returns the POID of the /group/collections_targets object.

If the collections group is already in collections, the opcode throws an error.

Retrieving a Collections Sharing Group

Use the PCM_OP_COLLECTIONS_GROUP_GET_BILLINFO opcode to retrieve:

  • Whether the specified bill unit is a member of a collections sharing group.

  • The pending receivables for each bill unit. If a bill unit is a parent of a collections sharing group, it also provides the name of the collections sharing group and its child member bill units.

This opcode is called directly by Collections Center.

This opcode takes as input the /account or /billinfo POID and performs the following actions:

  • If the /billinfo POID is not passed in, retrieves all /billinfo objects associated with the /account object.

  • For each /billinfo object, reads the associated /group/collections_targets object to determine whether the bill unit belongs to a collections sharing group and, if it does, whether it is a parent bill unit or a child bill unit.

    • If it is not a member of a collections sharing group, returns the /group/collections_targets POID and the PIN_FLD_BOOLEAN field set to 0.

    • If it is a child in a collections sharing group, returns the /group/collections_targets POID and the PIN_FLD_BOOLEAN field set to 1.

    • If it is a parent in a collections sharing group, returns the /group/collections_targets POID, the PIN_FLD_BOOLEAN field set to 1, and the pending receivables of all group members.

Modifying a Collections Sharing Group

Use the PCM_OP_COLLECTIONS_GROUP_MODIFY opcode to modify an existing collections sharing group, such as renaming the collections sharing group, changing the parent member, and replacing all of the existing child members.

This opcode is called directly by Customer Center.

This opcode takes as input the POID of the /group/collections_targets object and the information to change, modifies the collections sharing group, and returns the POID of the /group/collections_targets object.

Changing the Parent of a Collections Sharing Group

Use the PCM_OP_COLLECTIONS_GROUP_SET_PARENT opcode to change a collections sharing group's existing parent bill unit.

This opcode is called directly by Customer Center.

This opcode takes as input the POID of the /group/collections_targets object, the name of the calling program, and the POID of the new parent bill unit.

This opcode performs the following actions:

  • Validates that the new parent bill unit is not a child of the existing collections sharing group.

  • Validates that the new parent bill unit is not already a parent of another collections sharing group.

  • Calls the PCM_OP_GROUP_SET_PARENT opcode to assign the new parent bill unit to the /group/collections_targets object.

If the opcode fails, it returns an error in the error buffer. The transaction is rolled back.

If successful, this opcode returns the POID of the /group/collections_targets object.

Configuring Promise-to-Pay Agreements

Collections Center calls the following opcodes to configure the promise-to-pay agreements. To add this functionality to a custom client application, customize it to accept the information required by the target opcode's input flist and pass it to the appropriate opcode.

Creating a Promise-to-Pay Action

For a bill unit (/billinfo object) that is already in collections, use the PCM_OP_COLLECTIONS_INVOKE_PROMISE_TO_PAY opcode to create the promise-to-pay action.

This opcode calls the PCM_OP_COLLECTIONS_POL_INVOKE_PROMISE_TO_PAY policy opcode. By default, this policy opcode is an empty hook.

Collections Center calls this opcode when a customer requests a promise-to-pay agreement for a bill unit that is in collections.

This opcode takes as input:

  • The number of payment milestones (PIN_FLD_NUM_MILESTONES) or the amount per milestone (PIN_FLD_MILESTONE_AMOUNT).

  • The total number of days during which the full outstanding amount will be paid off (PIN_FLD_DAYS) or the interval in days between each payment milestone (PIN_FLD_MILESTONE_INTERVAL).

  • (Optional) The date for the first payment milestone. If this is not specified, the current date is used.

This opcode performs the following actions:

  • Creates /collections_action/promise_to_pay actions for the payment milestones and updates the action due dates and milestone amounts. This /promise_to_pay action is attached to the existing scenario.

  • Reschedules the pending collections actions by one day after the last milestone due date.

  • Generates an /event/audit/collections/actions audit event to record the promise-to-pay details.

You can add additional milestones and collect_payment actions to an existing collections scenario using Collections Center.

Updating Amount and Payment Details

Use the PCM_OP_COLLECTIONS_UPDATE_ACTION_PAYMENT_DETAILS opcode to update the amount and payment details for a collections action.

Collections Center calls this opcode to update the amount and payment details for the Promise to Pay and Collect Payment actions.

If the input action type is Promise to Pay and the amount details are updated, the opcode updates the total outstanding amount in the /collections_scenario object with the difference amount.

If the input action type is Promise to Pay and the payment details are updated, depending on the option whether the updated details is applicable only to the current installment or includes the next installments, the opcode updates the details.

When calling this opcode, send only the data that needs to be updated. For example, in a scenario where only the amount details should be updated, if the payment details are also sent in the input flist with NULL values, the opcode updates the payment details of the current action with the NULL values.

Revoking a Promise-to-Pay Agreement

Use the PCM_OP_COLLECTIONS_REVOKE_PROMISE_TO_PAY opcode to revoke the promise-to-pay agreement.

Collections Center calls this opcode when the customer cancels the promise-to-pay agreement.

As input, this opcode takes the POID of the /event/activity/collections/promise_to_pay object and performs the following actions:

  • Cancels the outstanding payment milestones and deletes the corresponding schedule objects.

  • Reschedules the scenario actions to start from the next day and updates the corresponding schedule objects.

  • Removes the reference of /event/activity/collections/promise_to_pay object from the collections scenario object.

Rescheduling a Promise-to-Pay Action

Use the PCM_OP_COLLECTIONS_RESCHEDULE_ACTION opcode to reschedule a Promise to Pay action that was scheduled by a bill unit's collections scenario.

See "Rescheduling an Action Scheduled for a Bill Unit" for more information about rescheduling an action.

Changing the Status of a Promise-to-Pay Action

Use the PCM_OP_COLLECTIONS_SET_ACTION_STATUS opcode to change the status of a Promise to Pay action.

See "Changing the Status of a Collections Action" for more information about changing the status of a promise-to-pay action.

Creating CollectionsInfoChange Business Events

If your custom application connects to BRM through Oracle Application Integration Architecture (Oracle AIA), the Oracle Advance Queue (AQ) needs to be notified with a CollectionsInfoChange business event when a collections job has run.

To create a CollectionInfoChange business event:

  1. Open the BRM_home/apps/pin_collections/pin.conf file in a text editor.

  2. Add a publish_run details entry and set it to 1:

    - pin_collections_process publish_run_details 1
    
  3. Save and close the file.

Customizing Collections Manager

Use the following policy opcodes to customize Collections Manager:

Customizing Dunning Letters

By default, the PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA policy opcode gathers the following data for your dunning letters:

  • Current overdue amount

  • Currency type

  • Current bill unit overdue date

  • Account POID

However, you can modify the type of data gathered by customizing the policy opcode. For example, you can enrich the standard data with additional information, such as the date on which the account will be inactivated.

Important:

By default, this policy opcode gathers the data required for typical dunning letter templates, such as for the samples in BRM_home/sys/data/config/stylesheets. If you use custom templates with placeholders for non-default data, you must customize this policy opcode.

This policy opcode is called by the PCM_OP_COLLECTIONS_SET_DUNNING_LETTER opcode.

Applying Finance Charges

Use the PCM_OP_COLLECTIONS_POL_APPLY_FINANCE_CHARGES policy opcode to apply finance charges to overdue amounts.

This policy opcode is called by the PCM_OP_COLLECTIONS_TAKE_ACTION opcode to calculate the finance charge when the scenario associated with the bill unit calls for finance charges.

By default, its calculation is based on the finance charge action definition entered in Collections Configuration. The finance charge percentage from Collections Configuration is stored in the /collections_action/finance_charge object, which is created when the account bill unit enters a scenario that includes a finance charge action.

Required inputs include the POID of the /collections_action/finance_charge object for this finance charge as well as the POID of the /billinfo object, POID of the account with which this /billinfo object is associated, overdue amount, and overdue date.

You can customize this policy opcode to change the way a finance charge is calculated or to add functionality. For example, you can customize this policy opcode to calculate the finance charge from the customer's average daily balance rather than the current balance.

You can also customize this policy opcode to find a specific balance group where finance charges apply. By default, BRM applies finance charges to the bill unit's default balance group.

By default, errors in the syntax of the input flist cause this policy opcode to fail. Customizing this policy opcode may introduce additional error conditions.

By default, this policy opcode returns the POID of the /collections_action/finance_charge object, the POID of the /billinfo object, the action status, and the PIN_FLD_EVENT substruct. After customization, the return value depends on the features implemented.

If this policy opcode fails, it returns an error in the error buffer. The transaction is rolled back.

Applying Late Fees

Use the PCM_OP_COLLECTIONS_POL_APPLY_LATE_FEES policy opcode to apply a late fee to overdue charges.

This policy opcode is called by the PCM_OP_COLLECTIONS_TAKE_ACTION opcode when the scenario associated with a bill unit calls for late fees. By default, it uses the late fee action definition entered in Collections Configuration. The late fee amount or percentage is stored in the /collections_action/late_fee object, which is created when the account bill unit enters a scenario that includes a late fee action.

Required inputs include the POID of the /collections_action/late_fee object for this late fee, the POID of the /billinfo object or the POID of the account to which the bill unit belongs, the overdue amount, and the overdue date.

This policy opcode performs the following tasks by default:

  • Gathers the late fee definition information and, if it is based on a percentage, calculates the amount.

  • Converts currency, if necessary.

You can customize this policy opcode to change how the late fee is calculated or to add functionality. For example, you can customize this policy opcode to calculate a percentage-based late fee from the customer's average daily balance rather than from the current balance.

You can also customize this policy opcode to find specific balance groups where late fees apply. By default, BRM applies late fees to the default balance group of the bill unit.

By default, errors in the input flist cause this policy opcode to fail. Customizing this policy opcode may introduce additional error conditions.

By default, this policy opcode returns the POID of the /collections_action/late_fee object and the status of the action. After customization, the return value depends on the features implemented.

If this policy opcode fails, it returns an error in the error buffer. The transaction is rolled back.

Assigning Bill Units Automatically

Use the PCM_OP_COLLECTIONS_POL_ASSIGN_AGENT policy opcode to automatically assign bill units to collections agents. By default, this policy opcode is an empty hook.

This policy opcode is called by PCM_OP_COLLECTIONS_PROCESS_BILLINFO.

Assigning Bill Units to a Debt Collections Agency

Use the PCM_OP_COLLECTIONS_POL_ASSIGN_DCA policy opcode to automate the logic of selecting a debt collections agent (DCA) when multiple DCAs are configured. By default, this policy opcode is an empty hook.

This opcode is called when a system collections action of type Refer to outside agency is run.

Customizing to Which Collections Group Members to Apply Collections Actions

Use the PCM_OP_COLLECTIONS_POL_GET_GROUP_TARGET_ACTIONS policy opcode to override the action target setting in the /config/collections_actions object. By default, this policy opcode is an empty hook.

This policy opcode is called by the PCM_OP_COLLECTIONS_TAKE_ACTION opcode.

When you add a collections action to a scenario in Collections Configuration, you specify whether the collections action applies to:

  • The individual bill unit

  • The parent and all child bill units in a collections sharing group

  • All child bill units in a collections sharing group

You can customize this policy opcode to use additional attributes for deciding to which bill units to apply the collections action.

This policy opcode must return in the output flist the /account POID and one of the following:

  • The PIN_FLD_BILLINFO array with a list of /billinfo objects to which to apply the collections action.

  • The PIN_FLD_TARGET field set to:

    • 0 to apply the collections action to the /billinfo object passed in the input flist.

    • 1 to apply the collections action to the parent and all child /billinfo objects in the collections sharing group.

    • 2 to apply the collections action to all child /billinfo objects in the collections sharing group.

Mapping Bill Units to Collections Profiles

Use the PCM_OP_COLLECTIONS_POL_SELECT_PROFILE policy opcode to map a bill unit to a collections profile. By default, this policy opcode maps all bill units to the default collections profile, but you can customize it to map bill units to custom profiles based on specific criteria.

For example, you can assign bill units to profiles based on credit score. You can map bill units with low credit scores to profiles with more aggressive collections scenarios and bill units with high credit scores to profiles with more lenient collections scenarios.

Your custom code must return the POID of the /config/collections/profile object or the collections profile to which the bill units map. BRM creates profile objects when you define one in Collections Configuration.

This policy opcode is called by the PCM_OP_COLLECTIONS_PROCESS_BILLINFO opcode.

Adding Information that Is Passed to Custom Client Applications

Use the PCM_OP_COLLECTIONS_POL_PUBLISH_EVENT policy opcode to append additional fields to the /event/audit/collections/action notification event before it is passed to your custom client application. The entire /event/audit/collections/action notification event is passed in the input flist to this policy opcode.

This policy opcode is called by the PCM_OP_COLLECTIONS_PUBLISH_EVENT opcode.

By default, this policy opcode adds the following information to the notification event:

  • /billinfo POID

  • /collections_action POID

  • Collections action name

  • Collections action description

  • Collections action type

  • Collections action status

  • Collections action due date

  • Collections action completed date

  • Opcode number

  • Overdue amount

  • Currency

  • Total number of days the account has been in collections

  • Bill details

  • Accounting type

Performing Custom Collections Actions

Use the PCM_OP_COLLECTIONS_POL_EXEC_POLICY_ACTION policy opcode to perform custom collections actions, such as sending SMS text messages to a customer's wireless phone. By default, this policy opcode sets the collections action status to Pending and then returns to the calling opcode.

By default, this policy opcode is called by the PCM_OP_COLLECTIONS_TAKE_ACTION opcode.

The names and descriptions of custom actions are created in Collections Configuration and are stored in /collections_action objects. This information is then passed in an input flist to the PCM_OP_COLLECTIONS_POL_EXEC_POLICY_ACTION policy opcode. When you customize this policy opcode, you use this bill unit information to find any other information required for a particular custom action.

Performing Custom Actions when a Bill Unit Leaves Collections

Use the PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO policy opcode to perform custom tasks, such as cleaning up files or modifying a customer's credit score, when a bill unit exits collections. By default, this policy opcode is an empty hook.

This policy opcode is called by the PCM_OP_COLLECTIONS_PROCESS_BILLINFO opcode when a bill unit exits the collections process.