AEAT390/Technical Documentation
MODELO 390: TECHNICAL DOCUMENTATION
Contents |
Purpose of the project
The purpose of the project is to create a new module for generating the Spanish official 390 tax report (Modelo 390) valid file. This module will be part of the Spanish Professional Localization Pack.
Modelo 390 is the annual VAT Settlement, which must be submitted to the tax authorities as a valid XML file implemented according to the Spanish tax authorities requirements.
On line submission of the Modelo 390 implies that the Spanish companies must have a Tax ID as well as a user Certificate X.509.V3 issued by FNMT or any other valid Certificate according to tax authorities requirements.
Apart from the XML file to be provided to the tax authorities, the Modelo 390 module will provide a CSV file ready to be imported in any spreadsheet software with the list of invoices, tax amounts, taxable amounts with its correspondent 390 box that have been included into the XML file. With this .csv file, the user has all the information about the transactions included into the report.
Module definition
- Name: Tax Report: Modelo 390 (Spain)
- Java Package: org.openbravo.module.aeat390.es
- Description: Genera un fichero para la presentación telemática de la declaración-resumen anual del Impuesto sobre el Valor Añadido (IVA)
- Translation Required: Yes
- Module Language: Spanish (Spain)
- IsCommercial: Yes
- Has reference data: Yes
- Reference Data Description: Configuración del Modelo 390
- License text: Copyright (C) 2011 Openbravo S.L.U. Licensed under the Openbravo Commercial License version 1.0. You may obtain a copy of the License at http://www.openbravo.com/legal/obcl.html or in the legal folder of this module distribution.
- Author: Openbravo S.L.U.
- URL: http://forge.openbravo.com/projects/spainaeatmodelo390
- DB Prefix: AEAT390
- Module Dependencies:
- Core 2.50MP37 to Core 3.0
- I.A.E. Epigraphs (Epígrafes del I.A.E.) 1.00
- Legal Representative of the Organization 1.0.0
- Provincias de España 1.0.5
- Tax Report Launcher 1.0.14
- Taxes: configuration for Spain (Impuestos para España) 1.2.39
Other modules to be created
It will be necessary to create two new modules that will be a new dependency of the Modelo 390:
Legal Representative of the Organization
Creates a new tab inside Organization window to provide the legal representative information for the organization
- Name: Legal Representative of the Organization
- Java Package: org.openbravo.module.organization.representative.es
- Description: Representante Legal de la Organización
- Help: Añade una nueva solapa dentro de la ventana de Organización en la que se puede introducir los datos de los representantes legales de la organización. Esta información puede ser útil al generar modelos oficiales de la AEAT.
- Translation Required: Yes
- Module Language: Spanish (Spain)
- IsCommercial: No
- Has reference data: No
- License text: Licensed under the Openbravo Public License version 1.1. You may obtain a copy of the License at http://www.openbravo.com/legal/license.html or in the legal folder of the Openbravo ERP core distribution.
- Author: Openbravo S.L.U.
- URL: http://forge.openbravo.com/projects/orgrepresentative
- DB Prefix: OREP
- Module Dependencies:
- Core from 2.50.19749 to Core 3.0
I.A.E. Epigraphs (Epígrafes del I.A.E.)
Provides a system level dataset with the list of epigraphs for the Spanish I.A.E., and adds a new tab inside the Organization window to define the organization's main activities.
- Name: I.A.E. Epigraphs (Epígrafes del I.A.E.)
- Java Package: org.openbravo.module.epigrafes.iae.es
- Description: Epígrafes del Impuesto sobre Actividades Económicas (IAE)
- Help: Proporciona la lista de epígrafes del I.A.E. y crea una nueva solapa llamada "Actividades" en la ventana de Organización en la que el usuario puede seleccionar las distintas actividades asociadas a cada organización. Este tipo de información se requiere en determinados modelos tributarios oficiales, como por ejemplo el Modelo 390.
- Translation Required: Yes
- Module Language: Spanish (Spain)
- IsCommercial: No
- Has reference data: Yes
- Reference Data Description: Lista de epígrafes del I.A.E.
- License text: Licensed under the Openbravo Public License version 1.1. You may obtain a copy of the License at http://www.openbravo.com/legal/license.html or in the legal folder of the Openbravo ERP core distribution.
- Author: Openbravo S.L.U.
- URL: http://forge.openbravo.com/projects/spainepigrafesiae
- DB Prefix: EPIAE
- Module Dependencies:
- User Interface Selector 1.0.14 to 2.1
Improvements in dependant modules
Tax Report Launcher
The Modelo 390 module depends on the tax report launcher framework, however when launching the 390 report the user will get two different files: the XML file with the official report, and a CSV file with the list of invoices included into the report.
Before Tax Report Launcher 1.0.14, all the reports that use the tax report launcher returned just one file. The Modelo 390 will return two files, so it's necessary to adapt the tax report launcher to return more than files.
The feature request 19335 will allow tax report launcher to return a ZIP file that contains any number of files inside, that are generated by the concrete reports.
Database stuff
New columns
Several new columns will be added to allow the implementation of reflection code (see [#6.Java Code|outline Java Code]).
OBTL_TAX_REPORT_GROUP
| COLUMN NAME | TYPE | REQUIRED | DEFAULT VALUE | ONCREATE DEFAULT | DESCRIPTION |
| EM_AEAT390_FACTORYMETHOD | VARCHAR(255) | No | Defines the factory method used for creating the equivalent XML element using reflection |
OBTL_TAX_REPORT_PARAMETER
| COLUMN NAME | TYPE | REQUIRED | DEFAULT VALUE | ONCREATE DEFAULT | DESCRIPTION |
| EM_AEAT390_ISSPLIT | CHAR(1) | Yes | N | N | Split by tax rate percentage |
| EM_AEAT390_XML_ELEMENT | VARCHAR(255) | No | Name of the XML element represented by this parameter | ||
| EM_AEAT390_BOX | VARCHAR(255) | No | Boxes in the 390 report represented by this parameter | ||
| EM_AEAT390_ISTOTAL | CHAR(1) | Yes | N | N | Set to Yes if the parameter includes a “Total” field for this parameter |
Java Code
Summary
This project has two main difficulties compared to other tax report launcher based modules:
- We must generate a XML file that contains the official report. In previous reports a plain TXT file has used
- We must generate a CSV file with the list of invoices that have been included into the report.
Apart from them, the Modelo 390 has a new difficulty, which is the usage of reflection techniques.
XML file creation
AEAT provides a XML schema with the structure of the Modelo 390 XML file. For managing the XML file we will use the JAXB API that allow us to map Java classes to XML representation, making it easier to generate the XML file with Java objects (marshalling).
We create the set of Java class that maps the XML structure with the xjc command already included into the JDK. The generated classes are stored into the org.openbravo.module.aeat390.es.bean package
After that we just need to work with the generated classes as usual. When finished we just need to marshall the objects into the XML file using the JAXB API. The AEAT390Utility.marshallModelo390ToXMLFile() method is used for creating the XML file.
CSV file creation
A CSV file is a plain text file that stores data in a tabular way, usually using a comma-separated list of values. This kind of files are easily portable and can be opened by any spreadsheet software like Openoffice.org Calc, Microsoft Excel, etc.
The CSV file will contain the following list of columns:
| Document Type | Invoice Number | Business Partner | Invoice date | Accounting Date | Tax Rate | Tax Rate % | Tax Amount | Taxable Amount | 390 box |
The AEAT390CSV class is in charge of managing all the CSV related stuff.
Reflection techniques
Reflection is a feature in the Java programming language. It allows an executing Java program to examine or "introspect" upon itself, and manipulate internal properties of the program.
This technique in conjunction with a well defined tax report configuration allows us to write generic code that covers scenarios that can be easily extended in the future. Example: the BaseImponibleyCuota section of the XML file contains several elements (RegOrdinario, AdqIntracomBienes, etc.) with the same elements inside (Tipo4, Tipo7, etc), and these elements contain exactly the same elements (BI and Cuota). Let's see it:
In the definition of the tax report we have included new columns that defines the factory method used for creating an object that maps each XML element, the XML element that a tax report parameter represents, if we need to split by tax rate percentage, etc.
The Java code reads all this configuration and uses it to create the right objects that will later on be included into the XML report as new elements.
This technique allows us to include new tax parameters in the future without writing new Java code!
Class diagram
This module uses the framework available in the Tax Report Launcher. This basically means that we need to have Java class that implements the OBTL_TaxReport_I interface and dataset that defines the input and constant parameters, and the relationship between tax parameters and tax rates in the application.
The AEAT390Report2011 class implements the OBTL_TaxReport_I interface and it's the most important one because it contains all the business logic for generating the 390 file. The generateElectronicFile() method is the entry point to the class, that will first of all initialize the report's configuration parameters (initializeConfigurationParameters() method) and check all the data for launching the report is OK (checkData() method). After that the initializeClassAttributes() method initializes other relevant class attributes.
The rest of the methods in this class are in charge of generating different parts of the final XML file. Special attention deserves the generateOperacionesRegimenGeneral(), exploreRegGeneralGroups() and exploreTaxableAmountGroups() methods that use reflection techniques to create its correspondent XML elements based on the data defined in the Tax Report configuration.
The AEAT390Report2011 class delegates all the access to the data stored in the database using DAL (Hibernate) to the AEAT390Report2011 Dao class.
As commented before, the org.openbravo.module.aeat390.es.bean package stores all the classes automatically generated by JAXB (not shown in the image for simplicity). Apart from them, the AEAT390String class is used for working with the strings that will be included into the 390 report. It's in charge of checking no strange characters are included.
The AEAT390CSV class and its inner class AEAT390CSVLine class represent the final CSV file that includes the invoices transactions included into the report.
The AEAT390CalculationsHelper is a helper class designed for calculating the amounts to be included into each section of the report. It knows the logic to be applied in case of normal invoices, credit memos, reversal invoices, etc.
Finally, there are two more important class in the org.openbravo.module.aeat390.es.utility package developed as Utility classes: the AEAT390Utility is a general utility class and the AEAT390ReflectionUtility is specialized in the reflection stuff.
Dataset structure
The dataset, with an organization data access level, will contain the relevant information for 390 report of the following tables:
- OBTL_Tax_Parameter, which is the table that links the tax rates with the tax report parameters. The IsBusinessObject checkbox is enabled
- OBTL_Tax_Report, which contains the tax report definition. The IsBusinessObject checkbox is enabled to get Tax Report Groups and Tax Report Parameters
The Tax Report definition (inside the Tax Report configuration window), will just contain a record for the yearly basis 390 report associated with the org.openbravo.module.aeat390.es.report.AEAT390Report2011 class.