How to use

15 minute read

Elements of the frontend

All user interaction with the Data Governance component is done through its frontend. All functionality is accessed from a main menu on the left side of the screen. This can be seen in Figure 1.

The menu for the simple user is on the left side and (apart from Home) has six main items. The first four deal with dataset metadata: Search Datasets, Access History, Internal Datasets, External Datasets. The last two are user related and are Profile and Notifications.

The administrator’s menu has all the above items plus three that are administrator specific. The first is dataset related and is Organisational Datasets, while the other two are user related: Organisation and Users.

Search Datasets: shows a list of all datasets available in DG, along with search criteria that can be set to help find a suitable dataset.

Access History: shows the user`s personal history of access requests, pending access requests and of access revocations to external datasets.

Internal Datasets: shows a list of datasets that have been added by the user, along with a button to add new metadata.

External Datasets: contains three tabs (Personal, Organizational, Public), each showing external datasets that the user has access to due to personal, organisational or public permissions.

Organisational Datasets (administrator only): contains a table of organisational datasets for the logged-in administrator.

Organisation (administrator only): shows a list of metadata pertaining to the organisation of the logged-in administrator.

Users (administrator only): contains two tabs (Active Users, Inactive Users), the first showing a table of active users belonging to the administrators organisation and two buttons: Add UserandDeactivate Selected. The second tab shows the inactive users and an Activate Selected` button.

Profile: The user`s profile shows all data pertinent to the user, e.g. email, full name etc.

Notifications: Contains a list of notifications the user has received due to the actions of other users, e.g. access requests on one of the user`s internal datasets.

The following sections describe the most important of the above views.

Dataset searches and access requests

The Search Datasets view contains a number of search criteria, based on which a list of datasets is presented to the user. The view is shown in Figure 2.

The criteria available for searching appropriate datasets are the following:

• Dataset Provider Username
  Choose the username for the provider user
• Dataset Name
  Enter text for the dataset name, or part of it
• Industry Domain
  Choose the industry domain of interest
• Access Rights
  Choose the access rights (i.e. permissions) that must be available
• Custom Access Rights
  Enter text for the custom access rights (i.e. custom permissions) that must be available
• Keyword / Tag
  Enter text to search as part of the keyword/tag field
• Dataset Provider
  Choose the provider organisation
• Dataset Owner
  Choose the owner organisation
• Data Volume Min/Max (KiB)
  Enter the range of values that data volume must lie within
• Data Velocity Min/Max (KiB/sec)
  Enter the range of values that data velocity must lie within
• Has Agent
  Specify whether to search for datasets that are provided through a DataPorts platform agent or not
• Distribution
  Choose the desired distribution format
• Language
  Choose the desired language for the data
• Theme / Category
  Enter text to search as part of the theme/category field
• Version Min/Max
  Enter the range of values that the dataset version must lie within
• Spatial Geographic Coverage
  Enter text to search as part of the spatial geographic coverage field
• Temporal Coverage Start/End
  Enter the range of values that the dataset version must lie within
• Data Source
  Enter text to search as part of the dataset`s data source metadata

After filling out the desired search criteria, the user has to press the Search button to get a filtered list of available datasets, based on the criteria entered. The list contains various information on each dataset to give the user a general idea about the dataset (Figure 2). Principal among them is the DataSourceID missing column. This contains boolean values based on whether the provider has declared the dataset to be provided through the DataPorts platform by use of a data access agent, while not having actually selected a related datasource ID for the dataset. If that is the case, the column is marked Yes and coloured orange, as a warning. If the dataset is not provided through a data access agent, or if the datasource ID has already been selected, then the column is marked No.

Clicking on a dataset, from the filtered list of datasets found below the criteria, brings up a view of dataset details, like the one in Figure 3.

Here the user can view the dataset`s basic details, as well as a table of access rights (Figure 4).

The table is split into four sections, highlighted with coloured rectangles in Figure 4. The Access Right section (blue rectangle) contains the available access rights, both standard and custom, for this dataset.

The Personal section (orange rectangle) contains permissions information on the personal access level. Here, is shows that the user has no active personal access rights on the dataset (Active column), but has already requested read access (yes value for read in the Pending column). The user can additionally request modify or persist access on the dataset by checking the relevant boxes in the Request column and then clicking on the Personal Request button.

Similar to the Personal section, the Organisational section (green rectangle) shows the status of permissions the user has on the organizational level: read and modify active organizational permissions, pending persist permission. Here, the user has already asked for all of the available permissions, so no extra access requests can be made (all boxes in the Request column are disabled).

Finally, the Public section (brown rectangle) contains information about any public level permissions granted by the provider. Here, no public permissions are available.

