Projects:Madv/Specifications

This document contains the functional specification of the mass advanced payment module.

Contents 1 General Description 1.1 Background Information - Creating advanced payments manually in Openbravo ERP 1.2 Module Overview - Creating mass advanced payments 2 Relation to other modules 3 Mass Advanced Payments Wizard 3.1 Step 1: Select Organization, bank, business partners and amount 3.2 Step 2: Review and adjust proposed payments 3.3 Step 3: The result 4 Advanced Payment Templates 4.1 Table: Payment Template 5 Generating Advanced Payments 6 Other considerations 6.1 Server-Side Implementation

General Description

Background Information - Creating advanced payments manually in Openbravo ERP

In Openbravo ERP, users can create an advanced payment from or to a business partner by creating a settlement and recording the cash movement in a bank statement.

This can be done using one of the following two approaches:

• Bank Statement creating a settlement
  • Navigate to the Bank Statement window
  • Create a new bank statement record, selecting:
    • The bank that will receive or issue the payment
    • The transaction data
  • Nvigate to the line tab and create a new line record
  • Press the Create Payment button and specify:
    • the business partner
    • the amount of the advance
    • the currency
    • the payment due date
    • the form of payment
    • whether it is a receipt or a disbursement
    • a status
    • optionally a description
  • Process the Bank Statement
  • This process creates a settlement with two debt payments, one associated with the bank account and one of opposite sign to balance it.
  • Once the bank statement is processed, debt payment associated with it is marked as paid (Payment Complete set to Y).

• Settlement creating a bank account
  • Navigate to the Settlement window
  • Create a new settlement accepting the default values
  • Navigate to the Created Payments tab and create two new payment records
  • The first record specifies:
    • Form of payment: the desired form of payment, typically Bank Deposit
    • Due Date: the date of the payment
    • Business Partner: the business partner
    • Bank Account: the account that will receive or issue the payment
    • Amount: the amount of the payment
    • Status: the payment status
    • Receipt: check if it is a receipt, uncheck if it is a disboursement
  • The second record specifies:
    • Form of payment: same as the first record
    • Due Date: same as the first record
    • Business Partner: same as the first record
    • Bank Account: null
    • Amount: the opposite of the amount of the payment
    • Status: same as the first record
    • Receipt: same as the first record
  • Navigate back to the Settlement header and complete the document
  • Navigate to the Bank Statement window
  • Create a new bank statement record, selecting:
    • The bank that will receive or issue the payment
    • The transaction data
  • Press the Create Lines From button and select the first payment record in the Settlement that you just created.
  • Process the Bank Statement
  • Once the bank statement is processed, debt payment associated with it is marked as paid (Payment Complete set to Y).

The outcome of both of these approaches is a debt payment record that is matched to the bank statement (the money has been received) and a negative debt payment record that is not matched to any transaction. In case this debt payment is a receipt, this debt payment represents a liability (hence it is negative) as the business partner has paid money to the organization but no goods or service has been provided. When a sales invoice is created, a positive debt payment is created and it can be cancelled against the negative payment eliminating the liability.

Module Overview - Creating mass advanced payments

This module allows people to automatically create advanced payments in bulk for a number of different partners at the same time.

Additionally, if the partner is an internal organization it creates the corresponding payment in that organization:

• A collection payment in organization A from organization B triggers a disbursement in organization B
• A disbursement payment in organization A to organization B triggers a collection in organization B.

This module will use the prefix: MADV.

This module consists of two additional screens:

• Advanced Payment Template: where users define the template for the bulk processing.
• Advanced Payment Wizard: where users initiate the mass creation of payments based on the template.

The menu option for the mass advanced payment wizard can be found in the Financial Management > Receivables & Payables > Transactions menu. The menu option for the advanced payment templace can be found in the Financial Management > Receivables & Payables > Setup menu.

