Annotation (In English)
The X-Road pattern catalogue contains X-Road service design and usage
patterns. The patterns, their categories, short descriptions (chapter "Patterns overview") and a guide for choosing a suitable pattern (chapter "Finding a suitable pattern") are given on the current page.
The description of each pattern contains an English annotation, which briefly describes the aim and the main idea of the pattern. The main parts of pattern descriptions are in Estonian however at least the WSDL examples (and possibly UML diagrams) should be useful to a non-Estonian reader.
The patterns are divided into three main categories:
- Primitives - Basic building blocks for X-Road services.
Primitives offer very generic functions that can be applied to provide basic data exchange between information systems. Primitives can be combined and extended to create more complex communications mechanisms.
- Functional patterns - Solutions that are based on primitives and
offer some additional functionality.
Functional patterns focus on solving data exchange problems that can't be solved by using a single primitive. Functional patterns are created by extending a primitive, combining multiple primitives or by combination of the two.
- Compositional patterns - Consuming and processing of X-Road
Compositional patterns are divided into two groups:
- service consumption patterns (pattern code KM) show how X-Road services are commonly consumed on X-Road;
- service processing patterns (pattern code TM) show how the messages exchanged on X-Road can be processed.
Figure 1.1 Pattern names and how patterns are divided into groups.
This chapter gives an overview of the patterns contained in this catalogue. For each pattern the main purpose and some main characteristics are given. If a pattern seems interesting then it is recommended to take a look at the full description of that pattern.
- PM1: Data pull service – describes querying data over X-Road. A single service will be developed where the service
input contains the query parameters and output contains the query result. The service will be developed in the information system that contains the data to be queried.
- PM2: Data push service – describes sending data over X-Road. A single service will be developed where the service input contains the data to be sent and the output contains conformation of receiving the sent data. The output may also contain business information. The service will be developed in the information system that will receive the data.
- PM3: Protocol tunnelling – describes creating a service when it is not desired to define the input
and/or output of a service fully in WSDL. For example in cases when the same service is used for supporting different business processes or when the data structures are too complex to be described in WSDL.
The solution is to use a special element that can contain data in a freely chosen format.
- FM1: Universal data pull service – describes querying data over X-Road when the service consumer needs to be able to choose which data fields to query. For example if one information system needs person's name and nationality while another information system needs person's name and place of residence, then this pattern allows to solve both needs via the same service. The main idea is to define an additional array of data field names in the service input which will be used to determine which fields to query.
- FM2: Summary list and details – describes querying data over X-Road when the service consumer needs
detailed information of a specific record, but does not know exactly which
record that is. The main idea is to perform the query in two parts via two services. The first service is used to query general information about all records and the second service is used to query detailed information of a specific record. This pattern is mostly used in human guided processes.
- FM3: CRUD operations – describes managing data over X-Road. It is an example of how the basic functions of persistent storage (create, read, update, delete) can be performed over X-Road services. One service will be developed for each operation. This pattern is suitable in situations where one information system needs to be able to manage the data stored on another information system (for example managing user accounts).
- FM4: Long running task – describes a way to use long running tasks via X-Road. The details of the task itself do not matter, except that the task must have some input and it must produce some output. For example the task can be a complex database query, a scientific calculation or a task that requires human interaction to be completed. The main idea of this pattern is to separate the process input and output into separate services so that one service is used for the task input and second service is used for the task output.
- FM5: Data synchronization – describes a data structure that is suitable for synchronisation messages. More specifically when an information system needs to send information about changes in its dataset to another information system. The pattern proposes using a set of three arrays (new records, updated records, deleted records).
- FM6: Authentication – describes an authentication mechanism created using X-Road. It is used when one information system wishes to authenticate its users via an authentication mechanism of another system. The authentication itself is performed by the other information system and X-Road is used to exchange information that supports the process.
- FM7: Data exchange trough central node – describes exchanging data over X-Road in cases when the availability of both information systems is so low that it is difficult to find a suitable time when both systems are available. The pattern proposes
adding a central node between the information systems. The central node
acts as a high availability mail-box between the information systems. Both information systems will be able to send data to and read data from the central node.
- FM8: Data usage pull service – describes a service that used when a person
must be able to query an information system to find out when and why his/hers
data has been used. The service description is based on the reusable component "Andmejälgija" (https://github.com/e-gov/AJ/blob/master/README.md).
- KM1: Sequential service execution – describes executing X-Road services sequentially. It is a widely used and a simple pattern. It is needed in situations where the output of one service is needed for the input of the next service.
- KM2: Alternative service execution – describes the case when it is not known in advance if some services need to be executed. It is characterized by multiple service execution paths
that would be executed under certain conditions.
- KM3: Nested service call – describes the case when creating a response message for one service requires using another service. Or in other words consuming an X-road service is part of the implementation of another service.
- KM4: Parallel service execution – describes executing multiple X-Road services in parallel. This means that the service calls are made at practically the same time and the response messages will be received independently from each other. It is used in situations where the output of one service is not needed for the input of another service.
- KM5: Data prefetching – describes the case when services are executed before the service responses are actually needed. Both sequential and parallel service execution patterns can be combined with data prefetching.
- KM6: Loop service execution – describes the case when one or more services are used sequentially during the same workflow. For example when multiple documents are signed by the user sequentially.
- KM6.1: Self-loop – describes a special case of loop service execution. More specifically a case when some service is known to be unstable (a proper response message is often not sent). A possible solution is to retry service execution multiple times until a proper response is received. A reasonable maximum should be set for the number of retries.
- TM1: Content splitter – describes a general approach to dividing a bigger dataset into smaller independent parts. Usually the aim is that each part could be processed separately (for example sent to different information systems via different services).
- TM2: Content aggregator – describes a general approach to combining multiple smaller datasets into a bigger complete dataset. Usually the aim is to normalize the data (using common classifications and units) and to allow the dataset to be processed as an integral whole.
- TM3: Header-based routing – describes an approach for re-routing messages internally based on the data contained in the message header. It is useful when the same service is used to support multiple different business processes (PM3: Protocol tunnelling).
Finding a suitable pattern
The purpose of this section is to help the reader understand different roles that exist in the context of X-Road patterns, determining ones role and finding a suitable pattern for the task at hand.
- Determining ones role is described in the chapter "Roles". The chapter gives descriptions of the roles and the main considerations associated with each role. These are summarised in a decision tree (figure 1.2).
- The chapter "Patterns" focuses on finding a suitable pattern for the task at hand. The chapter begins with listing the patterns along with their short descriptions. The chapter also contains descriptions of the main considerations to keep in mind when finding a suitable pattern. These are summarised in a decision tree (figure 1.3).
- The pattern catalogue is intended to be added to over time. Therefore it is possible that a suitable pattern is not yet added to the catalogue. In that case the existing patterns may be modified as needed.
- If multiple services are consumed during the same workflow, then the chapter "Compositional patterns" may be helpful. It lists the patters associated to service consumption and gives a short summary for each of them.
One of the main purposes of X-Road is to enable different information systems to exchange data with each other. This is achieved through creating services based on the patterns described in this catalogue.
Each data exchange is always between two parties and thus we can distinguish two roles:
- service consumer – consumes services created by the service producer, initiates the data exchange and develops the business logic needed to consume the service and process the service response.
- service producer – creates the service, develops the business logic needed to produce the service and controls which systems have access to the service.
The main considerations when determining ones role come from the service oriented nature of X-Road.
- Is a suitable service already created?
- At the time of writing there are over 1500 different services available on X-Road. Therefore it is likely that a suitable service has already been created and a new service is not needed.
- Existence of a service can be checked trough RIHA or from the other party.
- Corresponding question in the decision tree "Service exists?".
- How high is the availability of the related information systems?
- When creating a new service it is important to keep in mind the availability of information systems that need to exchange data.
- The service producer must be always available when someone might want to consume the service.
- The service consumer must be available only when consuming the service.
- Corresponding question in the decision tree "IS availability?".
- Which party wishes to have control over when data is exchanged?
- If the availability of both information systems is high enough then the roles should be determined based on which party wishes to initiate the data exchange. The following should be considered:
- the service consumer has control over when data is exchanged;
- the service producer has control over who can exchange data;
- the service producer can send feedback to the service consumer via the service response message.
- Corresponding question in the decision tree "Initiator?".
Figure 1.2 Decision tree for determining ones role.
PatternsThis chapter focuses only on the primitives and functional patterns. Compositional patterns are briefly covered in the chapter "Compositional patterns"
Primitives and functional patterns are the following:
- PM1: Data pull service – if the service is created to allow the consumer to query data (important data is in the response message);
- PM2: Data push service – if the service is created to allow the consumer to send data (important data is in the request message);
- PM3: Protocol tunnelling – if the same service is used for different datasets of the dataset structure is difficult to describe in WSDL;
- FM1: Universal data pull service – if the service is consumed by different parties that need differentiated datasets;
- FM2: Summary list and details – if the dataset is large and the business process is led by a human user;
- FM3: CRUD operations – if the data needs to be managed over X-Road;
- FM4: Long running task – if creating the service response message takes a long time;
- FM5: Data synchronization – if the data needs to correspond for both parties;
- FM6: Authentication – if X-Road is used to provide an authentication mechanism to another information system;
- not included in the decision tree, because this pattern is suitable for one specific task;
- FM7: Data exchange trough central node – if the availability of both information systems is low;
- FM8: Data usage pull service – if data usage information needs to be queried;
- not included in the decision tree, because this pattern is suitable for one specific task;
- How complicated is the structure of the data that is changed?
- The service input and output structures are usually described in the service WSDL. However in some cases it may turn out to be unreasonably complicated to do (for example HL7 documents).
- Another case is when a single service is used for vastly different datasets. For example if X-Road is used only as a transport layer for some other protocol.
- Corresponding question in the decision tree "Complicated dataset?".
- Which information system contains important data?
- By important data we mean data that is created in one information system and needed by the other information system.
- Corresponding question in the decision tree "Data source?".
- Is data updated periodically?
- By periodic updates we mean the situation in which one information system is required to send changes in its data to another information system periodically (for example at the end of every workday).
- Corresponding question in the decision tree "Periodic updates?".
- Does data need to be managed over X-Road?
- Here we mean the situation in which one information system must be able to modify data on the other information system on the fly.
- Corresponding question in the decision tree "Data management?".
- Does the creation of a service response take a long time?
- It is possible to provide access to long running tasks over X-Road. However to enable this two services will need to be used. One for the input of the process and one for the output.
- Corresponding question in the decision tree "Long processing time?".
- Does the service consumer need to have control over which data fields appear in the response message?
- The service input and output are usually clearly defined in the service WSDL. However in some cases it is needed that the service consumer is able to choose which data fields will be included in the response message.
- Corresponding question in the decision tree "Dataset differentiation?".
- Is it needed to find specific records among a large number of records?
- If the X-Road is used in a human led process, then there may be a need to provide an overview of records to the user, from which the user can choose interesting records to further examine.
- Corresponding question in the decision tree "Data search?".
Figure 1.3 Decision tree for finding a suitable pattern.
If multiple services are consumed during the same workflow, then it is useful to go over the compositional patterns. Compositional patterns are divided into two groups:
- Service consumption (pattern code KM) – consumption (invocation) of X-Road services:
- KM1: Sequential service execution – if multiple services are consumed and input of one service depends on the output of the previous service;
- KM2: Alternative service execution – if multiple services are consumed and consumption of some services is optional;
- KM3: Nested service call – if the service producer needs to consume another service before creating the response message;
- KM4: Parallel service execution – if multiple services are consumed and services are independent from each other;
- KM5: Data prefetching – if services are consumed before they are actually needed by the business process;
- KM6: Loop service execution – if the same services are consumed multiple times during the same workflow;
- KM6.1: Self-loop – if the same service is used multiple times in a row;
- Message processing (pattern code TM) – processing of X-road messages:
- TM1: Content splitter – if the response message needs to be divided into smaller datasets that can be processed independently;
- TM2: Content aggregator – if response messages of multiple service invocations need to be merged into a single dataset that can be processed as a whole:
- TM3: Header-based routing – if messages received over X-Road need to be rerouted in the information system based on data in the message.