Introduction

This document describes detailed requirements of the dunning module.
It is split in two main areas:

User Stories area describes all requirements related to new windows and processes.

Gaps area describes all changes to be developed on existing Openbravo functionalities.

Each area includes a description of the user story or the gap, and some sub-sections related to user interfaces and business rules.
Each requirement element (a story, a gap, a user interface, a business rule) is assigned a unique code.

User Stories

User Story US-DUN-001: Dunning Keys Setup

As a financial user, I can enter the dunning keys window and define a new key.
I assign the code 15 for the organization California, the name “Dunning 15” and I set coming into effect to 20 days. This is a dunning key which is a sub-sequent key for another one. Therefore, I save the record and create a new one, code 14, name “Dunning 14”, I select 15 from the sub-sequent key list, and I set coming into effect to 30 days. If I want to configure a key that is the last one in a dunning case, I can select 00 or 99 as sub-sequent key.
For each dunning key I can assign different levels of dunning costs according to the amount of the receivable. I can create different records for a dunning key to specify dunning costs for different amounts.

User Interface UI-DUN-001: Dunning key

Mock-up:

Final window:
There is a new field named "Payment Priority"

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Client

Drop-Down List

Reference to list of clients

Yes

Organization

Drop-Down List

Reference to list of organizations

*

Read-Only

Yes

Name

Text

String

60

Yes

Key

Text

String

2

Just digits, if one digit is entered, a leading 0 is added

Yes

Reminder

Check-Box

Boolean

false

Yes

Sub-sequent key

Drop-Down List Reference to list of keys

The list includes just keys of the same client/organization, plus the default keys '00' and '99'

Yes

Coming into effect (Grace Period)

Number

Integer

2

30

Range between 1 and 99

Yes

Dunning Fee

Number

Decimal 2,2 (Percentage)

No

Active

Check-Box

Boolean

True

Yes

User Interface UI-DUN-011: Dunning Costs Limits

Mockup:

Final window:

This is a nested tab of the dunning key window with a zero to many relationship.

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Client

Drop-Down List

Reference to list of clients

Yes

Organization

Drop-Down List

Reference to list of organizations

*

Read-Only

Yes

Amount

Number

Decimal 2,2 (Money)

Yes

Description

Text

String

Yes

Dunning Cost

Number

Decimal 2,2 (Money)

Yes

Active

Check-Box

Boolean

True

Yes

Business Rule BR-DUN-001: Dunning key mandatory fields

It is not possible to create a dunning key if at least one of the following field is not filled: key, name, sub-sequent key, coming into effect.

Business Rule BR-DUN-002: Uniqueness of dunning key

It is not possible to create a dunning key with the same code of another key for the same client/organization.

Business Rule BR-DUN-003: Sub-sequent keys must exist

It is not possible to set a sub-sequent key if the corresponding key does not exist in the same client/organization.

Business Rule BR-DUN-004: Circularity of dunning keys is not possible

It is not possible to create a chain of sub-sequent keys which generates a circularity. As an example, if 13 is sub-sequent of 12, and 12 is sub-sequent of 11, 11 cannot be sub-sequent of 13.

Business Rule BR-DUN-032: Cannot be created keys 00 and 99

It is not possible to create a key with code 00 or 99. These keys are already pre-loaded at the setup of each organization including "*".

Business Rule BR-DUN-037: Cannot create dunning costs for the same limit

It is not possible to create dunning costs record for a dunning key having the same limit amount of another existing record linked to the same key.

Business Rule BR-DUN-038: Dunning Keys on organization *

It is not allowed to create a dunning key for organizations different than *.

User Story US-DUN-002: Setup Base Interest Rates

As a financial user, I can enter the base interest rate. Base interest rates can be defined just on 1st Jan and 1st July of each year.

User Interface UI-DUN-003: Base Interest Rates

Mockup:

Final window:

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Client

Drop-Down List

Reference to list of clients

Yes

Organization

Drop-Down List

Reference to list of organizations

Yes

Date

Date

Date

Yes

Rate

Number

Decimal

2,2

Yes

Active

Check-Box

Boolean

True

Yes

Business Rule BR-DUN-034: Base Interest Rates on organization *

It is not allowed to create a base interest rate for organizations different than *.

Business Rule BR-DUN-035: Base Interest Rates on same date

It is not allowed to create a base interest rate on the exact same date of an already existing date.

User Story US-DUN-003: Start a dunning run