The functional approach chosen by this module is that, for each payment to be created, a settlement with two payments is created (the second approch described in the previous section). The bank statement is then created manually. To automate the creation of the bank statement, this module relies on the Direct Debit Form of Payment module: users can specify this form of payment in the advanced payment template and the system automatically creates and process the bank statement.

Relation to other modules

This module provides similar functionality to the Mass Invoicing module but for advanced payments. The implementation of this module can use Mass Invoicing as a pattern and replicate and adapt its code.

This module makes use of and is dependent on the multi-business-partner selector module. The business partner delivered by that module is used in the generation wizard.

In addition, this module uses the depends on the Direct Debit Form of Payment module as described in the previous section.

Mass Advanced Payments Wizard

To generate orders the user will go through a multi-step wizard:

1. select the organization initiating the transaction as well as its bank account; select the payment date; select the business partners, amount, currency and advanced payment template
2. review and adjust the proposed payments
3. show the result of the generation step (payments created)

Step 1: Select Organization, bank, business partners and amount

This step allows the user to:

• select an organization
• set the payment date
• select the bank account to receive or issue the payment from (optional)
• select one or more business partners
• set the default payment amount
• select the currency of the payment
• select which avanced payment template to use

A first version of the user interface is shown below

The following defaulting rules should be applied to this window:

• The organization should be defaulted to the default organization of the user session
• The bank account should be defaulted to null
• The currency should be initially defaulted from the default currency for the client; if a bank account is specified, the currency should be defaulted from the currency of the bank account.

The advanced template listbox will only show order templates which are active.

The business partner selector is implemented by the multi business partner selector module. It allows filtering business partners and to select one or more business partners.

The following validations should be done in step 1 of the wizard:

• at least one business partner should be selected (client-side)
• the business partners should belong to the accessible organizations for the selected organization in the window.
• if the business partner is an organization and the template has the Create Matching Inter-company Payment flag set to Y, then:
  • the corresponding organization should be accessible in the current role
  • the corresponding organization should have at least one bank account defined
• payment date should be set and have the right format (client-side)
• an advanced payment template should be selected (client-side)
• the amount should be set and have the right format (client-sied)

The validations marked with client-side are performed on the client-side (in the browser). The remaining validations are done when the user presses next. If a validation fails the same window is displayed with all the information as entered and a message box explaining the validation failure. The validation message should show enough detail (list specific business partners for which the above check fails).

When the user is satisfied the user can select the next button to go to step 2. The information entered in step 1 is stored and the user can return back from step 2 to change the information.

Step 2: Review and adjust proposed payments

The second step uses the information from the first step to show a list of proposed payment to be executed.

This step allows to adjust the payment amount on a business partner by business partner basis.

This page consists of two tables. The tables are not rendered if they do not contain any data. In both tables, initially all records are selected and users can deselect some or all records.

The first table contains the list of proposed payments for external business partners. The amount field is defaulted from step 1 and for selected records the user can edit this value.

The second table contains the list of proposed payments for internal organizations. The bank account field contains the bank account for the target organization and it is defaulted from the first bank account in alphabetical order. The amount field is defaulted from step 1 and for selected records the user can edit this value.

IMPORTANT NOTE: if the template has Create Matching Inter-company Payment set to N, then internal organizations are treated as regualar business partners and appear in the first table. In this case, the second table is always empty and therefore not rendered.

When the user presses generate the system validates the inputs and asks for confirmation. If the user confirms then system generates the payment (see later section for a description of the generate process).

The validation, validates that each selected line has a valid amount.

If the generation fails then the step 2 window is re-shown with a detailed error message in a red message box.

Step 3: The result

In step 3 the result for the generation step is shown. The proposal is to show the following information. For each organization where a payment has been executed, a table with a list of payments with for each payment:

• business partner
• document
• document number
• description
• due date
• amount
• currency

The document is a link to the payment itself.

Please notice that you would have more than one table only in the case of inter-company payments.

Advanced Payment Templates

In the first step of the advanced generation wizard the user can select the advanced payment template. The template defines the characteristics of the generated payments and it consists of:

