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

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

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:

http://localhost:8080/FMR-WB/items/conceptscheme.html?urn=urn:sdmx:org.sdmx.infomodel.conceptscheme.ConceptScheme=OECD:CS_TOURISM(1.0)&env=DOT_STAT

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

http://localhost:8080/FMR-WB/items/conceptscheme-wizard.html?urn=urn:sdmx:org.sdmx.infomodel.conceptscheme.ConceptScheme=OECD:CS_TOURISM(1.0)&env=DOT_STAT

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.