Collections Opcode Workflows

8 Collections Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) collections opcode workflows.

Topics in this document:

For more information about collections, see "Understanding Collections Manager" in BRM Collections Manager.

Opcodes Described in This Chapter

Table 8-1 lists the opcodes described in this chapter.

Caution:

Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
Do not use SQL commands to change data in the database. Always use the API.

Table 8-1 Collections Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_COLLECTIONS_ADD_ACTION	Adding Actions to a Collections Scenario
PCM_OP_COLLECTIONS_ASSIGN_AGENT	Assigning Bill Units to a Collections Agent
PCM_OP_COLLECTIONS_CALC_AGING_BUCKETS	Retrieving Aging Buckets Information
PCM_OP_COLLECTIONS_CONFIG_DELETE_ACTION	Deleting an Existing Collections Action
PCM_OP_COLLECTIONS_CONFIG_DELETE_PROFILE	Deleting an Existing Collections Profile
PCM_OP_COLLECTIONS_CONFIG_DELETE_SCENARIO	Deleting an Existing Collections Scenario
PCM_OP_COLLECTIONS_CONFIG_GET_ACTIONS	Getting All Currently Defined Collections Actions
PCM_OP_COLLECTIONS_CONFIG_GET_PROFILES	Getting All Currently Defined Collections Profiles
PCM_OP_COLLECTIONS_CONFIG_GET_SCENARIO_DETAIL	Getting Details of a Collections Scenario
PCM_OP_COLLECTIONS_CONFIG_GET_SCENARIOS	Getting All Currently Defined Collections Scenarios
PCM_OP_COLLECTIONS_CONFIG_GET_TEMPLATES	Getting a List of Message Templates
PCM_OP_COLLECTIONS_CONFIG_SET_ACTION	Creating or Updating Collections Actions Applying Late Fees
PCM_OP_COLLECTIONS_CONFIG_SET_PROFILE	Creating or Updating Collections Profiles
PCM_OP_COLLECTIONS_EXEMPT_BILLINFO	Exempting Bill Units from Collections
PCM_OP_COLLECTIONS_GET_ACTION_HISTORY	Retrieving Collections Action History Information
PCM_OP_COLLECTIONS_GET_AGENTS_ACTIONS	Retrieving a List of Collections Actions
PCM_OP_COLLECTIONS_GET_BILLINFOS	Retrieving a List of Bill Units in Collections
PCM_OP_COLLECTIONS_GET_DUNNING_LETTER	Retrieving Dunning Letters
PCM_OP_COLLECTIONS_GET_SCENARIO_DETAIL	Retrieving Scenario Information
PCM_OP_COLLECTIONS_GET_VALID_SCENARIOS	Getting All Valid Collections Scenarios Replacing a Collections Scenario
PCM_OP_COLLECTIONS_GROUP_ADD_MEMBER	Adding Members to a Collections Group Creating a Collections Group
PCM_OP_COLLECTIONS_GROUP_CREATE	Creating a Collections Group
PCM_OP_COLLECTIONS_GROUP_DELETE	Deleting a Collections Group
PCM_OP_COLLECTIONS_GROUP_DELETE_MEMBER	Removing a Member from a Collections Group
PCM_OP_COLLECTIONS_GROUP_GET_BILLINFO	Retrieving a Collections Group
PCM_OP_COLLECTIONS_GROUP_MODIFY	Modifying a Collections Group
PCM_OP_COLLECTIONS_GROUP_SET_PARENT	Changing the Parent of a Collections Group
PCM_OP_COLLECTIONS_INVOKE_PROMISE_TO_PAY	Creating a System-Configured Promise-to-Pay Agreement Creating a Manually Configured Promise-to-Pay Agreement
PCM_OP_COLLECTIONS_POL_APPLY_FINANCE_CHARGES	Applying Finance Charges
PCM_OP_COLLECTIONS_POL_APPLY_LATE_FEES	Applying Late Fees
PCM_OP_COLLECTIONS_POL_ASSIGN_AGENT	Assigning Bill Units Automatically Executing Automatic Collections Actions
PCM_OP_COLLECTIONS_POL_ASSIGN_DCA	Assigning Bill Units to a Debt Collections Agency
PCM_OP_COLLECTIONS_POL_CALC_DUE_DATE	Customizing Due Dates
PCM_OP_COLLECTIONS_POL_EXEC_POLICY_ACTION	Executing Pending Actions for a Bill Unit Performing Custom Collections Actions
PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO	Performing Custom Actions when a Bill Unit Leaves Collections Executing Automatic Collections Actions Exempting Bill Units from Collections
PCM_OP_COLLECTIONS_POL_GET_GROUP_TARGET_ACTIONS	Customizing How to Apply Collections Actions to Collections Group Members
PCM_OP_COLLECTIONS_POL_GET_VALID_SCENARIOS	Getting All Valid Collections Scenarios
PCM_OP_COLLECTIONS_POL_HANDLE_BREACH_PROMISE_TO_PAY	Breaking a Promise-to-Pay Agreement
PCM_OP_COLLECTIONS_POL_INITIATE_PAYMENT	Executing Pending Actions for a Bill Unit
PCM_OP_COLLECTIONS_POL_INVOKE_PROMISE_TO_PAY	Creating a System-Configured Promise-to-Pay Agreement
PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA	Customizing Dunning Letters Gathering and Storing Data for Dunning Letters
PCM_OP_COLLECTIONS_POL_PROCESS_BILLINFO	Executing Automatic Collections Actions
PCM_OP_COLLECTIONS_POL_SELECT_PROFILE	Configuring the Currency Used in Collections Mapping Bill Units to Collections Profiles Executing Automatic Collections Actions
PCM_OP_COLLECTIONS_PROCESS_BILLINFO	Assigning Bill Units Automatically Mapping Bill Units to Collections Profiles Performing Custom Actions when a Bill Unit Leaves Collections Executing Automatic Collections Actions Preparing Invoice Reminders Gathering and Storing Data for Dunning Letters Executing Pending Actions for a Bill Unit
PCM_OP_COLLECTIONS_REPLACE_SCENARIO	Replacing a Collections Scenario
PCM_OP_COLLECTIONS_RESCHEDULE_ACTION	Rescheduling an Action Scheduled for a Bill Unit Rescheduling a Promise-to-Pay Action
PCM_OP_COLLECTIONS_REVOKE_PROMISE_TO_PAY	Breaking a Promise-to-Pay Agreement Canceling a Promise-to-Pay Agreement
PCM_OP_COLLECTIONS_SET_ACTION_STATUS	Changing the Status of a Collections Action Changing the Status of a Promise-to-Pay Action
PCM_OP_COLLECTIONS_SET_DUNNING_LETTER	Customizing Dunning Letters Gathering and Storing Data for Dunning Letters
PCM_OP_COLLECTIONS_SET_INVOICE_REMINDER	Preparing Invoice Reminders
PCM_OP_COLLECTIONS_TAKE_ACTION	Applying Finance Charges Applying Late Fees Customizing How to Apply Collections Actions to Collections Group Members Performing Custom Collections Actions Executing Automatic Collections Actions Gathering and Storing Data for Dunning Letters Executing Pending Actions for a Bill Unit
PCM_OP_COLLECTIONS_UPDATE_ACTION_PAYMENT_DETAILS	Updating Amount and Payment Details
PCM_OP_GROUP_ADD_MEMBER	Adding Members to a Collections Group Creating a Collections Group
PCM_OP_GROUP_CREATE_GROUP	Creating a Collections Group
PCM_OP_GROUP_DELETE_GROUP	Deleting a Collections Group
PCM_OP_GROUP_SET_PARENT	Changing the Parent of a Collections Group
PCM_OP_INV_FORMAT_INVOICE	Retrieving Dunning Letters
PCM_OP_PYMT_POL_EXEC_COLLECTIONS_ACTION	Completing Promise-to-Pay Installments during Payment Processing
PCM_OP_UMS_SET_MESSAGE	Preparing Invoice Reminders