As a financial user, I can execute a dunning run. I set a date that will be used as reminder date and select a type of receivable. I also need to select either the level or the key (or both). I then press the search button and retrieve all dunnings meeting the parameters being entered.
I can select which of the retrieved dunnings are included in this run and then press the process button. I am finally presented with a short message informing that the process is completed.
The process is described in the user story US-DUN-004.

User Interface UI-DUN-004: Dunning Run

Mockup:

Final window:

Note that the header of the select column in the search table must be a check-box too to be used to quickly select/unselect all records.

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Client

Drop-Down List

Reference to list of clients

Yes

Organization

Drop-Down List

Reference to list of organizations

Yes

Reminder Date

Date

Date

Current date

Must greater or equal to the the current date

Yes

Level

Drop-Down List

List of {1, 2, 3}

No

Key

Drop-Down List

Reference to dunning keys

No

Search

Button

Not enabled until either dunning level or dunning key has not been selected.

Search Results

Search Table

Table

All select check-box are true for all records. Not visible until the user has not pressed the Search button.

Process

Button

Enabled only if at least one dunning is selected in the search result table.

Search table specification
All the fields of the search table cannot be edited but the selection of the select check-box.

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Select

Check-Box

Boolean

True

Receivable

Link

Link to the receivable

Type

Text

String

Due Date

Date

Date

Dunning Date

Date

Date

Granted Deferral

Date

Date

Outstanding Amount

Number

Decimal

Business Rule BR-DUN-014: Minimum parameters to search dunnings

It is not possible to search dunning cases if the user has not selected either a dunning level or a dunning key, or both.

Business Rule BR-DUN-015: Reminder date cannot be in the past

It is not possible to execute a dunning run if the reminder date is in the past.

Business Rule BR-DUN-017: Dunning key 00 and 99

All receivables (payment plans) whose dunning key is 00 or 99 are not displayed in the search result.

Business Rule BR-DUN-018: Search by dunning key

In case a dunning key has been selected as a parameter, all receivables (payment plans) whose dunning key match the selected dunning key and the current date is greater than the dunning date are retrieved.

Business Rule BR-DUN-019: Search by dunning level

In case a dunning level has been selected as a parameter, all receivables (payment plans) whose dunning level is equal to the selected level minus 1 and the current date is greater than the dunning date are retrieved.

Business Rule BR-DUN-020: Search by dunning level and key

In case both a dunning level and dunning key have been selected as a parameters, both rules BR-DUN-018 and BR-DUN-019 are applied in “and” condition.

Business Rule BR-DUN-042: Outstanding amount must be greater than 0

User Story US-DUN-004: Dunning run process

After the user has pressed the dunning run button, the application performs the following steps.

Case 1: Type Public

This step is executed only if the type of the receivable is public (customer subject to public law) and only if the current dunning key associated to the receivable is not flagged as reminder.

If it's the first time this receivable is dunned, the application calculates the dunning fee.
The application calculates the fine for late payments.

Case 2: Type Private

This step is executed only if the type of the receivable is private (customer subject to private law) and only if the current dunning key associated to the receivable is not flagged as reminder.

The application calculates the interest on arrears.
The application calculates the dunning costs.

Case 3: Deferral

This step is executed only if the current date is greater than the granted deferral date, if a granted deferral date for a receivable has been set and if the current dunning key is not flagged as reminder. This step is executed regardless of the type of the receivable.

The application calculates interests on deferral.

Whatever is the applied case, the application assigns the receivable a new dunning key (the sub-sequent key of the current key) and increases the level by one. In case of the first dun, being the dunning level not set for the receivable, the new dunning level will be 1.
The new dunning date is calculated by adding the coming into effect days of the new dunning key to previous dunning date (see BR-DUN-016). The application records a new entry in the dunning history and creates the dunning file.
The application creates a new sales invoice for the relevant customer with payment terms immediate with as many lines as the different fees or interests to be charged to the customer. The new sales invoice will be completed and a payment plan and dunning information are generated. Dunning key will be set to the same new key for the related invoice. The new invoice will include a description informing that this invoice has been generated after dunning starting from payment due on <date> for the outstanding amount <amount> of the invoice <invoice number>.

Business Rule BR-DUN-036: How to get base interest rate

In order to get the base interest rate that was active at a given date, the application has to retrieve the most recent date which does not exceed or at most is equal to the relevant date. The application searches the base interest rate table for the * organization.
As an example, assume that base interest rate is 0,50 on 01/07/2009, 0,40 on 01/01/2010 and 0,30 on 01/07/2010 and you want to get the rate on 30/04/2010. Since the date of the rate for 01/07/2010 exceeds the date 30/04/2010, the most recent is 01/01/2010, so the base rate is 0.40.