Internal datasets and metadata creation

As already explained, Internal Datasets shows a list of datasets for which metadata have been added by the user, along with a button to add new metadata (Add Dataset). This can be seen in Figure 5.

Add dataset

Clicking on the Add Dataset button presents to the user the form shown in Figure 6.

The form contains a series of fields, most of them editable. These fields collectively form the Data Governance metadata. Only three fields are pre-filled and non-editable: the provider username (always the current user), the provider user`s email, and the provider organisation (always the organisation of the current user). Some fields are marked with an asterisk, meaning their completion is mandatory. Most of the fields are the same as those found in the search criteria. The extra ones are the following:

• Dataset Provider E-mail
• Dataset Description
• Agreement URL
  This must be a valid URL (which accepts CORS requests) of the text (in PDF format) of an agreement between the provider and any potential consumer to use the dataset in question
• Terms and Conditions URL
  This must be a valid URL (which accepts CORS requests) of the text (in PDF format) of the terms and conditions governing the use of the dataset in question
• Copyright URL
  This must be a valid URL (which accepts CORS requests) of the text (in PDF format) of a copyright statement for the dataset in question
• Endpoint
  If entered, this is meant to be the endpoint through which the dataset can be acquired – this can be a KrakenD endpoint
• Dataset Owner Username
  The username for the user acting as representative of the owner organisation
• Comments
• Data Source ID
  Once the Has Agent box is checked, the Data Source ID drop-down list appears. This contains the list of datasource IDs, coming from the semantic interoperability component of the DataPorts platform. Each such ID is created when a data access agent is created for a particular dataset. The user has to identify and select the correct ID pertaining to the dataset currently being described. To help with that, the drop-down list is searchable.
  Crucially, choosing and matching a datasource ID to some Data Governance metadata causes the DG component to request the relevant datasource metadata from the Semantic Interoperability component. The retrieved datasource metadata are then saved on the blockchain, together with DG metadata.

Internal dataset details

Clicking on a row of the internal datasets table (Figure 5) takes the user to the internal dataset details view that comprises the following seven tabs:

• Details
  Contains the metadata, as were described in previous sections. The only new fields are Agreement Hash, Terms and Conditions Hash and Copyright Hash, which are the MD5 hash values of the corresponding PDF files (Figure 7). The point of adding these hashes is to assure the consumer that the agreement, terms and copyright are the exact same documents that were initially given by the provider and are downloadable through the corresponding URLs.
  At the bottom there is an Edit button. By clicking it the provider is presented with an edit form, where they can change the values of the various DG metadata.

• Permissions
  The permissions tab comprises three, so to speak, sub-tabs, personal, organisational and public, which display the permissions given on these three different access levels.
  • The Personal tab shows a table with rows pertaining to each individual user that has been given some access rights to the given dataset. The columns of the table contain both user information (email, name etc.) as well as the specific rights granted. In Figure 8 we can see user adminVPF having been given personal read access to the current dataset. The blue checkbox is clickable. By clicking it and then clicking the Save Changes button, the provider can remove the given access right from the consumer user. The provider is also given the ability to remove access rights en masse based on user role, i.e. can remove an access right from all consumer users, or only from simple users, or only from administrator users. This is done by selecting the permission to be removed from the Permission drop-down list, then selecting the user role to which the revocation will apply from the User role drop-down list and then clicking on the Revoke and Save Changes buttons.
  • The Organisational permissions tab is analogous to the Personal one, where instead of individual users we have organisations and the rights granted to each one.
  • Finally, the Public permissions tab can be seen in Figure 9 and contains a drop-down list with all available permissions for the current dataset. The provider can click those they want to grant on a public access level and then click on Save Changes.

• Content
  This tab (Figure 10) contains metadata coming from the Semantic Interoperability component that describe the current dataset’s data, e.g. the relevant data model that the data adhere to, the attributes they contain etc.

The next four tabs contain logging data pertaining to DG metadata updates, datasource metadata updates, access requests and access revocations.

• Update History

• Data Source History

• Access Requests History

• Revoked Access History

External datasets

The External Datasets view contains three tabs, Personal, Organizational and Public, each showing external datasets that the user has access to due to personal, organisational or public permissions. These are shown in Figure 15, Figure 16, Figure 17.

The dataset table in all the above views is identical and contains certain basic information, like the dataset, owner and provider names, whether the datasource ID is missing etc. Clicking on a table row displays the dataset’s details (Figure 18). We can see that this view contains all tabs available under the internal dataset view (Figure 7), except Permissions, since the logged in user is a consumer of the dataset and, thus, cannot change dataset permissions. Similarly, the Edit button is absent from the Details tab.

Organisational datasets

This is an administrator-only view that contains a table of organisational datasets pertinent to the logged-in administrator (Figure 19). It is worth remembering that a dataset is considered to be organisational to a user, if that user’s organisation owns the dataset.

Clicking on a dataset in the list presents the administrator with a view of the dataset details. Whenever an administrator opens the Organisational Datasets list, they are seeing datasets that have either

• been added by them (the administrator is also the provider user)
• been added by other members of their organisation, or
• been added by users of other organisations that are providers for the dataset

The amount and type of information shown about the dataset depends on the following:

• if the administrator clicking on a dataset is also the provider of that dataset, the dataset view shown must be the same as that shown through the Internal Datasets list
• if the administrator clicking on a dataset belongs to the organisation owning but not providing that dataset, he will be able to see four tabs (Details, Content, Update History, Data Source History), but not edit the dataset details. We call this the “owner`s view” of the dataset (Figure 20)
• if the administrator clicking on a dataset belongs to the provider organisation, but is not the provider user, he will be able to see the owner`s view of the dataset

Users

This is an administrator-only menu item showing two tabs (Active Users, Inactive Users), the first showing a table of active users belonging to the administrator’s organisation and two buttons: Add User and Deactivate Selected (Figure 21). The second tab shows the inactive users and an Activate Selected button.

Adding a user

Clicking on Add User brings up a form for the administrator to fill in, shown in Figure 22. The administrator has to enter the new user’s role (administrator or simple user), the first and last names, the username and the user’s email address. Once filled in, the administrator clicks on Register to save the new user. Upon creation, the system returns an initial safe password for the new user, shown in an alert popup. The administrator has to copy that password and send it in a secure manner to the person using the new account.

Deactivating and activating a user

An administrator can opt to deactivate an existing simple user (not another administrator), if it is deemed necessary due to security or other reasons. To do that they have to go to the Active Users tab, click the checkbox at the beginning of the desired user’s row and then click on Deactivate Selected. The system then deactivates the selected user, which means that logging in with that particular user is now unauthorised. However, all user details are still kept in Data Governance. The deactivated user is shown in the table of the Inactive Users tab.

The administrator can later decide to reinstate the deactivated user. To do that they must go to the Inactive Users tab, click the checkbox at the beginning of the desired user’s row and then click on the Activate Selected button. This removes the user from the inactive users table and places him once again in the active users table. Login is once again possible.

Notifications

The Notifications menu item presents a list of notifications the user has received due to the actions of other users, most notably access requests for one of the user’s internal datasets. This can be seen in Figure 23.

Clicking on a notification brings up the notification details, which can be seen in Figure 24.

The details show which user from which organisation asked for what permissions on which dataset and when. It also contains three buttons. The Cancel button takes the user back to the notifications list. The Accept and Reject buttons do exactly what they say, plus they remove the notification from the notifications list.

External organisations

Each port (ThPA and VPF) has a special account on the EXT system organisation. These accounts are:

• adminThPAext for ThPA
• adminVPFext for VPF

These accounts have access to a special dashboard, which enables them to create external organisations. This is shown in Figure 25. Apart from Profile and Notifications (which are standard items), there is only a single item on the left-hand-side menu: External Organisations. This presents a table containing all external organisations created in Data Governance by the particular port.

Clicking on an external organisation in the table of Figure 25 opens up the external organisation’s details view, shown in Figure 26. This view contains three tabs:

• Profile: this tab contains the organisation’s information that was entered when the organisation was created (Figure 27), e.g. name, address, VAT number etc.
• Organisation Active Users: this view shows a list of active users for this external organisation and is identical to the one in Figure 21. As with the Users menu (Section 4.5), there is an option to deactivate users.
• Organisation Inactive Users: this view shows a list of inactive users for this external organisation and is identical to the Inactive Users tab in the Users menu (Section 4.5). There is an option to reactivate an inactive user.

Adding an external organisation

In Figure 25 we can see a button in the upper right corner labelled Add External Organisation. Clicking it presents the form shown in Figure 27. The port admin just needs to fill in all pertinent fields (mandatory fields marked with an asterisk) and click on Register. Once the organisation is created, an alert pops up containing the password for the new external organisation admin’s password. This needs to be noted down and sent to the appropriate recipient through a safe channel. Once this is done, the port admin can close the alert pop-up and is then taken back to the External Organisations view, where the new organisation is now visible.

Deleting an external organisation

Again in Figure 25 we can see a second button below the Add External Organisation, called Delete Selected. Clicking on it, after having selected an organisation from the table (by clicking the appropriate checkbox in the first column), deletes an external organisation. Multiple organisations can be deleted at once.