Hey, how can we help?

Creating your first ESEF report can feel like a big task, but with the right tools and a clear process, it’s completely manageable. This guide walks you through the essential steps to build and export your ESEF report using Tangelo. From setting up your general data to tagging financial facts and reviewing the final output, you’ll learn how to move through each phase with confidence. Whether you're a first-time filer or just getting familiar with the Tangelo ESEF module, this article is designed to help you get started smoothly and efficiently.

1. Enter ESEF general data

Begin by filling in the general ESEF settings in the root section of your Tangelo document. This includes essential details:

• Reporting period
• LEI code
• Currency (see the property ‘ESEF - currency’ in the properties of the document’s root section

Important: Ensure that the language of the report is set in the document properties.

🔗 Also see: 

• How to insert iXBRL General Data
• Setting General data and hyper tagging for ESEF

2. Add required hypertags based on the report’s content

Hypertags are essential in ESEF reporting, enabling the precise tagging of ordered facts about an organization. These inline tags link specific sections of text to the appropriate taxonomy elements, ensuring that your report is well-structured, compliant with regulatory standards, and easy to navigate. By tagging key elements, hypertags help streamline the process for both auditors and automated systems to access and validate important information.

To correctly tag content, refer to List of text tags (hypertags/inline tags) for your report. These tags must be applied to the corresponding parts of the text, such as:

• Name of the reporting entity
• Domicile of the entity
• Description of the entity's operations
• Legal form of the entity
• Explanation of any departures from IFRS
• Sources of estimation uncertainty with significant risk

For a correct filing, ensure that all relevant tags are used in the proper sections. For example, if the reporting entity has changed its name, include the appropriate tag to explain the change. Similarly, if the entity’s financial statements are not prepared on a going concern basis, you must tag this with an explanation.

Tip:
Some tags may not be applicable, such as when there is no parent entity. In such cases, it’s important to note that while the ESEF validation system might show warnings, these can generally be ignored. Additionally, hypertags can only contain text. They should not include non-text content like tables or images to maintain compliance.

Before finalizing your report, ensure you review which hypertags are required in your specific case with your auditor. This review will help confirm that all necessary tags are applied and that no critical information is omitted, ensuring compliance and reducing the risk of errors in your filing.

🔗 Also see: 

• How to use ESEF Hypertags
• Setting General data and hyper tagging for ESEF

3. Set ESEF containers

Tangelo uses ESEF containers to structure your report in line with the ESEF IFRS taxonomy. These containers define which section of the financial statements a group of facts belongs to, allowing the ESEF engine to correctly generate the presentation and calculation linkbases in the final ESEF package.

Important:
The ESEF IFRS taxonomy defines a fixed set of containers (e.g., Statement of Financial Position, Statement of Comprehensive Income, Statement of Changes in Equity, etc.). These are not editable or customizable. You must select from the predefined set.

What you need to do:

• Assign the correct container to the row of the first line item of each financial statement section using the property ‘ESEF - container’ in the row properties in a table in Tangelo.
• This tagging informs the system which part of the statement each fact belongs to.
• Tangelo uses this mapping to place the facts in the appropriate section of the presentation linkbase, which is required by ESMA regulations.

Examples of containers:

• StatementOfFinancialPosition
• StatementOfComprehensiveIncome
• StatementOfCashFlows
• StatementOfChangesInEquity

Each of these containers must be applied to the correct rows in your statement in the Tangelo editor to ensure your data is structured according to the ESEF specifications.

Tip:
Be consistent when tagging rows. Container assignment should match the structure of the financial statements as disclosed in the report.

🔗 Also see: 

• How to set iXBRL containers

4. Tag all relevent facts in the consolidated financial statements

This is one of the most critical steps in the ESEF preparation process. You’ll need to tag all numerical facts presented in the primary financial statements. These facts are mapped to the ESEF IFRS taxonomy to ensure the report is machine-readable and semantically accurate.

You must provide detailed tagging for the following core statements:

• Statement of Financial Position
• Statement of Comprehensive Income
• Statement of Cash Flows
• Statement of Changes in Equity

For each of these, be sure to:

• Tag all rows that contain numeric facts (e.g., assets, liabilities, income, expenses)
• Apply the correct ESEF taxonomy concept
• Use the appropriate monetary precision and sign (positive/negative)
• Set the correct context (e.g., current period, prior period)

🔗 Also see: 

• How to tag (financial) facts
• Setting General data and hyper tagging for ESEF

Special attention: statement of changes in equity

The Statement of Changes in Equity often presents the most complexity due to its structure and required tagging approach. Here’s what you need to watch for:

Tagging equity components and movements

Each component of equity (e.g., share capital, retained earnings, revaluation reserves) must be tagged individually.

Movements such as:

• Dividends declared

• Total comprehensive income for the period

• Issue or buy-back of shares

• Transfers between reserves

must also be tagged and connected to the correct axis and member in the taxonomy.

Handling dimensions

The equity table uses dimensions which must be applied to tag facts in the correct context. This means you must not only tag the numeric value but also associate it with the correct equity component via dimension–member combinations.

Ensure that the correct members are set in the header cells of the table. Use the taxonomy browser to select the appropriate standard member, or create custom members if an extension is required.

5. Set XBRL properties

Make sure all facts are:

• Using the correct monetary precision
• Tagged with the appropriate sign usage (positive/negative XBRL fact value)

You can review and adjust these in the table row or cell properties panel.

🔗See more: 

• How to overwrite the standard monetary precision for a specific line item
• How to set correct fact signing in ESEF

6. Add block tags to the notes

As described in our article on notes preparation, block tagging is essential for complying with ESEF rules for textual information.

• Apply block tags at the section or paragraph level only.
• Use reverse tagging for more granular tagging needs.

🔗See more: 

• How to do block tagging
• Preparation of the Notes to the Consolidated Financial Statements

7. Run the ESEF export

Once everything is tagged, run the ESEF export to generate your draft filing package. This export includes:

• Inline XBRL (.xhtml)
• Extension taxonomy (.xsd, .xml)
• Label and reference linkbases

8. Check the validation report

After export, a validation report is automatically generated. This helps you identify and correct any tagging errors or missing data before submission.

9. Check xHTML on completeness (Final Step)

Before finalizing your report, ensure that the xHTML output is complete and adheres to ESEF requirements:

• Verify that all necessary sections are present and correctly formatted.
• Confirm that only internal section links (anchor links) are used. External hyperlinks (e.g., to websites or external documents) are not allowed in ESEF xHTML output, as per ESMA’s Reporting Manual.

This step ensures your report is structurally correct and valid for final submission.

 Tips for first-time filers

• Start early: Block tagging and sign checks can take time, especially the first year.
• Work in phases: Don’t try to tag everything in one sitting. Break it down per section or statement.
• Use your consultant: Tangelo consultants are here to guide you through every step, don’t hesitate to reach out!

 What’s next?

Once you’ve completed your first draft ESEF report:

• Review the validation results
• Share with auditors for review
• Make necessary adjustments based on feedback
• Export your final ESEF filing package for submission

Need help?

Our support team and consultants are here to help! Reach out if you need assistance with any of the steps above or want a walkthrough tailored to your report setup.

Let’s make your first ESEF filing a success one step at a time.

In XBRL, you report both a human-readable report and machine readable tags. In the human readable report, you can report positive or negative numbers, and usually from the context it is clear to the reader how to interpret these numbers. However, there could be situations where there is ambiguity. In the machine readable version, no ambiguity is allowed to exist, and you have to make sure the signs of all reported values are correct.

Any type of expense for example can be shown as a negative number in the human-readable report: as it is an outflow it can make sense to represent this as a negative number. However, since the tag in the XBRL taxonomy already states it is an expense, reporting a negative number in the XBRL fact would actually represent an inflow.

The rule of thumb for setting the correct signs for XBRL fact values is to look at the wording and balance of the concepts in the taxonomy. In principle the default should be to always use positive values in the XBRL. If you report a negative value, that means the reported value differs from what would be expected for this concept.

Let's take a look at some examples to show how the sign in the XBRL fact can deviate from the sign in the readable report:

Finance costs is reported as a negative value in the human-readable report. In the context of the Profit or loss, it is an outflow, so this makes sense. However, looking at the wording and balance of the Finance costs tag, you see that this already indicates a cost, and the fact value should be positive.

Other finance income (cost) is also reported as a negative value in the human-readable report, as it is an outflow just as well. However, in this case you can see from the wording of the tag that it expects an income. In this case it is not an income, but a cost, and therefore the XBRL value should be negative.

Adjustments for finance income (cost) is reported as a positive value in the human-readable report, since in the context of the Cash Flow statement this is the case. However, since the tag again assumes adjustments for finance income, but this is actually adjustments for finance cost, a negative fact value should be reported.

For completeness, we can also look at the simple situation of Profit (loss) before tax. Since in this case a profit is reported, this is a positive value in both the human-readable version and the XBRL fact.

When to modify the default sign behaviour?

First of all, it is important to understand the above, and understand the desired situation. For some cases, this will be already the case. Because of the ambiguity in the readable version, we cannot with certainty set the XBRL fact to the correct sign, and you might need to control this in Tangelo.

A good indication that the signs of the fact values in your report are not set correctly is if you are getting calculation inconsistencies. However, there can be facts that are not a part of a calculation, and it is worthwhile to check all.

To control the sign of the XBRL facts in the report, you can use the "Concept is negative" property in Tangelo. This is available on the row level for if you want to consistently set a certain sign for the entire row, or on the cell level if you want to set this for a specific year. Using this property you can explicitly set the fact value to either positive or negative.

See the table below on how to use this attribute to accomplish specific results for the XBRL fact value:

Credit (or no balance set in the taxonomy)

Debit

Further reading

ESEF Reporting Manual, Guidance 1.6: https://www.esma.europa.eu/sites/default/files/library/esma32-60-254_esef_reporting_manual.pdf

https://www.corporatings.com/blog-post/best-esef-practices-how-to-avoid-of-sign-errors

As the guidelines of regulations are updated every year, sometimes block tags are added, changed or moved.

As of FY 2024 some block tags that used to be regular block tags are now moved to inline tags. 

The difference between regular block tags and inline tags is, that inline tags can be applied in a sentence and can contain certain words instead of a whole paragraph of section. Inline tags are also used in the general data. 

The following regular block tags have been moved to inline tags: 

• Length of life of limited life entity
• Explanation of departure from IFRS
• Explanation of financial effect of departure from IFRS
• Explanation of fact and basis for preparation of financial statements when not going concern basis Explanation of why entity not regarded as going concern
• Description of reason for using longer or shorter reporting period
• Description of fact that amounts presented in financial statements are not entirely comparable
• Explanation of sources of estimation uncertainty with significant risk of causing material adjustment

See how to set inline tags here.

This happens often during setup. The engine didn’t recognise the label in the first column of the table.

Next to spotting this in the preview using the "Highlight" feature in the top right of the screen, you can also spot these errors in the "Conversion report" section of the error report.

There can be various reasons why labels are not being recognized:

1. Some labels always need a custom label to be recognized correctly. This is indicated in the Excel you received when the initial mapping was done. An example is the "Balance at 1 January 20xx" in the Statement of Changes in Equity. For this line you always need to set the ESEF label property on the table cell that contains the text, and set it to "Equity at beginning of period".
   
2. This can be because the text in the table has been changed from what has been mapped before. In most cases the mapping has been done correct earlier but the labels have been changed since. Sometimes to fix a spelling mistake, sometimes because it will look better in the document. Ideally the new spelling is added to the mapping. So if you are still gathering input for mapping changes, please include these cases in the update of what is changed.
   If the change in label is minor and you are sure that it is not an indicator that a different tag should be selected for this line item, this situation can also be fixed by adding the original text to the ESEF label property on the table cell that contains the label.
   Please note: even adding or removing a space, - or other (on first glance) minor changes, can cause cells to not be recognised by the engine. The engine uses auto-tagging, but only when the exact label is known to the system.
3. If it is a new label, then this should be mapped. Please note that it will take at least a full week for a mapping change in the engine. It is wise to freeze changes a week prior to publishing the ESEF file.
4. A custom label was set while not needed or not removed correctly. Remove the ESEF label property by using the trashcan.

In most cases cells aren’t recognised by the engine due to changes in wording, this is the best way to start your investigation and gives the quickest results.

A positive number was expected by the XBRL taxonomy but the number provided in the report is negative. XBRL taxonomy expects a positive number here and not a negative.

This could be a false positive, if you are reporting an exceptional situation, for example a negative value for a reserve. However, it could also mean that the value is not tagged correctly.

In XBRL, the fact value should always be relative to the balance of the concept that is chosen for the fact.

For example, the concept ifrs-full:CostOfSales is a debit concept in the IFRS taxonomy. So while you are likely to report this as a negative value in your readable version of the income statement, the underlying fact value in the iXBRL should be positive.

In most cases this is handled automatically. However, if you find out that for some of your line items this is not done correctly, you can correct this by setting the Concept is negative property on either the table row or a specific table cell to set it explicitly.

To find where these negative values are in your report you can use the preview feature and step through the financial statement values using the arrows in the top right. Check for negative values here, and review if they indeed should be negative.

This error in the top of your log output and needs to be resolved, it causes an incorrect filing packages as it will also generate the following error: 

Depending on your auditor, these can be ignored or should be addressed. 

The reason behind the illegal positive is that there is a value presented as debit but it should be credit, or it is changing from debit to credit or the other way around. In the example here above, Dividend with the value 1.000.000 should be a positive number, but is presented as a negative number, of the other way around. XBRL knows what items should be credit or debit and expects numbers to reflect that. However human readers need context as they do not know if a statement is a credit or debit statement. This often results in these errors.

The error also states where the number is located. In this case in chapter 3.2, table 6. That makes it easier to pinpoint the number. Pasting the ifrs-full:Dividend into the search bar of the inline viewer will cause you to jump to the correct number al well. 

In the report / statement the number will be written in a certain way for humans to be able to read it. For example dividend written as a negative number, while the number itself should be positive as the system automatically knows if its debit or credit here. 

In Tangelo under the cell properties, this situation can be reversed by using the "concept is negative" attribute:  (below: Esef - concept is n....)

This reverses the credit / debit value of a specific cell. 

Be careful as this also can generate other errors, since the system now handles the number differently. This can cause calculation errors on other statements. 

All the things you need to know to do your ESEF filing in Tangelo without hassle ánd with a correct file. 

We have created a video specifically for the yearly roll forward in Tangelo. In 30 minutes we will guide you through all the steps you need to do, check, and more over: not to check, to end up with a succesfull ESEF file to share with your auditor or file. 

We will go through: 

1. Doing a roll forward of last years document
2. Checking and changing the publication dates
3. Checking the primairy statements
4. Checking the hyper tags 
5. Checking and changing the block tags
6. Running the block tag list export for you and your auditor

After these six steps your ESEF document is ready to go. Watch our video below. 

The easiest way to check if your block tags are placed correctly is to run the "Block tags report" export. You can find this export in the document menu at the top of the table of contents view in Tangelo.

This will provide an overview file (.xlsx) of all block tags from the "Tags that must be applied if corresponding information is present in a report", and the name of the section(s) in which it is applied.

To check the tagging in detail, you can use the ESEF preview as described in the steps below.

Step 1: Run the ESEF wizard in Tangelo

Run the ESEF wizard on your document. 

Step 2: Go to the preview of ESEF in Tangelo

Then go to the preview of the ESEF file. This will open a new window in your browser that displays your xHTML file from the ESEF package. 

 The middle button will open the preview .

Step 3: Check if a section has a block tag

Scroll to the section or element that is tagged.  When clicking somewhere in that section or element, a blue box will appear around the content that is tagged. This indicates there is an ESEF element, just as it does in Tangelo itself. Hovering over the section/element will display a blue box as well, indicating there is an element there. This blue box only appears when clicking on the content that is tagged or hovering over it.

Step 4: Check the block tag(s) itself

To see what tag a block is tagged with, see the properties pane on the right side of your screen. If you haven't clicked on the content yet, the properties will be empty: 

However, as soon as an element is clicked and the blue box appears, the properties pane will display the information about this section/element: 

In this example the properties pane displays that there are two block tags being used. The first is the block tag: ifrs-full:DescriptionOfReasonWhyFinancialStatementsAreNotEntirelyComparable and the second is ifrs-full:DisclosureOfAccruedExpensesAndOtherLiabilitiesExplanatory.  

The viewer always displays the full IFRS tag. 

These are the IFRS tags taken from the input in Tangelo.

This how-to will give a quick overview of the Tangelo application. For more detailled information please browse our Help Center. 

After you have logged in to Tangelo, the main screen will appear. 

Here Tangelo will show recent documents you have opened (if you are a new user this will be empty), available document types and on the top right of your screen it shows tabs with options within Tangelo, depending on your role in the system. 

Recently viewed by you displays documents you have recently opened. This list wil be populated by documents you have opened and is therefor prone to change. The list includes all documents from all document types. 

All documents displays available document types. A document type is a type of branded document. Every document type contains the layout information of the documents inside that type. For instance the Annual Report in the above example will hold all documents in the formatting of the annual report branding. 

The hamburger menu behind the document name in the recently viewed by you reveals the actions you can do with the document, depending on your user rights. 

Click a document to open it, or click on the document types icons to go the correct document type and select your document to open there. 

After you have selected the document type, Tangelo will display a list of documents to edit. 

Open the document by clicking on the document. Or use the hamburger menu to use other options (depending on your user rights)

Creating a PDF of a document

In the screen above you can select Create PDF. This will prompt a window to generate a full PDF of the whole document without editing the document. 

Some options can be set, for example, if the document uses different versions, the Show changes menu will show the option to compare different versions of the document in a PDF output. 

To generate the PDF click on the PDF button: and Tangelo will generate a full PDF of the document, this is the end result of the document. If needed select the Print option at Format to generate the full print ready version of the document. 

Opening a document

Click on the document, or select Edit in the hamburger menu to open the document. 

Tangelo will show the tree structure of the document, with all sections, chapters, paragraphs etc. In some cases the tree will not be expanded and it will look like this: 

Click on the logo in front of the document title to open the document tree. Use CTRL+click to open the whole tree and view all sections / chapters / paragraphs, etc.

Double click on a title of a section to open the Tangelo editor. 

The hamburger menu has extra options per section:

Adding a section / chapter / paragraph / subparagraph

To add something to the document tree, use the Add menu hamburger menu. Depending where you are located inside the document tree, options will appear. For example: a paragraph is always nested inside a chapter and a subparagraph inside a paragraph. Adding a paragraph in a section is not possible since it is a child of a chapter and will therefor not appear in the add menu when using the hamburger menu on a section. 

In the above case we can add a chapter to a section, but only a chapter, no paragraph. Or we can add a section before or after this section. The same goes for paragraphs and subparagraphs, it depends where in the tree you are located. 

Moving things around

Moving of chapters / paragraphs etc, is very easy in Tangelo. Use the hamburger menu and go to the move menu. 

You can manually move something one place above or one place below it's current position in the tree. 

Tangelo uses a hierarchy or levels. So a paragraph can not be moved to the same level as a chapter. You can cut or copy and past sections / chapters / paragraphs, etc, but pasting can only be done at the same hierarchy level. Since that level determines the design. 

Removing a section / chapter / paragraph / subparagraph

To remove a section / chapter / paragraph / subparagraph or anything else from the document tree, use the hamburger menu and select Delete. Please note that once it's deleted, it is deleted forever and that content can not be recovered anymore. 

Editing a chapter

Double click on a node in the tree to edit that specific section / chapter / paragraph, etc.