Business Rule BR-DUN-033: How to get dunning configuration

In order to get the general dunning configuration relevant for a receivable (dunning case), the application takes into account the dunning configuration for the same organization set for the receivable. If a dunning configuration is not defined for the organization, the application searches up in the organization hierarchy until a dunning configuration is found.
If a dunning configuration is not found, the application skips the processing of the dunning case and writes a warning at the end of the process.

Business Rule BR-DUN-021: Parameters of new receivables

When the application creates new receivables for fees, interests, costs, etc., these receivables are linked to the same invoice from the originating receivable, the same type, level, key and dunning date are assigned, and the due date is set at the current date. The total amount of these receivables is flagged as not paid.

Business Rule BR-DUN-022: Dunning file format and location

This an example of the dunning output file
Media:20100906122500.doc.
At the end of each run a file is stored in /opt/openbravo/dunning following the naming convention yyyymmddhhmiss.xml. The section OBBO_BookingControl is generated only if Booking Control module is available in the ERP instance.
The example below shows just the minimum set of fields to be included in the file, this example does not excluded that other fields can be included in the file.

Business Rule BR-DUN-023: Calculation of dunning fees

The application gets the dunning fee for the current dunning key. If no dunning fee is set for the dunning key, the application gets the dunning fee from the general dunning configuration (base percentage of dunning fee section in the window Dunning Configuration). The application also gets the minimum and maximum charge from the dunning configuration.

The dunning fee is calculated as (outstanding amount x dunning fee) rounded to the second decimal digit.
In any case, the dunning fee amount cannot be below the minimum charge or above the maximum charge.

As an example, assuming that the base rate for dunning fee is 0,5%, minimum amount is € 4,00, maximum amount is € 75,00, if the outstanding amount is € 1000, then the dunning fee is € 5,00; if the outstanding amount is € 500, although the result of the calculation is € 2,50, the dunning fee will be € 4,00; as well, if the outstanding amount is € 50000, although the result of the calculation is € 250,00, the dunning fee will be € 75,00.

Business Rule BR-DUN-024: Calculation of fines for late payment

The application gets the fine percentage, rounding and minimum default days from the general dunning configuration.

The application calculates the number of whole months from the due date. In order to perform this calculation, retrieve the number of days between the current date and the due date, then divide by 30 and round up the result to the first whole number. As an example, if the dunning date is May 5th and the current date is July 16th, the number of whole months is 3, in fact the period includes 72 days, if you divide by 30 you get 2,4 which turns in 3 when rounded up to the first whole number.
No fines are applied before the minimum number of default days after the dunning date. In the example above, if the dunning date is June 4th, no fines can be applied before June 10th, assuming that the minimum default days is set to 6.
Retrieve the outstanding amount and calculate the base amount for fine by rounding down the outstanding amount based on the rounding parameter. In order to perform this calculation, calculate the whole division of the outstanding amount by the rounding amount, then multiply the result for the rounding amount.

As an example assume that the outstanding amount is € 115 and rounding is set to € 50,00, then the base amount for fine is (€ 115,00 / € 50,00) = 2 --> 2 x € 50,00 = € 100,00.

The fine is calculated as (base amount x fine percentage x number of whole months). According to the example above, that is an outstanding amount of € 115,00 with due date May 5th and current date July 16th, and assuming the fine percentage is configured to 1,0%, then the fine will be (€ 100 x 0,01 x 2) = € 2,00.

Business Rule BR-DUN-025: Calculation of interest on arrears

The application gets the private and business person percentages from the general dunning configuration.

