The Workiva iXBRL Viewer allows Inline XBRL (or iXBRL) reports to be viewed interactively in a web browser. The viewer allows users to access the tagged XBRL data embedded in an iXBRL report. Key features include:
- Full text search on taxonomy labels and references
- View full details of tagged facts
- Export tables to Excel
- Visualize and navigate calculation relationships
- Produce on-the-fly graphs using XBRL data
The viewer project consists of two components:
- A plugin for the Arelle XBRL tool
- The Javascript viewer application
In order to view an iXBRL report in the viewer, it must first be prepared using the Arelle plugin. The preparation process updates the iXBRL file to include:
- A link to the Javascript viewer
- A block of JSON data that contains the results of processing the XBRL data and associated taxonomy
Once prepared, the resulting file provides an entirely standalone viewer. Once prepared, the viewer is entirely standalone, and does not require access to the taxonomy, or to any online services. The only dependency is on the javascript viewer application, which is a single file which can be accessed directly online, downloaded or built locally.
The javascript viewer application is a single Javascript file called ixbrlviewer.js. It contains all of the javascript that runs the viewer functionality.
The python portion of this repo is developed using Python 3.9.
- Clone the iXBRL Viewer git repository.
- Download and install Arelle
In order to make things as easy as possible Workiva is now hosting the javascript via a CDN. It can be accessed via the followng CDN url:
https://cdn-prod.wdesk.com/ixbrl-viewer/<version tag>/ixbrlviewer.js
Where <version tag>
is the current version of ixbrl-viewer you are using. For instance 1.0.0.
When a new version of ixbrl-viewer is released, the javascript is included as a release asset. The asset can be found on the releases page for each version of the ixbrl-viewer.
- Install npm. Instructions can be found here: https://www.npmjs.com/get-npm
- Install the dependencies for javascript by running:
npm install
. This command must be run from within theixbrl-viewer directory
(i.e. the root of your checkout of the repository). - Run
npm run prod
. This will create the ixbrlviewer.js in the iXBRLViewerPlugin/viewer/dist directory.
The ixbrl-viewer plugin embeds processed XBRL metadata in the HTML that has a specific format read by the JavaScript. The metadata produced by a version will be broken if a major version bump is released. The new javascript won't necessarily work with older versions of the generated metadata. if a minor version bump is released, then the metadata format was updated, any ixbrl-viewer produced on that minor version will have to use at least that minor version for the javascript.
-
Open Arelle and select Manage Plugins from the Help menu.
-
Press Browse under "Find plug-in modules".
-
Browse to the iXBRLViewerPlugin directory within your checkout of the iXBRL Viewer git repository and select the __init__.py file within it.
-
Press Close and then Yes when prompted to restart Arelle.
-
You should now have a Save iXBRL Viewer instance on the Tools menu.
-
Open the ixbrl filing zip in Arelle
-
Select Save iXBRL Viewer instance option on the Tools menu
-
Provide a script URL to the ixbrlviewer.js file.
This url can be one of the following:
https://cdn-prod.wdesk.com/ixbrl-viewer/<version tag>/ixbrlviewer.js
- A relative url to the downloaded ixviewer.js from github
- A relative url to the locally built ixviewer.js
-
Save the viewer iXBRL file to a new file in the newly created directory by selecting Browse, browsing to the directory, and providing a file name.
-
You should now be able to open the created file in Chrome, and the iXBRL viewer should load.
To prepare an iXBRL document set, open the document set in Arelle. The process is as for a single file, except that a directory should be selected as the output location, rather than a file.
The plugin can also be used on the command line:
python3 Arelle/arelleCmdLine.py --plugins=<path to iXBRLViewerPlugin> -f ixbrl-report.html --save-viewer ixbrl-report-viewer.html --viewer-url https://cdn-prod.wdesk.com/ixbrl-viewer/<version tag>/ixbrlviewer.js
Notes:
-
"Arelle/arelleCmdLine.py" should be the path to your installation of Arelle
-
The plugin path needs to an absolute file path to the ixbrl-viewer plugin
-
The viewer url can be one of the following:
https://cdn-prod.wdesk.com/ixbrl-viewer/<version tag>/ixbrlviewer.js
- A relative url to the downloaded ixviewer.js from github
- A relative url to the locally built ixviewer.js
The iXBRL Viewer supports Inline XBRL document sets. This requires the inlineXbrlDocumentSet
plugin. The input is specified using JSON in the following form:
[
{
"ixds": [
{ "file": "file1.html" },
{ "file": "file2.html" },
]
}
]
The output must be specified as a directory. For example:
python3 Arelle/arelleCmdLine.py --plugins '/path/to/iXBRLViewerPlugin|inlineXbrlDocumentSet' -f '[{"ixds":[{"file":"document1.html"},{"file":"document2.html"}]}]' --save-viewer out-dir --viewer-url https://cdn-prod.wdesk.com/ixbrl-viewer/<version tag>/ixbrlviewer.js
Notes:
-
The first file specified is the "primary" file, and should be opened in a browser to use the viewer. The other files will be loaded in separate tabs within the viewer.
-
"Arelle/arelleCmdLine.py" should be the path to your installation of Arelle
-
The plugin path needs to an absolute file path to the ixbrl-viewer plugin
-
The viewer url can be one of the following:
https://cdn-prod.wdesk.com/ixbrl-viewer/<version tag>/ixbrlviewer.js
- A relative url to the downloaded ixviewer.js from github
- A relative url to the locally built ixviewer.js
As an alternative to the standard Arelle command line, the
samples/build-viewer.py
script can also be used. To use the script, both the
Arelle source code and the iXBRLViewerPlugin must be on the Python path. e.g.:
PYTHONPATH=/path/to/Arelle:/path/to/ixbrl-viewer ./samples/build-viewer.py --help
A document set can be processed by passing a directory as input. All .html
and .xhtml
in the directory will be combined into a document set. The
generated files will be saved into the directory specified by the --out
option.
Taxonomy packages can be specified using --package-dir
. All ZIP files in the
specified directories will be loaded as taxonomy packages.
e.g.
PYTHONPATH=/path/to/Arelle:/path/to/ixbrl-viewer ./samples/build-viewer.py --out out-dir --package-dir /my/packages/ ixds-dir
In order to run the javascript unit tests make sure that you have installed all of the npm requirements.
Run the following command to run javascript unit tests: npm run test
In order to run the python unit tests make sure that you have pip installed requirements-dev.txt.
Run the following command to run python unit tests: nosetests