FMR Workbench

Overview

The FMR WorkBench (FWB) is a User Interface (UI) for browsing and maintaining SDMX Structures obtained from SDMX compliant Structure Web Services. The UI of the FWB is a stripped-down version of the Fusion Metadata Registry (FMR) User Interface; it is stripped down because the UI of the FWB supports the use case of viewing and maintaining structural metadata, whilst the FMR supports additional use cases including data validation, data conversion, and has administrative UI pages. Whilst the FMR uses a database to store its configuration settings, the FWB configuration is stored in a file. The FWB has no database requirements.

The FWB UI browses and displays the SDMX structures of the Environment it is connected to. An Environment is a connection to a collection of related SDMX web services for a single SDMX service offering. Related web services include the web service entry point to retrieve the structures, the entry point to save structures, and the entry point to delete structures.

The UI of the FWB enables the user to switch their connection to an alternative Environment; the list of available Environments is defined in the configuration file for the FWB. The connected Environment is associated with the current user; this enables multiple users of the FWB to be connected to different Environments simultaneously.

Getting Started

The FMR Workbench (FWB) is deployed as a Web Application Archive (war) file. The war file must be deployed to a Java Servlet container such as Apache Tomcat. The Servlet container will host the application so that it can be accessed over HTTP as a web application.

Configuration File Location

The FMR Workbench does not use a database, instead it obtains its configuration settings from a configuration file called fwb_config.json.

An example configuration file is provided with the software. The configuration file needs to be placed in the following directory (the directory must be created if it does not exist):

<USER HOME>\MetadataTechnology\FusionRegistry

Example:

C:\Users\Matthew Nelson\MetadataTechnology\FusionRegistry

Configuration File Properties

Showing the switch environment options

The configuration file is split into 2 parts:

1. Server Properties
2. Environment Definitions

{
   "Properties": { server properties go here },
   "Environments": [ environment definitions go here ]
}

Properties
There is only 1 property which is required for the FWB, this is the URL to the FWB application. This property enables the application to know where to find required resources, and how to redirect users to the correct pages.

"Properties": {
   server.url: "http://localhost:8080/fwb"
}

Localhost can be used for testing purposes when deploying the application to the same computer that the web browser is run from. For a live deployment this URL must be changed accordingly.

Environments
The Environment property has an array of JSON Objects. Each JSON Object in this array defines a distinct Environment which the FWB can switch to in order to browse and optionally create/maintain the SDMX Structures of that Environment.

An Environment consists of an id and a name and defines the web service entry points to retrieve, save, and delete structures. The retrieve web service is required, the save and delete entry points are optional.

The Environment definition also contains details on the authentication mechanism used to access the contents of the web services.

An example of an Environment definition is given below:

{
   "id": "DOT_STAT",
   "name" : "Dot Stat Test",
   "api": {
       "query": "https://nsi-demo-reset.siscc.org/rest",
       "persist": "https://nsi-demo-reset.siscc.org/rest/structure",
       "delete": "https://nsi-demo-stable.siscc.org/rest/structure",
       "version": "1.5.0"
   },
   "agencies": ["SDMX", "METATECH"],
   "auth": "OIDC_PKCE",
   "locale": ["en", "fr"],
   "oidc": {
       "config": "https://keycloak.siscc.org/auth/realms/OECD/.well-known/openid-configuration",
       "clientId": "app"
   },
   "format": "mlv2.1"
}

The following table describes the properties for an Environment definition based on the above example:

Property	Description
id	Required This is the ID of the Environment. It is used in the REST API to switch environments
name	Required The name of the Environment as presented to the user
api	Required contains the base SDMX REST URL for each web service of the Environment
api.query	Required structure query web service
api.persist	Optional to support add/edit functionality. HTTP POST messages will be sent to this URL
api.delete	Optional to support delete functionality, HTTP DELETE messages will be sent to this URL
api.version	Required the Version of the SDMX REST API. Supported values are 1.5.0 and 2.0.0
api.timeout	Optional maximum number of seconds to wait for response from API before timing out. Defaults to120 seconds.
format	The SDMX structure format used when POSTing structures to web service (for the use case of structure persistence). Options include: mlv2.1 – XML format SDMX-ML v.2.1 mlv3.0 – XML format SDMX-ML v.3.0 jsonv1 – JSON format SDMX-JSON v.1.0 jsonv2 – JSON format SDMX-JSON v.2.0 fusion – the FMR specific format. This format should be used if connected to another FMR instance as it covers both SDMX structures and non-SDMX structures such as Publication Tables and Reporting Templates

Apache Tomcat Example

Showing the home page of the Fusion Workbench

If using Apache Tomcat, the war file would be placed under the ‘<tomcat>\webapps’ folder.

The name of the war file will be the name of the Web Application when accessed in the web browser, for example if the war file is called fwb.war, the application would be accessed using the following URL syntax:

http(s)://[server]:[port]/fwb