• name (mandatory)
• description (non mandatory)
• receipt (checkbox - defaulted to checked)
• form of payment (mandatory)
• bank account (optional)
• status (mandatory)
• create matching inter-company payment (checkbox - defaulted to unchecked)
• active (checkbox - defaulted to checked)

Table: Payment Template

To maintain and store advanced payment templates a new table is created:

• madv_payment_template: with the following fields:
  • standard columns: madv_payment_template_id, ad_client_id, ad_org_id, isactive, created, createdby, updated, updatedby
  • name (required): the name of the payment template, is displayed to the user generating payments
  • description: is used to create the settlement and payment description
  • isreceipt (required): Y or N
  • paymentrule (required): a free format string field to store the form of payment
  • c_bank_account_id (not required): a foreign key to c_bank_account
  • status (required): a free format string to store the initial payment status
  • create_matching_interco (required): Y or N

Generating Advanced Payments

This section of the functional spec describes in some detail how the advanced payments are created and which information is used to set their attributes.

When the user presses the generate button the following actions are performed:

• For each checked proposed payment
  • A settlement is created
  • The settlement has two lines

The information on the settlement header (c_settlement) is set as follows:

Column	Value
c_settlement_id	UUID of the record
ad_client_id	the current user client
ad_org_id	the organization selected in step 1
isactive	Y
created, createdby, updated, updatedby	current user, current date
documentno	will be computed
datetrx	current date
c_doctype_id	the ID corresponding to document type "Debt/Payment Settlement"
processing	N
processed	N
posted	N
c_campaign_id, c_project_id, c_activity_id, user1_id, user2_id	all null
createfrom	null
c_currency_id	set to the value specified in step 1 of the wizard
description	set from the order template
cancelednotchargedamt	0
generatedamt	0
chargedamt	0
createfile	N
settlementtype	C
copyfrom	N
isgenerated	N
istemplate	N

Any other nullable column not explicitly mentioned should be set to null.

For each settlment, two records for created payments (c_debt_payment_generate) are set as follows:

Column	Value
c_debt_payment_id	UUID of the record
ad_client_id	the current user client
ad_org_id	the organization selected in step 1
isactive	Y
created, createdby, updated, updatedby	current user, current date
c_settlement_id	the id of the settlement
description	from the payment template
isreceipt	from the payment template
c_invoice_id	null
c_bpartner_id	the business partner for which the payment is generated
c_currency_id	set to the value specified in step 1 of the wizard
c_cashline_id, c_bankstatementline_id	null
c_bank_account_id	set to the value specified in step 1 of the wizard; if no value is specified there, then set to the value specified in the payment template
c_cashbook_id	null
paymentrule	from the payment template
ispaid	N
amount	value specified in step 2 of the wizard
writeoffamt	0
dateplanned	the due date specified in step 1 of the wizard
ismanual	N
isvalid	Y
generate_processed	N
c_glitem_id	null
isdirectposting	N
status	from the payment template
c_project_id	null
c_withholding_id	null
withholdingamount	null

Any other nullable column not explicitly mentioned should be set to null.

A settlement is stored in the database and directly posted using the C_SETTLEMENT_POST stored procedure.

Other considerations

• The payment template name is not translated.
• Labels and messages should be translatable.
• The date and numeric formats used by the rest of the application should also be used here.

Server-Side Implementation

The server-side logic to create advanced payments will be using the DAL.

Similar to Mass Invoices that added the InvoicePropertySetter class to core, this project requires the creation of the class SettlementPropertySetter. This class contains logic to set the information of a Settlement, including canceled and generated payments. This makes it much easier for application code to create settlements: just set a few mandatory field and SettlementPropertySetter does the rest. The class can be found here: org.openbravo.service.model.financial.payment.SettlementPropertySetter.

The posting of the settlements is done through a stored procedure. The implementation of this module will leverage a generic api provided by MassInvoicing for passing parameters to stored procedures and running stored procedures from Java.