Customizing Collections Manager

See the following topics:

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.

Customizing Due Dates

Use PCM_OP_COLLECTIONS_POL_CALC_DUE_DATE to customize how collections actions due dates are determined. For example, for collections actions that fall on a holiday, you can customize this opcode to set the action due date to the following day.

By default, if any collections action falls on a Saturday or Sunday, this opcode sets the action due date to the following Monday.

Customizing Dunning Letters

PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA enables customization of dunning letter data before it is stored in the database. You can modify the type of data gathered by customizing the opcode. For example, you can enrich the standard data with additional information, such as the date on which the account is inactivated.

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

Current overdue amount
Currency type
Current bill unit overdue date
Account POID

Note:

By default, PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA 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 nondefault data, you must customize this opcode.

PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA is called by PCM_OP_COLLECTIONS_SET_DUNNING_LETTER.

Applying Finance Charges

Use PCM_OP_COLLECTIONS_POL_APPLY_FINANCE_CHARGES to apply finance charges to overdue amounts.

This opcode is called by PCM_OP_COLLECTIONS_TAKE_ACTION 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, POID of the bill unit, POID of the account with which this bill unit is associated, overdue amount, and overdue date.

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

You can also customize PCM_OP_COLLECTIONS_POL_APPLY_FINANCE_CHARGES 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 PCM_OP_COLLECTIONS_POL_APPLY_FINANCE_CHARGES to fail. Customizing this opcode may introduce additional error conditions.

