Why describe data services?

The purpose of describing the data services is to explain the nature and purpose of the data services offered on X-tee in a better and more human-friendly way.

A well-described data service can:

  • cause other X-tee members to be more interested in your data services;
  • make it easier for other members to use your data services;
  • reduce the number of questions addressed to you and thereby reduce your administrative burden;
  • improve the user experience of using your data service;

RIA's goal with the X-tee self-service environment service catalogue is to give data service providers the opportunity to manage their own X-tee data service documentation in one environment and to support their deployment.

Prerequisites

The data services offered by the institution connected to X-tee can be described by a user who fulfils the following criteria:

  • The user has logged in to the X-tee self-service environment
  • The user has the right of representation of the institution providing the data service or has been assigned the role of either a representative or a security server administrator based on authorization.

You can check your connection with the institution in the "My organizations" view. If you have a valid right of representation or authorization, your institution or institutions are highlighted in this view.

If you find that the "My organizations" view is empty or some authorities are missing, please refer to the instructions for adding authorization.

Description of data services

In the left menu bar of the X-tee self-service environment, a red number is marked next to "My services" if the user's related data service has unfilled mandatory fields.

By opening the "My services" view, you can get an overview of the data services connected to you. If the mandatory fields are not filled in for the data service, the explanatory text is displayed in red under the service code of this data service. You can start describing the desired data service by clicking on the service code link:

Clicking on the service code link opens a detailed view of this data service. You can start describing the data service via the "Edit" button in the detail view.

As a result, the description view opens:

The description can only be saved if the mandatory fields are filled:

  • Service name - short name of the data service
  • Service description - semantic description of the data service. When describing, we recommend to be based on the questions that the user of the data service may have:
    • What does this data service do or enable?
    • Who should use it?
    • What data is taken as input and what is output as response?
  • Documents (optional) - You can also add documents to the service description, which can, for example, describe the data service more technically or contain the conditions for using the data service.

NB! Certain restrictions apply when adding a document:

  • Allowed file extensions: .doc, .pdf, .txt, .docx, .xls, .xlsx, .csv, .log, .rtf, .odt
  • Maximum file size allowed: 5MB
  • When the file is loaded, a virus check is performed on the file, which may take up to 5 seconds.

Examples - as examples, you can view the descriptions of the following data services provided by RIA: