Identifiers used in the Data Exchange Layer

This article describes the identifiers used in the Suomi.fi Data Exchange Layer.

In version 6 of X-Road, each organisation that has connected to the Data Exchange Layer, and the subsystem and service it has connected to the Data Exchange Layer, are given a globally unique identifier. The purpose of this identifier is to support the X-Road federation feature, which allows multiple X-Road instances to be joined together.

X-Road’s internal exchange of messages and management of access rights are based on the unique identifiers of organisations, subsystems and services within a single X-Road instance and an entity composed of multiple instances.

Structure of identifiers

Organisation-specific identifiers consist of three, subsystem-specific identifiers of four and service-specific identifiers of six separate sections. The identifiers are hierarchical. Subsystem identifiers always contain the identifier of the organisation that owns them. Similarly, service identifiers always contain both subsystem and organisation identifiers.

Organisation identifiers (member)

In version 6 of X-Road, the identifiers of organisations that have connected to the Data Exchange Layer are composed of three parts as follows:

Organisation: [X-Road instance]/[member class]/[member code]

• X-Road instance = unique identifier of the X-Road instance. The identifier must consist of an ISO country code and an annex identifying the technical environment in the Data Exchange Layer (FI-DEV, FI-TEST, FI). The Data Exchange Layer operator sets the environment identifier when the Central Server is installed.
• Member class = unique identifier that identifies the type of organisation within a single instance. In the testing, production and development environments of the Data Exchange Layer, organisations are classified as follows:

GOV: Government institutions

COM: Commercial operators

MUN: Municipalities

EDU: Education and training sector

ORG: Non-profit organisations such as associations and foundations (only in testing and production environments)

PRI: Private individuals (only in the development environment)

• Member code = an identifier specifying an organisation. The identifier must be unique at least within the type of organisation selected. However, for the sake of clarity, it is better that the identifiers used are unique at the level of the entire instance. A business ID is used as the unique identifier of an organisation.
• Member code = an identifier specifying an organisation. The identifier must be unique at least within the type of organisation selected. However, for the sake of clarity, it is better that the identifiers used are unique at the level of the entire instance. A business ID is used as the unique identifier of an organisation.

Specifications to the member code

Organisations can connect to all Data Exchange Layer environments. In the case of organisations, their business ID is recorded as a Member code without the FI prefix, i.e., 0920632-0. If the organisation to be connected does not have a business ID, the Data Exchange Layer administration assigns the organisation an identifier to use as a Member code.

Private individuals can only connect to the Data Exchange Layer development environment. To connect to the development environment as a private individual, first contact the Data Exchange Layer support at palveluvayla@palveluvayla.fi. The service administrators provide you with the required connection information (member name and member code). In the case of private individuals, the Member code is a sequence numbering 0000001-0, 0000002-0, etc., instead of a business ID.

We do not recommend that you use your own name for a security server or subsystems, for example. You should use an invented name and discuss naming with Data Exchange Layer support.

For example, the identifier below identifies a private company belonging to the FI-DEV instance, i.e., the development environment, whose business ID is 12345:

Organisation: FI-DEV/COM/12345

Subsystem identifiers (subsystem)

A subsystem (consumer) that uses data through the Data Exchange Layer must always have a subsystem-level identifier.

A subsystem refers to an individual information system or logical service/system entity connected by an organisation to X-Road. A subsystem identifier consists of the identifier of the organisation that owns it (subsystem owner) and a unique subsystem identifier at the organisation level (subsystem code).

The identifiers (subsystem code) assigned to subsystems are at the discretion of the organisations themselves. However, the CamelCase naming convention is recommended for subsystems. In practice, this means that subsystem names consisting of multiple words are written without spaces, separating words with a capitalised letter (e.g., TestSystem).

Subsystem: [subsystem owner]/[subsystem code]

For example, the identifier below identifies a subsystem called HighSecurity that belongs to the organisation FI-DEV/COM/12345 shown in the previous example.

Subsystem: FI-DEV/COM/12345/HighSecurity

Service identifiers (service)

A service that provides data through the Data Exchange Layer must always have a service-level identifier that contains a subsystem.

A service refers to a single SOAP service that has been published to the Data Exchange Layer through a subsystem. The service identifier consists of the identifier of the subsystem that published it, the unique identifier of the service and the version number of the service.

The version number is used to distinguish between different versions of the service. Its use is mandatory. The service identifier must be unique at the level of the subsystem that published it. The publisher can decide on the service identifier and define it in the WSDL descriptions containing the interface descriptions of the connected services. The version number consists of the letter ‘v’ and an integer indicating the version number.

Service: [service provider]/[service code]/[version]

For example, the identifier below identifies version v1 of the getSecureData service that belongs to the subsystem FI-DEV/COM/12345/HighSecurity shown in the previous example.

Service: FI-DEV/COM/12345/HighSecurity/getSecureData/v1

Use of identifiers

All data-providing services (provider) and data-utilising systems (consumer) connected to the Data Exchange Layer must be connected to the Data Exchange Layer through subsystems. Although it is technically possible to connect services directly under organisations or call services as an organisation, the use of subsystems allows for a more sophisticated definition of access rights. In addition, the use of subsystems ensures the most uniform structure of identifiers in the systems and services connected to the Data Exchange Layer.

A system using data through the Data Exchange Layer must always have a subsystem-level identifier, and a service providing data must have a service-level identifier that contains a subsystem. However, a member-level identifier is sufficient for an organisation marked as the owner of the security server if the organisation does not provide data to the Data Exchange Layer and does not use any data within. When connecting to the Data Exchange Layer, all organisations will first receive a member-level identifier, after which it will be possible to add new subsystems and services and create the identifiers required by them.

For more information about using identifiers, read the article X-Road communication protocol.