By default, PCM_OP_COLLECTIONS_POL_APPLY_FINANCE_CHARGES returns the POID of the /collections_action/finance_charge object, the POID of the bill unit, the action status, and the PIN_FLD_EVENT substruct. After customization, the return value depends on the features implemented.

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

Applying Late Fees

Use PCM_OP_COLLECTIONS_POL_APPLY_LATE_FEES to apply a late fee to overdue charges.

This opcode is called by PCM_OP_COLLECTIONS_CONFIG_SET_ACTION and PCM_OP_COLLECTIONS_TAKE_ACTION 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 bill unit or the POID of the account to which the bill unit belongs, the overdue amount, and the overdue date.

PCM_OP_COLLECTIONS_POL_APPLY_LATE_FEES 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 opcode to change how the late fee is calculated or to add functionality. For example, you can customize this 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 PCM_OP_COLLECTIONS_POL_APPLY_LATE_FEES 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 opcode to fail. Customizing this opcode may introduce additional error conditions.

By default, this 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 PCM_OP_COLLECTIONS_POL_APPLY_LATE_FEES fails, it returns an error in the error buffer. The transaction is rolled back.

Assigning Bill Units Automatically

Use PCM_OP_COLLECTIONS_POL_ASSIGN_AGENT to automatically assign bill units to collections agents. This opcode is an empty hook.

This opcode can be modified to customize how account bill units are assigned to collections agents.

This opcode is called by PCM_OP_COLLECTIONS_PROCESS_BILLINFO.

Assigning Bill Units to a Debt Collections Agency

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

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

Customizing How to Apply Collections Actions to Collections Group Members

Use PCM_OP_COLLECTIONS_POL_GET_GROUP_TARGET_ACTIONS to override the action target setting in the /config/collections_actions object. This opcode is an empty hook.

You can customize PCM_OP_COLLECTIONS_POL_GET_GROUP_TARGET_ACTIONS to use additional attributes for deciding which bill units to apply a collections action to:

The individual bill unit only
The parent and all child bill units in the collections group
All child bill units in the collections group

PCM_OP_COLLECTIONS_POL_GET_GROUP_TARGET_ACTIONS is called by PCM_OP_COLLECTIONS_TAKE_ACTION.

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

PCM_OP_COLLECTIONS_POL_GET_GROUP_TARGET_ACTIONS 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 one of the following:
- 0 to apply the collections action to the bill unit passed in the input flist.
- 1 to apply the collections action to the parent and all child bill units in the collections group.
- 2 to apply the collections action to all child bill units in the collections group.

Mapping Bill Units to Collections Profiles

Use PCM_OP_COLLECTIONS_POL_SELECT_PROFILE to map a bill unit to a collections profile. By default, this 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.

The default profile uses US Dollars for the currency. To use a different currency for collections, you must edit this opcode.

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.

PCM_OP_COLLECTIONS_POL_SELECT_PROFILE is called by PCM_OP_COLLECTIONS_PROCESS_BILLINFO.

Performing Custom Collections Actions

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

This opcode is called by PCM_OP_COLLECTIONS_TAKE_ACTION.

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 PCM_OP_COLLECTIONS_POL_EXEC_POLICY_ACTION. When you customize this 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 PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO to perform custom tasks, such as cleaning up files or modifying a customer's credit score, when a bill unit exits collections. This opcode is an empty hook.

This opcode is called by PCM_OP_COLLECTIONS_PROCESS_BILLINFO.

Managing Overdue Balance Collection

See the following topics:

Creating or Updating Collections Actions

