XBRLmapper
Product page
Description
XBRLmapper is a sophisticated tool that transfers data from information systems to XBRL reports and from XBRL reports to other systems. It supports then two different purposes:
- Automatic generation of XBRL reports from different data sources
- Automatic extraction of data from XBRL reports and data loading into different repositories
Both products share a similar architecture. Both are based on a common definition of data events connected with the XBRL side and specific drivers that attend the data events. Both sides (definition of events, and drivers) can be configured using XML files. This architecture has multiple advantages:
- Isolates the complexity of the XBRL technology in one part (the definition of the data events). If there are changes in the taxonomy, the user may need to change just the definition of the data events
- Isolates the complexity of the internal data repositories. Each of the data repositories can be accessed by an instantiation of a driver
- Each driver has its own configuration file
- Drivers are defined for the repository data format
- The generation of an XBRL report may involve several drivers looking at data in different repositories simultaneously
- The same event could be potentially attended by more than one driver if this is required
- Multiple drivers of the same repository type can be used concurrently
The XBRL mapper is a software component that can be launched from a GUI or can be integrated in a workflow. The integration requires development of code (in Java or .NET) Starting with release 2.6.10 of XBRLizer the functionality of the XBRL mapper has been integrated in XBRLizer. The Mapper can still be used as a separate software component and integrated into any IT platform as a wervice without a user interface.
Generating XBRL (Mapper)
Generating XBRL reports is one of the operations for which the mapper was conceived. In this documentation Mapping is the process of obtaining data from data repositories in order to create an XBRL report.
The XBRL Mapper product designed by Reporting Standard S.L. can be used in the most complex scenarios. The XBRL Mapper is robuts, powerful and flexible.
- Robust because it is based on a native XBRL API that supports 100% Conformance level with XBRL Validation
- Powerful because it is based on an architecture that allows the users to plug-in drivers prepared to read different data sources and prepare combinations of data sources attending "mapping events".
- Flexible because it allows users to easily migrate to new taxonomies by just changing the instance document template but maintaining the same "mapping event" names and driver configurations. Or to adapt the system to obtain data from different data sources while using the same target taxonomy.
The configuration of the mapping engine requires then two steps:
- Preparing an instance document template. This is the definition of "mapping events"
- Preparing the configuration file for the driver(s) attending "mapping events"
The instance document template
The instance document template is the configuration file where the "mapping events" are defined. As the name suggest, the instance document template resembles an XBRL report but it is parameterized in order to turn each fact in a report into a "mapping event". It is important to notice that while the instance document template may have just one fact for a concept definition in the taxonomy, the response from drivers about requesting data for one mapping event may be multiple facts and, if this is the case, the final output file will have multiple facts as a result of multiple data items for the same mapping event.
The creation of an initial instance document template is a straight forward process that can be initiated from two different sources. The file can be adapted to cover more complex mapping scenarios later.
The [XBRL Template File]] page on this wiki explains the format of the template files and how the user can create their own files for more complex mapping scenarios.
From a DTS (A set of Taxonomies and Linkbases)
In this case, the instance document template will be generated according to all concept definitions that exist in the DTS (all taxonomy schemas providing item and tuple definitions for the DTS). If the purpose of the instance document template is just the concepts in a specific presentation hierarchy it would be more interesting preparing a sample instance document and converting the sample report into an instance document template (See the next section).
So, the creation of an instance document template from a complete DTS may generate a template with lots of events. The user should use this option if he is absolutely sure this is the way to go.
Steps to produce the initial template file:
- Open Loader Editor tool
- In the "Mapper" menu, select the "New Template from DTS" option
- In the Compose DTS dialog, select the required files
- Make sure there is a template file name in the dialog to generate a simple instance document template. The file name extension should be (*.xbrlt).
- Make sure there is one initial data source in the dialog to generate a simple instance document template (more data sources can be added later).
- A template will be generated and loaded into the XBRLMapper main window.
From a sample XBRL report
In this case, the instance document template will be generated according to the facts that already exist in an XBRL Report. The XBRLMapper tool will take the instance document and will prepare an XBRL Template File for all facts that exist in the instance.
This process generates a template with just the facts that exist in the instance document provided as a parameter. Hint: if the user wants to create an instance document according to the content of one single presentation linkbase, the user can use the XBRLizer tool in order to generate a sample instance document for the presentation tree and then use that file as input for the process of creating the instance document template.
Steps to produce the initial template file:
- Open Loader Editor tool
- In the "Mapper" menu, select the "New Template from Instance" option
- Find the XBRL Report that must be a local file
- Make sure there is a template file name in the dialog to generate a simple instance document template. The file name extension should be (*.xbrlt).
- Make sure there is one initial data source in the dialog to generate a simple instance document template (more data sources can be added later).
- A template will be generated and loaded into the XBRLMapper main window.
From XBRLizer
The XBRLizer tool can also be used for generating instance document templates. The process is as follows:
- Open or create a new XBRL report. You can open an existing XBRL report or create a new one directly from the taxonomy.
- Use the File -> Save as Template for mapping menu option. This will turn the XBRL report into an XBRL template for mapping.
Optional steps:
- In you want to map to Excel content, export the report view to Excel as well. This will facilitate the mapping process later because the generated XBRL report will contain a document view that matches the structure of the exported Excel report.
- Open the generated template in the Excel AddIn for mapping and the exported Excel scheet; then, start doing the mapping process.
In the following link you can get further info about more Detailed explanation about Excel mapping process from XBRLizer.
Editing instance document templates
The XBRL Template File page on this wiki explains the format of the template files and how the user can create their own files for more complex mapping scenarios. For complex mapping scenarios the mapping file needs to be edited in an XML Editor.
Drivers
The vast majority of use cases for mapping can be implemented using one of the generic drivers already developed by Reporting Standard S.L. For special use cases it is always possible to develop specific drivers in Java or .NET programming languages
List of available generic drivers:
- Excel data source driver
- Google Sheets data source driver
- CSV data source driver
- Relational database data source driver
- XBRL data source driver
- Web form data source driver
Running the template
The Mapper engine wiki page contains an explanation about the two modes of operation:
- as a software component, or
- called from the XBRLmapper GUI
At this stage we assume the user has already finished the creation of an XBRL Template File as explained in the previous chapters. In general, the process requires following steps:
- Creating a simple instance document template
- Create some raw data in Excel and map it
- Use the XBRLMapper GUI or XBRLizer in order to produce an XBRL report
The process may look hard if it is the first time you do it but remember you are preparing templates and the idea is to reuse the same templates multiple times in the future once the templates and the mapping configuration files are there, the process of producing a new report is much simpler than the first time you go through it.
We continue now with the missing chapters but we are going to link with the relevant chapters also in the specific pages for the drivers.
Create some raw data in Excel and map
If you want to see how other drivers works find the explanation in the specific driver page.
First thing you need is the excel XBRL mapping plug-in. This plug-in is able to read the content of an XBRL Template File and show the user all events suitable to be used from Excel. For installation instruction of the plug-in please contact Reporting Standard.
Press the Load... button and open the XBRL Template File. Then, open the excel spreadsheet you want to map to XBRL. The mapping can be implemented in two ways:
- Using excel names for cells (and forcing the creation of names if names do not exists)
- Using excel cell address of the type Sheet1!C3
Once you have both things open, just select on the right the event to map and drag & drop the name to the cell with the data. The mapping will be stored in the Excel driver configuration file. If you have forced the creation of cell names, at the end of the work you'll have to save both, the excel file and the driver configuration files. If the user has not modified excel because mapping has been created only to cell addresses then the user should just save the configuration file for the mapper.
The advantage of not storing information in the excel spreadsheet is that the same mapping configuration file can be used with new excel spreadsheets without having to do anything else with the excel file. The excel could be generated by an external tool automatically.
The advantage of mapping to cell names rather than cell addresses is that after mapping is finished the user can still add rows and columns to the excel spreadsheet. The mapping will continue working as usual.
Use the XBRLMapper GUI in order to produce an XBRL report
This process is explained in the mapper engine wiki page.
Using XBRLizer GUI in order to produce an XBRL report
Open XBRLizer and select the File -> Create new XBRL report automatically menu option. XBRLizer will ask you for the template to use and will start processing the template. Once the template processing is finished XBRLizer will ask you for data for each one of the drivers in use (Excel files are the source for Excel drivers). Once the information is supplied (Excel data for the Excel drivers) the template will be executed and the new report will appear in the report pane.
There is more information at the process of creating an XBRL report from a template page
Moving XBRL data (Loader)
Reporting Standard offers two alternative ways to store XBRL information.
- The data loader (described here)
- The XBRL Database
The data loader is useful in the following scenarios:
- The user already has a repository of information and for him, XBRL is just a transitory format to exchange information.
- The user is not interested in storing all the information that is transmitted in an XBRL report but only in some elements.
The definition of the loading events
The XBRL Data loader works using the concept of a data loading event. A data loading event consist of a filter definition that operates on the incoming XBRL report. The user can define the different facets of the filter. Facts that pass the filtering conditions will be automatically send to the apropriate drivers.
Drivers
Drivers are responsible of dealing with the storing format. They receive the event from the loading event layer and work with the target format in order to make the data persistent.
An Excel driver, for example, is able to open/create a new excel workbook. Locate the target cell and put the fact value in the destication cell. An SQL Driver is able to write an SQL INSERT statement and populate a table with the incoming data.