Calculate the total interest to be applied, by summing the base interest rate to the spread (private percentage in case of private person, business percentage in case of business person). The base interest rate is the last available.
Calculate the number of days between the due date and the current date. As an example, if the due date is May 5th and the current date is June 16th, the number of days is 42.
Calculate the interest by applying the formula ((outstanding amount x total interest) / 360 x number of days). The result is rounded to the second decimal digit. As an example, assuming the outstanding amount is € 115,00, the base interest is 0,12% at Jan 1st, the dunning customer is a private person, the private percentage is 5,0%, and the number of days is 42, then the interest on arrears will be ((€ 115,00 x (0,12% + 5%) / 360 x 42) = € 0,69.

If the dunning procedure continues through several rates of the base interest default, the interest on arrears must be split for each rate. This is explained with the following example. The base rate is 0,12 from Jan 1st, and 0,15 from Jul 1st. Assume that the due date is May 5th and the current date is July 16th. In this case we have to distinguish two periods, a period starting May 5th until June 30th (56 days) with base interest rate 0,12%, another period starting July 1st until July 16th (16 days) with base interest rate 0,15%. The interest is calculated with the following formula: ((€ 115,00 x (0,12% + 5%) / 360 x 56) + ((€ 115,00 x (0,15% + 5%) / 360 x 16) = € 0,92 + € 0,26 = € 1,18. Rounding is applied separately to the two periods.
If a period includes full 6 months, the total number of days for this period must be assumed to be 180.

Business Rule BR-DUN-026: Calculation of dunning costs

The application gets the dunning cost for the current dunning key for the relevant amount limit.
The application searches among all dunning costs limits of the dunning key the record with the greatest amount which does not exceed the outstanding amount of the receivable.
If no dunning cost is set for the dunning key, the application does not charge any dunning cost.

Business Rule BR-DUN-027: Calculation for deferral

The application gets the deferral spread from the general dunning configuration (spread of deferral spread section in the window Dunning Configuration).

If the current date is before the granted deferral date, no deferral interest must be calculated. Otherwise:
The application calculate the total interest to be applied, by summing the deferral spread to the base interest rate. The base interest rate is the last available.
Then it calculate the number of days between the due date and the current date. As an example, if the due date is May 5th and the current date is June 16th, the number of days is 42.
It calculate the interest by applying the formula ((outstanding amount x total interest) / 360 x number of days). The result is rounded to the second decimal digit. As an example, assuming the outstanding amount is € 115,00, the base interest is 0,12% at Jan 1st, the deferral spread is 2,0%, and the number of days is 42, then the interest on deferral will be ((€ 115,00 x (0,12% + 2%) / 360 x 42) = € 0,28.
If the dunning procedure for deferral continues through several rates of the base interest default, the same rules as describes in BR-DUN-025 steps 4 and 5 must be followed.

Business Rule BR-DUN-028: History Record

The first time a receivable is involved in a dunning run, a new entry is recorded in the dunning history. It must be recorded the reference to the receivable, the dunning run date for level 1, the dunning key for level 1.
In sub-sequent dunning runs, the dunning history entry must be updated by recording the dunning run date and the dunning key for the relevant level.

Business Rule BR-DUN-029: Maximum number of levels

The maximum number of dunning levels is 3, plus some extra levels for reminders. It is possible to have no more than 2 reminder levels, so the total number can never exceed 5.

Business Rule BR-DUN-043: Dunning Report

This is an example of the report
Media:20100906122500.pdf.
At the end of each run a file is stored in /opt/openbravo/dunning following the naming convention yyyymmddhhmiss.pdf. The section Booking Control is generated only if Booking Control module is available in the ERP instance.

User Story US-DUN-005: View Dunning History

As a financial user, I can display all dunning cases with relevant details.

User Interface UI-DUN-010: Dunning History

Mockup:

Final window:

This is a read-only window.

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Receivable

Textbox

String (code of the receivable)

Yes

Dunning Date 1

Date-box

Date

Yes

Dunning Key 1

Textbox

String (code of the dunning key)

Yes

Dunning Date 2

Date-box

Date

No

Dunning Key 2

Textbox

String (code of the dunning key)

No

Dunning Date 3

Date-box

Date

No

Dunning Key 3

Textbox

String (code of the dunning key)

No

Dunning Date 4

Date-box

Date

No

Dunning Key 4

Textbox

String (code of the dunning key)

No

Dunning Date 5

Date-box

Date

No

Dunning Key 5

Textbox

String (code of the dunning key)

No

User Story US-DUN-006: Setup Dunning Configuration

As a financial user, I can setup parameters for dunning runs.

User Interface UI-DUN-009: Dunning Configuration

Mockup:

Final window:

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Client

Drop-Down List

Reference to list of clients

Yes

Organization

Drop-Down List

Reference to list of organizations

*

Read-Only

Yes

Private Person

Number

Decimal 2,2 (Percentage)

5,0%

Yes

Business Person

Number

Decimal 2,2 (Percentage)

8,0%

Yes

Base Percentage

Number

Decimal 2,2 (Percentage)

0,5%

Yes

Minimum Charge

Number

Decimal 2,2 (Money)

4,00

Yes

Maximum Charge

Number

Decimal 2,2 (Money)

75,00

Yes

Fine Percentage

Number

Decimal 2,2 (Percentage)

1,0%

Yes

Rounding

Number

Decimal 2,2 (Money)

50,00

Yes

Minimum Default Days

Number

Integer

6

Yes

Spread

Number

Decimal 2,2 (Percentage)

3,0%

Yes

Active

Check-box

Boolean

true

Yes

Business Rule BR-DUN-039: Dunning Configuration on organization *

It is not allowed to create a dunning configuration for organizations different than *.

Business Rule BR-DUN-040: Just one dunning configuration for client/organization

It is not allowed to create two or more dunning configurations for the same client/organization.

User Story US-DUN-007: Customer Dunning Configuration

As a user, when setting up a customer data, I can configure dunning setup. The configuration includes if the customer is subject to private or public law. In case it is subject to private law, I can define if the customer is a private person or a public person. I can then assign a dunning key and optionally and just for private law customers I can force a specific interest spread.
It is important noting that I can create different dunning configuration for different organizations.

User Interface UI-DUN-008: Customer Dunning Configuration

Mockup:

Final window:

This is a nested tab of the Customer tab of the Business Partner window.

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Subject to private law

Check-box

Boolean

false (it means the customer is subject to public law)

Yes

Private Person

Check-box

Boolean

false (it means the customer is a business person)

This field is visible only if the flag subject to private law is checked.

Yes

Dunning key

Drop-Down List

Reference to list of dunning keys

No

Override Interest Rate Spread

Check-box

Boolean

false (it means that standard interest spreads are applied)

This field is visible only if the flag subject to private law is checked.

Yes

Interest Rate Spread

Number

Decimal 2,2 (Percentage)

It is shown the standard interest spread according if the customer is private or public

This field is visible only if the flag Override Interest Rate Spread is checked.

No

Business Rule BR-DUN-031: One customer dunning configuration for each organization

It is not possible to create more than one customer dunning configuration for a given organization.

User Story US-DUN-009: Dunning information for payment plans of invoices

When an invoice is completed, the application generates a payment plan. For each payment plan the application has to also generate a dunning information. The dunning key must be set as the dunning key of the customer, the dunning level must be set to 0.

User Interface UI-DUN-012: Dunning Invoice tab

Mockup:

Final window:

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Dunning key

Drop-Down List

Reference to list of dunning keys

No

Next Dunning Date

Date

Date

Read-Only

No

Dunning Level

Number

Integer

1

Read-Only

No

Business Rule BR-DUN-011: Dunning keys can’t be defined for payable

It is not possible to assign a dunning key to a payable.
According to APR module, this means that the expected amount of the payment plan is negative (also expected amount equal to 0 must be treated according to this rule).

Business Rule BR-DUN-016: Dunning Date

The application sets the dunning date of the receivable according to the following rule.
If dunning key is set to 00 or 99 for the receivable the dunning date is left null.
Otherwise, the application retrieves the coming into effect days from the dunning key and adds this number of days to the due date of the receivable. If the dunning date falls in a non-business day, the application moves the dunning date to the next day, and so on until a valid business day is found. A business day is any date from Monday to Friday with the exception of the non business days as defined in the relevant fiscal calendar of the organization.

User Story US-DUN-010: Manage Granted Deferral for Payment Plans

As a financial user, I can agree with the customer on a delay for the payment, in such a case I can flag the payment as granted deferral and enter a new expected payment date (however this does not change the original due date).

User Interface UI-DUN-012: Dunning Invoice tab

Mockup:

Final window:

The UI has to be designed with two sections, the first is related to Dunning including the first three fields, the second is related to Deferral including the last two fields.

Name

Widget Type

Data Type

Length

Default

Constraint

Mandatory

Granted Deferral

Check-box

Boolean

false

Yes

Expected Deferral Date

Date

Date

Default is the due date of the payment plan

This field is visible only if granted deferral checkbox is ticked

No

Business Rule BR-DUN-041: Deferral Date is greater than due date

The deferral date must be a future date compared to the due date.

Changes

Dunning Key at Invoice Header Level

At invoice header level a new field "dunning key" has to be added. This field is a drop-down list which includes all dunning keys stored for the client. By default none of these keys is selected.
As soon as the user selects the customer for the invoice, the application retrieves the dunning key of the customer, if any, and automatically moves the selection of the dunning key field in the invoice to the key of the customer. Since it is not compulsory to set the dunning key at customer level, if no dunning key is configured for the customer, then the dunning key of the invoice will be null.
Whatever is the value automatically selected by the application, the user can freely change it, including not to select any key, or to select special keys 00 and 99.
As soon as the user presses the complete button, the application calculates payment plans and dunning keys, but differently from the current implementation, instead of deriving the dunning key from the customer, it derives it from the relevant invoice header. Dunning key field at invoice header turns into a read-only field when the status of the invoice is changed into completed.