Use PCM_OP_COLLECTIONS_CONFIG_SET_ACTION 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, PCM_OP_COLLECTIONS_CONFIG_SET_ACTION 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.

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

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

Creating or Updating Collections Profiles

Use PCM_OP_COLLECTIONS_CONFIG_SET_PROFILE to create or update a collections profile.

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

As input, PCM_OP_COLLECTIONS_CONFIG_SET_PROFILE 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.

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

If PCM_OP_COLLECTIONS_CONFIG_SET_PROFILE fails, it returns an error in the error buffer.

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

Getting All Currently Defined Collections Actions

Use PCM_OP_COLLECTIONS_CONFIG_GET_ACTIONS 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 PCM_OP_COLLECTIONS_CONFIG_GET_ACTIONS 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 run 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 PCM_OP_COLLECTIONS_CONFIG_GET_PROFILES 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 PCM_OP_COLLECTIONS_CONFIG_GET_SCENARIOS to get a list of all collections scenarios and associated profiles.

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. It also returns the POID and name of the profile associated with each scenario.

Getting Details of a Collections Scenario

Use PCM_OP_COLLECTIONS_CONFIG_GET_SCENARIO_DETAIL 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, PCM_OP_COLLECTIONS_CONFIG_GET_SCENARIO_DETAIL 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 run 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 PCM_OP_COLLECTIONS_CONFIG_GET_TEMPLATES to get a list of templates.

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, PCM_OP_COLLECTIONS_CONFIG_GET_TEMPLATES 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 and name of each template that matches the locale and action type specified in the input flist.

Deleting an Existing Collections Action

Use PCM_OP_COLLECTIONS_CONFIG_DELETE_ACTION 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.

PCM_OP_COLLECTIONS_CONFIG_DELETE_ACTION 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 PCM_OP_COLLECTIONS_CONFIG_DELETE_PROFILE 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.

PCM_OP_COLLECTIONS_CONFIG_DELETE_PROFILE 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 PCM_OP_COLLECTIONS_CONFIG_DELETE_SCENARIO 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.

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

Managing Promise-to-Pay Agreements

To manage your customer's promise-to-pay agreements, see the following:

The promise-to-pay opcodes are called by Billing Care. You can customize your client application to call these opcodes for managing promise-to-pay agreements.

For more information about promise-to-pay agreements, see "Managing Promise-to-Pay Agreements" in BRM Collections Manager.

Creating a System-Configured Promise-to-Pay Agreement

Use PCM_OP_COLLECTIONS_INVOKE_PROMISE_TO_PAY to create a promise-to-pay agreement with system-configured details. With system-configured agreements, Collections Manager calculates the installment schedule and installment amount for you. For example, a $500 promise-to-pay agreement could be created with five installments of $100 each that is due every 30 days.

To create a promise-to-pay agreement with system-configured details, pass in the following information in the opcode's input flist:

The account and bill unit in collections (PIN_FLD_POID and PIN_FLD_BILLINFO_OBJ)
The collections scenario (PIN_FLD_SCENARIO_OBJ)
The total amount that the customer promises to pay (PIN_FLD_AMOUNT under the PIN_FLD_PROMISE_TO_PAY_INFO substruct)
The due date for the first promise-to-pay installment (PIN_FLD_INVOKE_T under the PIN_FLD_PROMISE_TO_PAY_INFO substruct)
The installment schedule and amount. Include the following fields under the PIN_FLD_PROMISE_TO_PAY_INFO substruct:
- Either PIN_FLD_AMOUNT set to the amount owed for each installment, or PIN_FLD_NUM_MILESTONES set to the number of installment payments.
  
  If the installment amount is provided, Collections Manager calculates the number of installments as the total promise-to-pay amount divided by the installment amount. If the number of installments is provided, Collections Manager calculates the installment amount as the total promise-to-pay amount divided by the number of installments.
- Either PIN_FLD_MILESTONE_INTERVAL set to the number of days between each installment payment, or PIN_FLD_DAYS set to the total number of days in which the full outstanding amount is paid off.
  
  If the interval is provided, Collections Manager calculates the agreement's total number of days by multiplying the interval by the number of installments. If the agreement's total number of days is provided, Collections Manager calculates the interval as the total number of days divided by the number of installments.

PCM_OP_COLLECTIONS_INVOKE_PROMISE_TO_PAY performs the following actions:

