diff --git a/docs/user-guide/etendo-classic/basic-features/financial-management/accounting/setup/accounting-templates.md b/docs/user-guide/etendo-classic/basic-features/financial-management/accounting/setup/accounting-templates.md index 936de6fb02..61c3a2dd00 100644 --- a/docs/user-guide/etendo-classic/basic-features/financial-management/accounting/setup/accounting-templates.md +++ b/docs/user-guide/etendo-classic/basic-features/financial-management/accounting/setup/accounting-templates.md @@ -5,77 +5,106 @@ tags: - Templates - Financial Management - Setup - - Accounting --- -# Accounting Templates +# Accounting Templates :material-menu: `Application` > `Financial Management` > `Accounting` > `Setup` > `Accounting Templates` -## Overview - -Accounting templates in Etendo overwrite default accounting behavior. Each template is related to a specific table. +## Overview + +Accounting Templates allow organizations to **replace Etendo's default accounting entries with custom posting rules** for specific document types. When a document is posted, the accounting engine checks whether a template is defined for that document type and, if so, executes the custom logic instead of the standard posting behavior. + +This is typically needed when: + +- **Country-specific legal requirements** demand a different accounting treatment for certain transactions (for example, invoices, goods shipments, or payments). +- **Special posting rules** must be applied to a subset of documents, such as generating additional ledger lines or distributing amounts differently. + +!!!info + Setting up an Accounting Template is a collaborative task. A **developer** writes the custom posting logic (a Java class), and a **finance administrator** configures the template in this window to activate it. If your organization needs a custom template, coordinate with your development team before making changes. + +You can define a single template that covers all documents of a given type (for example, all invoices), or create separate templates that target only specific [document categories](document-type.md) (for example, only purchase invoices), while leaving the default behavior for the rest. + +## Header + +![Accounting Templates grid view](../../../../../../assets/drive/1QFEgaMk9QRkcpsjLLGOZJNKRJo75LvKr.png) -The accounting entries generated by Etendo usually need to be generated in a different way to fulfill the legal requirements for a concrete country. To support this kind of requirements, Etendo allows overriding the code that generates the accounting entries through what is called Accounting Templates. Each time a document is posted, the accounting engine checks whether any Accounting Template is defined for the associated table or for the concrete document and executes it instead of the default Core's code. - -!!! warning - This is a powerful feature that must be used with caution. The code that generates the accounting entries must be deeply tested before deploying it in a real instance. +Fields to note: -## Creating the Accounting Template Configuration +- **Name**: A descriptive identifier for the accounting template. Use a clear name that reflects the posting rule or the document type it affects. +- **Java Class Name**: The technical identifier for the custom posting logic. Your developer will provide this value — paste it exactly as given. +- **Table**: The document type this template overrides. Select the table corresponding to the transactions you want to customize. In the dropdown, look for names like `C_Invoice` (invoices) or `M_InOut` (goods shipments) — these are internal table names Etendo uses to identify each document type. +- **Description**: Optional additional information about the purpose or behavior of this template (not shown in the grid view above). +- **Active**: A flag indicating whether this template is currently in use. Deactivating a template restores the default posting behavior for the associated document type. -The Java class that implements the generation of the new accounting entries is defined into the Accounting Templates window. The definition is quite simple and only requires a name, the Java class name, which must be inside the java package of the module, and the table for which the user wants to override its accounting entries (for example, C_Invoice for Invoices, M_InOut for goods shipments/receipts, etc.). +!!!warning + Accounting Templates override the standard posting logic for the selected document type. Before activating a template in a production environment: -![](../../../../../../assets/drive/1QFEgaMk9QRkcpsjLLGOZJNKRJo75LvKr.png) + - **Test thoroughly** in a development or staging instance by posting sample documents and reviewing the generated accounting entries. + - **Involve your development team** to confirm the custom logic handles all expected scenarios. + - **Have an auditor or accounting manager review** the resulting ledger entries to ensure they meet legal and organizational requirements. -This Accounting Template will be later on associated with the Active Tables or a Document. So in this step it is important to define as many Java classes as Active Tables or Document to override their accounting behavior. -For example, we can define an unique java class for overriding the accounting behavior of all the invoices (sales invoices, purchase invoices, purchase/sales credit memo, etc.), or alternatively define a class for overriding only the accounting entries for Purchase Invoices (AP Invoice) and keep the default behavior to the rest of the invoices. +Once the template is configured, it is associated with the corresponding active tables or documents. The entries it generates will appear in the [General Ledger Configuration](general-ledger-configuration.md) reports alongside standard postings, following the rules defined in the [Account Tree](account-tree.md). -### Dataset Definition +## Dataset Definition -Dataset definition is a key step in this process. A wrong dataset definition can waste all previous work, so it is important to follow all these considerations: +!!!info + This section is intended for development teams that need to package a custom accounting template as a distributable module. If you are only configuring an existing template, you can skip this section. -- The dataset must belong to the accounting template module -- Try avoiding strange characters in the dataset's name. This string is used for generating the XML file name that stores the dataset. -- The Data Access Level must be set to System/Client, which means we allow users to apply the configuration only at Client level (Organization *). -- The Export allowed flag must be set. -- Inside the Table tab, include the AD_CreateFact_template table, which is the one that stores the Accounting Template configuration. -- The HQL/SQL Where clause is an important field, because it allows filtering the records the user wants to include into the dataset. In the example all the records that are inside the module java package name have been filtered. +The dataset definition determines which records are exported with the accounting template module so that the template can be installed in other environments. A correct dataset definition is essential — an incorrect one can render the entire template unusable after installation. For background on how organizations and datasets interact during setup, see [Initial Organization Setup](../../../general-setup/enterprise-model/initial-organization-setup.md). -![](../../../../../../assets/drive/1stuKmJOwNnsth6RG3HX9tj5_6v3OY83U.png) +Follow these guidelines when defining the dataset: -The dataset definition is ready, so the user just needs to export it to a file pressing the Export Reference Data button. This process queries the previous tables and gets all the records that fulfill the HQL/SQL Where clause, generating a XML file inside the module's referencedata/standard directory. As a fast check, this file can be opened using any plain text editor and the user can verify that it contains several lines. -In case the file is empty, the user should double check the dataset definition, specially the HQL/SQL Where clause used for each table. +- The dataset **must belong to the accounting template module**. +- **Avoid special characters** in the dataset name. This string is used to generate the XML filename that stores the dataset. +- **Data Access Level** must be set to `System/Client`, which means users can apply the configuration only at Client level (Organization `*`). Note: the screenshot below may show a different value depending on the Etendo version. +- The **Export Allowed** flag must be checked. +- In the **Table** tab, include the `AD_CreateFact_template` table, which stores the Accounting Template configuration. +- The **HQL/SQL Where Clause** is critical for filtering which records are included in the dataset. Typically, the clause filters all records whose Java class name falls within the module's Java package. -#### Testing the Dataset +![Dataset definition window](../../../../../../assets/drive/1stuKmJOwNnsth6RG3HX9tj5_6v3OY83U.png) -The real test to ensure the taxes dataset is OK can be done inside the development instance. The test consists on creating a new client running the Initial Client Setup and selecting the new dummy accounting template dataset. +Once the dataset definition is complete, export it by pressing the **Export Reference Data** button. This process queries the configured tables, retrieves all records matching the HQL/SQL Where Clause, and generates an XML file in the `referencedata/standard` directory of the module. -![](../../../../../../assets/drive/14yYG4b3onJefyFiz6sV8KlImkfi5ijCf.png) +!!!info + As a quick check, open the generated XML file with a text editor and verify it contains data. If the file is empty, review the dataset definition — especially the HQL/SQL Where Clause for each table. -!!! info - If the data inside the dataset are consistent, the Initial Client Setup Process should be completed successfully, otherwise it will fail giving a description about the error. +## Dataset Testing - -After a successful Initial Client Setup, login into the new client, go to the Accounting Templates window and check the record is there. +The recommended way to verify that the dataset is correct is to create a new client within the development instance using the [Initial Client Setup](../../../general-setup/getting-started.md#initial-client-setup) process, selecting the new accounting template dataset during setup. -## Functional Specification +![Initial Client Setup reference data selection](../../../../../../assets/drive/14yYG4b3onJefyFiz6sV8KlImkfi5ijCf.png) + +!!!info + If the data within the dataset is consistent, the Initial Client Setup process should complete successfully. Otherwise, it will fail with an error description indicating what went wrong. + +After a successful setup, log in to the new client, navigate to the **Accounting Templates** window, and confirm that the template record is present. You can then proceed to test posting by creating sample documents and verifying that the custom accounting entries are generated correctly. + +## How Accounting Templates Work + +This section explains the technical design behind Accounting Templates. It is provided for reference and is not required for day-to-day configuration. ### Overview -Nowadays, Etendo builds entries associated with documents following a hard-coded behavior. In order to modify the generated entry, code must be modified. The current code has become a module called core. If a module wants to modify accounting entries generated by documents, core must be modified, and this is not desired at all. -With this new development in core, modules will be able to easily modify the entries generated by each document. +By default, Etendo generates journal entries for documents using built-in posting logic. Accounting Templates introduce a mechanism that allows **modules to override this default behavior** without modifying the core application code. This means organizations can adapt how accounting entries are generated to meet specific legal or business requirements through independent, installable modules. ### Scope -The aim of this project is to allow modules to modify the way entries are generated when posting documents. + +The goal of Accounting Templates is to allow modules to **modify how journal entries are generated** when documents are posted. Rather than requiring changes to core code, a module can provide its own posting logic that the accounting engine will use in place of the default. ### Design Considerations -A new layer will be included between the document, and the logic that posts that document. In a new window each document is mapped to the servlet that implements the logic to post it. This way, just modifying the values on this window, accounting behavior is changed. If a new module wants to change the entry generated when posting an invoice, a new servlet is developed following the desired behavior. At the same time, the mapping of the invoices to the servlet that posts will be changed to the servlet developed in the module. This way, the whole application behavior is changed. -### Functional Requirements +Accounting Templates work by inserting a **new layer between the document and the posting logic**. In the Accounting Templates window, each document type is mapped to the class that implements its posting behavior. To change how a document is posted: + +1. A developer creates a new class that implements the desired posting logic. +2. The template is configured in this window to map the relevant document type to the new class. +3. From that point on, all documents of that type use the custom logic. + +This approach is transparent to end users — the posting process looks and works the same from the application interface. The only difference is in the accounting entries generated, which follow the rules defined by the custom template rather than the built-in defaults. -!!! info - Application is not affected by these developments, because all changes to the way the documents are posted are transparent to the user. Only a new window is necessary, that is configured automatically for the user when updating. +!!!info + The application interface is not affected by these changes. All modifications to posting behavior happen behind the scenes. The Accounting Templates window is the only additional configuration needed, and it is set up automatically when the template module is installed. --- -This work is a derivative of [Accounting Templates](https://wiki.openbravo.com/wiki/Projects:Accounting_Templates){target="\_blank"} by [Openbravo Wiki](http://wiki.openbravo.com/wiki/Welcome_to_Openbravo){target="\_blank"}, used under [CC BY-SA 2.5 ES](https://creativecommons.org/licenses/by-sa/2.5/es/){target="\_blank"}. This work is licensed under [CC BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/){target="\_blank"} by [Etendo](https://etendo.software){target="\_blank"}. \ No newline at end of file +This work is a derivative of [Accounting Templates](https://wiki.openbravo.com/wiki/Projects:Accounting_Templates){target="\_blank"} by [Openbravo Wiki](http://wiki.openbravo.com/wiki/Welcome_to_Openbravo){target="\_blank"}, used under [CC BY-SA 2.5 ES](https://creativecommons.org/licenses/by-sa/2.5/es/){target="\_blank"}. This work is licensed under [CC BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/){target="\_blank"} by [Etendo](https://etendo.software){target="\_blank"}.