Go directly to contents.
Suomi.fi Data Exchange Layer

Implementing a service provided through the Suomi.fi Data Exchange Layer

This instruction describes how you can implement a service that is available in the Suomi.fi Data Exchange Layer and described in the API Catalogue. Remember that you must always agree separately on the implementation of a service with its service provider.

Prerequisites:

Your organisation must be connected to the Data Exchange Layer and have a functioning subsystem before you can apply for a user permit to a particular service. Therefore, make sure that at least one subsystem is added to your security server. Instructions for adding a subsystem can be found in a separate support article. You can also check the existence of your subsystem in the API CatalogueOpens in a new window. under your own organisation.

The API CatalogueOpens in a new window. describes the subsystems that have been connected to the Data Exchange Layer. For an instruction of how to find services in the API Catalogue, see the support article Searching for services in the API Catalogue.

To implement a service that is available in the API Catalogue, follow these steps:

  1. Connect your organisation to the Suomi.fi Data Exchange Layer
  2. Familiarise yourself with the terms and conditions and technical specifications of the service
  3. Apply for a user permit to use the service
  4. Connect your organisation's and the service provider’s information systems

1. Connect your organisation to the Suomi.fi Data Exchange Layer

If your organisation intends to utilise the services offered through the Data Exchange Layer, it must join the Data Exchange Layer’s production environment.  For step-by-step instructions on how to join the Data Exchange Layer, see the Using the Data Exchange Layer page. The connection process takes between 1–3 months.

The connection process includes:

  1. Planning the connection process and your service maintenance policies
  2. Deploying a security server solution and applying for an access license
  3. Joining the test environment
  4. Performance testing in the test environment
  5. Transitioning to the production environment

We recommend testing the compatibility of your subsystems with your service provider when joining the test environment. This will help ensure that the messages between your organisation and your service provider’s service are transmitted without any issues. For more information, read the instructions below.

2. Familiarise yourself with the terms and conditions and technical specifications of the service

The organisation providing a service will describe said service in its subsystem description. See for example the Digital and Population Data Services Agency’s description of its VTJ interfaceOpens in a new window..

If the subsystem description is missing some of the information you need, contact the service provider and ask for the additional details.

Check whether you will be able to implement the service

First, check with the service provider to ensure that your organisation meets the following requirements for implementing the service:

  • terms and conditions
  • technical specifications.

Terms and conditions of use

The implementation and use of services may be subject to restrictions, licence applications and fees. For service-specific terms and conditions, see the description of the subsystem in the API Catalogue.

Technical specifications

More detailed interface-related information on the service can be found in the subsystem’s attachments. If the service is SOAP-based, the information on the service is presented in a WSDL file. In services based on the REST model, the file is usually in the JSON format. Service providers may also add other technical documents related to the service, such as PDF files, to the Attachments section.

The API Catalogue contains descriptions of services that are based on both the SOAP (Simple Object Access Protocol) and REST (Representational State Transfer) model. Whether a service is SOAP or REST-based will influence the technical solutions necessary for the implementation of the service. For example, a so-called adapter service is not needed with REST interfaces. REST is generally a more lightweight solution than SOAP, as it is more lightly standardised.

3. Apply for a user permit to use the service

The use of the services may require applying for a user permit. Depending on the service to be implemented, a user permit can be applied for either in the API Catalogue or by contacting the service provider.

Apply for a user permit in the API Catalogue

In the API Catalogue, you can apply for a permission to use the subsystem and services, if the service provider has made the function available. You can also apply for a user permit as an intermediary on behalf of another organisation.

When the service provider has implemented the function, a separate section Request permission to use this subsystem appears on the subsystem page for logged-in users in the API Catalogue. You can find more information about applying for a user permit in the API Catalogue in a separate support article.

Contact the service provider

Once you have found a service in the API Catalogue that you would like to implement, contact the organisation that provides the service.

The service provider’s contact information is included in the subsystem information available in the API Catalogue. If no contact information is available, ask for help from API Catalogue maintenance: palveluvayla@palveluvayla.fiOpens in a new window..

4. Connect your organisation's and the service provider’s information systems

Your organisation’s information system is connected to the Data Exchange Layer via a security server and subsystem

Please note that before you begin connecting the information systems used by the service user (you) and the service provider, your information system must already be connected to the Data Exchange Layer.

The information system that will receive data from other Data Exchange Layer services is connected to the Data Exchange Layer via a security server. The subsystem, on the other hand, acts as the interface between the security server and information system. In other words, the retrieval of information from one information system connected to the Data Exchange Layer to your information system takes place between the organisations' subsystems.

In practice, the deployment of a security server and the addition of a subsystem are part of the Data Exchange Layer connection process.

For more instructions on deploying a security server and adding a subsystem, see:

First, test the connection between your information systems in the test environment

Before you connect your information systems in the Data Exchange Layer’s production environment, you must test the connection in the test environment. Agree on the testing process with the organisation providing the service.

Record the errors detected during testing and correct them before entering the production environment. When everything is functioning smoothly in the test environment, you can begin connecting your information systems in the production environment.

For more information on the test environment and testing process, see:

Issues to consider when connecting information systems

When you begin connecting your information systems, your service provider will need at least the following:

  • your subsystem’s identifying information for configuring the related service permissions (subsystem name = X-Road subsystem code)
  • your security server’s IP address for the necessary port openings (5500 and 5577).

Your organisation must also be provided with the IP address of the service provider’s security server, so that you can perform the same port openings.

In addition, check that the following connection status indicators in the Diagnostics menu of the security server's management interface are green (functional):

  • Global Conf
  • TSA timestamping
  • OCSP (G3).
Updated: 9/10/2024

Are you satisfied with the content on this page?