Calls the PCM_OP_COLLECTIONS_POL_INVOKE_PROMISE_TO_PAY policy opcode to perform additional validation, such as preventing promise-to-pay agreements that go beyond 30 days. By default, this opcode is an empty hook.
Calculates the installment schedule and installment amount.
Creates a /collections_action/promise_to_pay object for each promise-to-pay installment.
Creates an /event/activity/collections/promise_to_pay object to record the details about the promise-to-pay agreement.
Reschedules all outstanding collections actions in the bill unit to continue, starting one day after the last promise-to-pay installment due date.
Generates an /event/audit/collections/actions audit event to record the changes to the collections actions.

Creating a Manually Configured Promise-to-Pay Agreement

Use PCM_OP_COLLECTIONS_INVOKE_PROMISE_TO_PAY to create a promise-to-pay agreement with manually configured details. Manually configured agreements allow you to create installments with varying amounts owed and varying intervals between installments. For example, you could create a $500 promise-to-pay agreement with the installments shown in Table 8-2.

Table 8-2 Sample Manually Configured Promise-to-Pay Installments

Installment Number	Interval Between Installments	Amount Owed
1	0	$250
2	30 Days	$100
3	15 Days	$100
4	20 Days	$50

To create a promise-to-pay agreement with manually configured details, pass in the following information in the opcode's input flist:

The account and bill unit in collections (PIN_FLD_POID and PIN_FLD_BILLINFO_OBJ)
The collections scenario to apply (PIN_FLD_SCENARIO_OBJ)
The promise-to-pay specification to apply (PIN_FLD_SPEC_NAME)
The total amount that the customer promises to pay (PIN_FLD_AMOUNT under the PIN_FLD_PROMISE_TO_PAY_INFO substruct)
The due date for the first promise-to-pay installment (PIN_FLD_INVOKE_T under the PIN_FLD_PROMISE_TO_PAY_INFO substruct)
For each installment, its due date and the amount owed. The sum of all installments must equal 100% of the promise-to-pay agreement amount.

For each installment, add a PIN_FLD_MILESTONES array with the following fields:
- PIN_FLD_MILESTONE_INTERVAL set to the number of days between the previous installment and this installment.
  
  Set the interval for the first installment to 0, because the due date of the first installment has already been set.
- Either PIN_FLD_MILESTONE_AMOUNT set to the amount owed for this installment, or PIN_FLD_MILESTONE_PERCENTAGE set to the percentage of the total promise-to-pay amount that will be paid off in this installment.

When the promise-to-pay details are configured manually, PCM_OP_COLLECTIONS_INVOKE_PROMISE_TO_PAY performs the following actions:

Validates that the promise-to-pay agreement's details adhere to the limits in the promise-to-pay specification (/config/collections/promise_to_pay_spec object).
Calls the PCM_OP_COLLECTIONS_POL_INVOKE_PROMISE_TO_PAY policy opcode to perform additional validation, such as preventing promise-to-pay agreements that go beyond 30 days. By default, this opcode is an empty hook.
Determines whether to automatically increase the customer's credit limit during the promise-to-pay period by reading the value of the PIN_FLD_CREDIT_LIMIT_FLAG field in the /config/collections/promise_to_pay_spec object:
- If the field is set to 0, the credit limit is not adjusted.
- If the field is set to 1, it calls the PCM_OP_BILL_SET_LIMIT_AND_CR opcode to temporarily increase the bill unit's credit limit, if needed. See "Managing Credit Limits and Sub-Balance Consumption Rules" for more information.
Creates a /collections_action/promise_to_pay object for each promise-to-pay installment.
Creates an /event/activity/collections/promise_to_pay object to record details about the promise-to-pay agreement.
Reschedules all outstanding collections actions in the bill unit to continue, beginning one day after the last promise-to-pay installment due date.
Generates an /event/audit/collections/actions audit event to record the changes to the collections actions.

Updating Amount and Payment Details

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

Billing Care 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.

Canceling a Promise-to-Pay Agreement

Use PCM_OP_COLLECTIONS_REVOKE_PROMISE_TO_PAY to cancel a promise-to-pay agreement.

This opcode takes as input the POID of the /event/activity/collections/promise_to_pay object, the POID of the /account object, the POID of the /collections_scenario object, and the POID of the /billinfo object. Then, the opcode does the following:

