CreditMngtDunning/User Stories
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
When performing a dunning run search, payments plan whose outstanding amount is 0 (or below) cannot be retrieved.
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.
Final window:
