XBRLmapper: Difference between revisions

From XBRLWiki
Jump to navigationJump to search
(5 intermediate revisions by the same user not shown)
Line 17: Line 17:


# 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 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 one of the data repositories can be accessed by an instantiation of a driver
# 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 his own configuration file
# Each driver has its own configuration file
# Drivers are defined for the repository data format
# Drivers are defined for the repository data format
# The generation of an XBRL report may involve several drivers looking at data in different repositores simultaneously
# 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
# 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
# Multiple drivers of the same repository type can be used concurrently
Line 43: Line 43:
===The instance document template===
===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 one of the facts 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 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 straingt forward process that can be initiated from two different sources, the file can be adapted to cover more complex mapping scenarios later.
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.
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.
Line 51: Line 51:
====From a DTS (A set of Taxonomies and Linkbases)====
====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 exists 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 prepating a sample instance document and convert the sample report into an instance document template (See the next section).
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.
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.
Line 65: Line 65:
====From a sample XBRL report====
====From a sample XBRL report====


In this case, the instance document template will be generated according to the facts that already exists in an XBRL Report. The XBRLMapper tool will take the instance document and will prepare an [[XBRL Template File]] for all facts that exists in the instance.
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 exists 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.
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:
Steps to produce the initial template file:
Line 129: Line 129:


==Moving XBRL data (Loader)==
==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 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===
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.


==Navigate==
==Navigate==
[[Main Page]]
[[Main Page]]

Revision as of 12:02, 8 October 2009

File:XBRLMapperMain.png
XBRL Mapper tool main window

Product page

[XBRL Mapper 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:

  1. Automatic generation of XBRL reports from different data sources
  2. 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:

  1. 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
  2. Isolates the complexity of the internal data repositories. Each of the data repositories can be accessed by an instantiation of a driver
  3. Each driver has its own configuration file
  4. Drivers are defined for the repository data format
  5. The generation of an XBRL report may involve several drivers looking at data in different repositories simultaneously
  6. The same event could be potentially attended by more than one driver if this is required
  7. 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)

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:

  1. Preparing an instance document template. This is the definition of "mapping events"
  2. 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:

  1. Open Loader Editor tool
  2. In the "Mapper" menu, select the "New Template from DTS" option
  3. In the Compose DTS dialog, select the required files
  4. 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).
  5. 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).
  6. 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:

  1. Open Loader Editor tool
  2. In the "Mapper" menu, select the "New Template from Instance" option
  3. Find the XBRL Report that must be a local file
  4. 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).
  5. 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).
  6. A template will be generated and loaded into the XBRLMapper main window.

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:

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:

  1. Creating a simple instance document template
  2. Create some raw data in Excel and map it
  3. Use the XBRLMapper GUI 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.

Moving XBRL data (Loader)

Reporting Standard offers two alternative ways to store XBRL information.

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.

Navigate

Main Page