Cancels all outstanding promise-to-pay installments and deletes all corresponding /schedule objects.
Sets the status of the overall promise-to-pay agreement to one of the following:
- Broken: Set to broken only if this opcode is called by the PCM_OP_COLLECTIONS_POL_HANDLE_BREACH_PROMISE_TO_PAY policy opcode.
- Canceled: Set to canceled if this opcode is called by an application.
Reads the value of the PIN_FLD_CREDIT_LIMIT_FLAG field in the /config/collections/promise_to_pay_spec object:
- If the value is 1, calls PCM_OP_BILL_SET_LIMIT_AND_CR to decrease the bill unit's temporary credit limit. See "Managing Credit Limits and Sub-Balance Consumption Rules for more information".
- If the value is 0, the credit limit is not adjusted.
Reschedules all outstanding collections actions to start from the next day and updates the corresponding /schedule objects.
Removes the reference of the /event/activity/collections/promise_to_pay object from the /collections_scenario object.

Breaking a Promise-to-Pay Agreement

Use the PCM_OP_COLLECTIONS_POL_HANDLE_BREACH_PROMISE_TO_PAY policy opcode to break a promise-to-pay agreement after a customer misses a promise-to-pay installment. This opcode is called by PCM_OP_COLLECTIONS_PYMT_COLLECT.

By default, this opcode does the following, but you can customize it to meet your business needs.

Sets the status of the current promise-to-pay installment to Broken.
Calls the PCM_OP_COLLECTIONS_REVOKE_PROMISE_TO_PAY opcode to cancel all outstanding installments, set the status of the overall promise-to-pay agreement to Broken, and reschedule all collections actions to start from the following day. See "Canceling a Promise-to-Pay Agreement" for more information.

Rescheduling a Promise-to-Pay Action

Use PCM_OP_COLLECTIONS_RESCHEDULE_ACTION 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".

Changing the Status of a Promise-to-Pay Action

Use PCM_OP_COLLECTIONS_SET_ACTION_STATUS to change the status of a Promise to Pay action. See "Changing the Status of a Collections Action".

Completing Promise-to-Pay Installments during Payment Processing

Use the PCM_OP_PYMT_POL_EXEC_COLLECTIONS_ACTION policy opcode to automatically complete a promise-to-pay installment as part of the payment process. This opcode is called by PCM_OP_PYMT_COLLECT.

This policy opcode determines whether a payment is for a promise-to-pay installment and then returns the PIN_FLD_RESULTS[0].PIN_FLD_RESULT output flist field set to one of the following:

PIN_PYMT_RES_NO_EXEC_COLLECTIONS_ACTION (1): The payment is not for a promise-to-pay installment. This is the default.
PIN_PYMT_RES_EXEC_COLLECTIONS_ACTION (0): The payment is for a promise-to-pay installment.

When PIN_PYMT_RES_EXEC_COLLECTIONS_ACTION (0) is returned, PCM_OP_PYMT_COLLECT changes the promise-to-pay installment's status to Completed.

By default, the PCM_OP_PYMT_POL_EXEC_COLLECTIONS_ACTION policy opcode returns PIN_PYMT_RES_EXEC_COLLECTIONS_ACTION (0) when the following is true, but you can customize the policy opcode to meet your business needs.

The bill unit is in collections.
In the PIN_FLD_PAYMENT_REASONS input flist array, the PIN_FLD_REASON_ID is set to 15 and the PIN_FLD_REASON_DOMAIN_ID field is set to 5.

For information about the reason ID values, see the BRM_home/sys/msgs/reasoncodes/reasons.en_US file.

Managing Collections Groups

See the following topics:

Creating a Collections Group

Use PCM_OP_COLLECTIONS_GROUP_CREATE to group bill units into a collections group.

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

If you pass a member's details in the input flist, the opcode calls PCM_OP_COLLECTIONS_GROUP_ADD_MEMBER opcode to add the member to the collections group.

PCM_OP_COLLECTIONS_GROUP_CREATE performs the following actions:

Validates that the parent bill unit is not already a parent or member of another collections group.
Calls PCM_OP_GROUP_CREATE_GROUP 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 PCM_OP_GROUP_ADD_MEMBER 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, PCM_OP_COLLECTIONS_GROUP_CREATE returns the POID of the /group/collections_targets object.

Adding Members to a Collections Group

Use PCM_OP_COLLECTIONS_GROUP_ADD_MEMBER to add a child member to an existing collections group. This opcode checks whether the prospective member is an account that has a nonpaying bill unit. Such accounts cannot be added as members of a collections group. If the account is already in the collections group, it is ignored.

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