Apache Tomcat can be started using the bin\startup.bat or on unix bin\startup.sh script. An alternative is to start Tomcat as a windows service.

On Tomcat startup the war file will be unpacked, creating a folder of the same name in the <tomcat>\webapps folder.

After Tomcat has started the Fusion Workbench would be accessed from the following URL.

http://localhost:8080/fwb

This URL assumes the following conditions are true:

1. The web browser is running on the same machine as the Tomcat server (localhost refers to the local machine).
2. No configuration changes have been made to the official distribution of Apache Tomcat (default port is 8080).
3. The FWB distribution has the file name fwb.war (fwb.war resolves to /fwb in the URL path)

Assuming the configuration files are in the correct folder and are valid JSON with no missing required properties, the URL will resolve to the UI of the FWB.

Error Resolution

If the home page of the FWB fails to load, please check the log files from Apache Tomcat. Other than the Apache Tomcat log files, the FWB will create 2 application specific log files:

1. FMRWorkbench.log – this file contains all logging output from the FWB. Logs are output if they have a level of INFO or higher.
2. FMRWorkbenchErrors.log – this file contains a subset of the logs from FMRWorkbench.log. It only contains logs that were written with a severity of WARN or higher.

To change the logging level, edit the logback.xml file which is found under the following location in Tomcat

<tomcat home>\webapps\fwb\WEB-INF\classes\logback.xml

Switching Services

The header bar of the FMR-Workbench contains a button showing the currently connected service, clicking on this button will open a window to allow a different service to be connected. By default the service is connected to anonymously, meaning only browser functionality will be supported.

To authenticate, click on the Login button after connecting to the service.

Authentication

The FMR Workbench supports 2 forms of authentication with the connected service: Basic Authentication and OpenID Connect. The type of authentication is set up in the Config file of the FMR-Workbench.

Basic Authentication

Clicking Login will take the user to the FMR-Workbench login page where the user is invited to enter a username and password. These details are stored in the FMR-Workbench against the user's session, and they are used whenever the user interacts with the target service. An initial check is performed against the target server to ensure the credentials can be used to obtain some structures, if the check fails then the details are deemed to be invalid and will be discarded.

Open ID Connect

Clicking Login will take the user to the OpenID Connect login page (defined in the configuration file of the FMR-Workbench). The user authenticates with the chosen OpenID Connect authentication provider, on success the user is redirected back to the FMR-Workbench with a token. The token is stored against the user's session, and used to authenticate with the target service.

Structure Navigation and Export

The FMR-Workbench front end will display structures in the same way the FMR provides - clicking on a sidebar item (example Codelists) will display the Codelist page and all the Codelists in the connected service. This is achieved by the front end issuing a SDMX web service query to the FMR Workbench for all Codelists as stubs. This query is then forwarded to the connected service, and the response is written back to the client. The FMR-Workbench can receive the query response from the connected service in any SDMX format. The response will be parsed by the FMR-Workbench before being written out in the requested format. This means the FMR-Workbench is able to write the response out in ANY format that the FMR Workbench supports, including Excel, SDMX, and JSON. The user is therefore able to click on a Codelist and export it as Excel, even if the connected service does not support Excel as an output format.

It is possible to automatically link to a page in the Fusion Registry against a specific service by providing the env argument in the URL, for example:

https://fwb.sdmxcloud.org/?env=DOT_STAT_STABLE

The above link will take the user to a specific Concept Scheme in the User Interface, from the DOT_STAT environment.

https://fwb.sdmxcloud.org/items/conceptscheme.html?urn=urn:sdmx:org.sdmx.infomodel.conceptscheme.ConceptScheme=IMF:CS_BOP(1.11)&env=DOT_STAT_STABLE

The above link will take the user to the Concept Scheme Wizard (the edit pages for a Concept Scheme). The Concept Scheme wizard will be editing the CS_TOURISM concept in the DOT_STAT Environment. As this page is a secure resource, the user will be automatically redirected to the login page if they are not already logged into the service.

SDMX Web Service

It is important to note that the FMR-Workbench has the same web service entry points as the FMR, and whilst these web services work, they are not guaranteed to be fully compliant. The web services of the FMR-Workbench forwards queries onto the connected service. The queries may be modify to reduce the possibility of the target service not supporting the query. If the connected service reports any error in the query, the FMR-Workbench will report 'no structures' for the query.

The recommendation is therefore to not rely on the web services of the FMR-Workbench, instead use the web services provided by the target service directly.

Structure Creation/Modification

If the user has logged into the connected service, they will be able to upload structures from the home page of the FMR-Workbench, or create/edit structures using the standard Wizards in the User Interface.

It is important to note that the FMR-Workbench contains the same User Interface as the FMR, and as such does not provision for the fact that the connected service may not support all the features of the FMR. For example it may be possible in the FMR-Workbench to create a SDMX 3.0 DSD with multiple measures, but the target service may reject the save request.

It is possible to load structures in any format supported by the FMR-Workbench, including Excel - these structures will be converted into a format supported by the connected service on the save request.