View source | Discuss this page | Page history | Printable version   

AEAT390/Technical Documentation



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

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

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.

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]).


EM_AEAT390_FACTORYMETHOD VARCHAR(255) No Defines the factory method used for creating the equivalent XML element using reflection


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


This project has two main difficulties compared to other tax report launcher based modules:

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 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 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:

Aeat390 reflection.png

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.

Aeat390 classdiagram.png

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 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 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:

The Tax Report definition (inside the Tax Report configuration window), will just contain a record for the yearly basis 390 report associated with the class.

Retrieved from ""

This page has been accessed 3,141 times. This page was last modified on 5 January 2012, at 11:19. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.