PCM_OP_COLLECTIONS_GROUP_ADD_MEMBER performs the following actions:

Validates that the new child member is not a parent or member of the existing collections group.
Calls PCM_OP_GROUP_ADD_MEMBER 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, PCM_OP_COLLECTIONS_GROUP_ADD_MEMBER returns the POID of the /group/collections_targets object.

Removing a Member from a Collections Group

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

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 Group

Use PCM_OP_COLLECTIONS_GROUP_DELETE to delete an existing collections group.

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 Group

Use PCM_OP_COLLECTIONS_GROUP_GET_BILLINFO to retrieve:

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

This opcode is called directly by Billing Care.

PCM_OP_COLLECTIONS_GROUP_GET_BILLINFO 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 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 group, returns the /group/collections_targets POID and the PIN_FLD_BOOLEAN field set to 0.
- If it is a child in a collections group, returns the /group/collections_targets POID and the PIN_FLD_BOOLEAN field set to 1.
- If it is a parent in a collections 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 Group

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

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

Changing the Parent of a Collections Group

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

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.

PCM_OP_COLLECTIONS_GROUP_SET_PARENT performs the following actions:

Validates that the new parent bill unit is not a child of the existing collections group.
Validates that the new parent bill unit is not already a parent of another collections group.
Calls PCM_OP_GROUP_SET_PARENT 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, PCM_OP_COLLECTIONS_GROUP_SET_PARENT returns the POID of the /group/collections_targets object.

Performing Manual Collections Actions

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 PCM_OP_COLLECTIONS_ASSIGN_AGENT to assign bill units to a collections agent.

This opcode is called 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 PCM_OP_COLLECTIONS_ADD_ACTION to add collections actions to a bill unit's collections scenario.

This opcode is called 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, PCM_OP_COLLECTIONS_ADD_ACTION checks the contents of the field to determine whether the actions that follow must 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 is 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.

PCM_OP_COLLECTIONS_ADD_ACTION 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 PCM_OP_COLLECTIONS_EXEMPT_BILLINFO to exempt bill units from collections.

This opcode is called 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 PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO 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, PCM_OP_COLLECTIONS_EXEMPT_BILLINFO 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 bill unit and the POID of the account to which the bill unit belongs.

Rescheduling an Action Scheduled for a Bill Unit

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

This opcode is called 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.

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

PCM_OP_COLLECTIONS_RESCHEDULE_ACTION 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 PCM_OP_COLLECTIONS_SET_ACTION_STATUS to change the status of a manual collections action.

This opcode is called 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, PCM_OP_COLLECTIONS_SET_ACTION_STATUS 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. 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.

PCM_OP_COLLECTIONS_SET_ACTION_STATUS 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 PCM_OP_COLLECTIONS_REPLACE_SCENARIO 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 PCM_OP_COLLECTIONS_GET_VALID_SCENARIOS to get a list of all the valid collections scenarios applicable for the bill unit.

After the new scenario is identified, PCM_OP_COLLECTIONS_REPLACE_SCENARIO 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.

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 PCM_OP_COLLECTIONS_PROCESS_BILLINFO to do the following:

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. This opcode then processes each bill unit to evaluate its collections status and perform any necessary collections actions.

PCM_OP_COLLECTIONS_PROCESS_BILLINFO calls PCM_OP_COLLECTIONS_POL_PROCESS_BILLINFO. You can use PCM_OP_COLLECTIONS_POL_PROCESS_BILLINFO to include additional criteria to determine whether bill units should enter and exit collections. Based on the status flag in the input flist, this opcode identifies if it is being called during entry or exit. PCM_OP_COLLECTIONS_POL_PROCESS_BILLINFO is an empty hook.

Tip:

The source code for PCM_OP_COLLECTIONS_POL_PROCESS_BILLINFOis not shipped with BRM.

When PCM_OP_COLLECTIONS_PROCESS_BILLINFO 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, PCM_OP_COLLECTIONS_PROCESS_BILLINFO:
- Calls PCM_OP_COLLECTIONS_POL_SELECT_PROFILE 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.
- Generates the /event/audit/collections/action notification event.
- Calls PCM_OP_COLLECTIONS_POL_ASSIGN_AGENT to assign a collections agent to the bill unit. See "Assigning Bill Units Automatically".
If the bill unit is already in collections, PCM_OP_COLLECTIONS_PROCESS_BILLINFO 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, PCM_OP_COLLECTIONS_PROCESS_BILLINFO changes the bill unit's action status to Completed, generates the /event/audit/collections/action notification event, and calls PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO 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, PCM_OP_COLLECTIONS_PROCESS_BILLINFO:
- 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 PCM_OP_COLLECTIONS_TAKE_ACTION to run 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, PCM_OP_COLLECTIONS_PROCESS_BILLINFO:
- Changes the bill unit's action status to Completed.
- Calls PCM_OP_COLLECTIONS_POL_EXIT_SCENARIO to perform any custom exit actions that you specify. See "Performing Custom Actions when a Bill Unit Leaves Collections".
- Generates the /event/audit/collections/action notification event.

Preparing Invoice Reminders

Use PCM_OP_COLLECTIONS_SET_INVOICE_REMINDER 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 PCM_OP_COLLECTIONS_PROCESS_BILLINFO 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 PCM_OP_COLLECTIONS_SET_DUNNING_LETTER to gather and store data for dunning letters.

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

This opcode performs the following actions:

Calls PCM_OP_COLLECTIONS_POL_PREP_DUNNING_DATA 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 PCM_OP_COLLECTIONS_PROCESS_BILLINFO.

Retrieving Dunning Letters

Use PCM_OP_COLLECTIONS_GET_DUNNING_LETTER 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 storable class is automatically subclassed when you load a dunning letter template.
Calls PCM_OP_INV_FORMAT_INVOICE to create the final dunning letter.

Executing Pending Actions for a Bill Unit

Use PCM_OP_COLLECTIONS_TAKE_ACTION to run pending actions for a bill unit.

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

As input, this opcode takes the POID of the action to run, 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 run:

If it requires a manual action, this opcode stops processing.
If it requires a system action, this opcode calls other opcodes to run the desired action:
- Prepare a dunning letter. See "Gathering and Storing Data for Dunning Letters".
- Apply finance charges. See "Applying Finance Charges".
- Apply late fees. See "Applying Late Fees".
If it requires a custom action, this opcode calls PCM_OP_COLLECTIONS_POL_EXEC_POLICY_ACTION to perform any custom actions that you specify. See "Performing Custom Collections Actions".

PCM_OP_COLLECTIONS_TAKE_ACTION calls PCM_OP_COLLECTIONS_POL_INITIATE_PAYMENT to performs auto-collect of the due amount for promise_to_pay and collect_payment actions, if the customer has opted to pay off the due amount through credit card or direct debit.

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, PCM_OP_COLLECTIONS_TAKE_ACTION 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 PCM_OP_COLLECTIONS_TAKE_ACTION 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.

Retrieving Collections Information

See the following topics:

Retrieving a List of Bill Units in Collections

Use PCM_OP_COLLECTIONS_GET_BILLINFOS to get a list of bill units that are in collections.

This opcode is called to display the bill units in collections that meet the criteria defined by a CSR.

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, PCM_OP_COLLECTIONS_GET_BILLINFOS 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.

Retrieving Aging Buckets Information

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

This opcode is called 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.

PCM_OP_COLLECTIONS_CALC_AGING_BUCKETS 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 bill unit, 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 PCM_OP_COLLECTIONS_GET_SCENARIO_DETAIL to retrieve details about a bill unit's collections scenario.

This opcode is called 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.

PCM_OP_COLLECTIONS_GET_SCENARIO_DETAIL 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 PCM_OP_COLLECTIONS_GET_VALID_SCENARIOS 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.

This opcode is called 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 PCM_OP_COLLECTIONS_POL_GET_VALID_SCENARIOS to determine if a scenario is valid or not for the current bill unit. PCM_OP_COLLECTIONS_POL_GET_VALID_SCENARIOS 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 opcode evaluates the next collections scenario.
Returns a list of all the valid scenarios. The results are ordered by the entry amount in the descending order and severity in the ascending order.

Retrieving a List of Collections Actions

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

This opcode is called 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.

PCM_OP_COLLECTIONS_GET_AGENTS_ACTIONS 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 run for the action.

Note:

This opcode uses step search when searching for bill units.

Retrieving Collections Action History Information

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

This opcode is called 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, PCM_OP_COLLECTIONS_GET_ACTION_HISTORY 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.