Difference between revisions of "Getting started guide"

Latest revision as of 17:32, 7 March 2023

[[Media:File.ogg]]This guide provides a list of steps to be taken by each partner wishing to deploy and join the DE4A infrastructure of iteration 2. There are four main activities: getting eDelivery certificates, setting up an SMP for DE4A, setting up a DE4A Connector and the development and integration of the final participant. There is an additional chapter for those participants who wish to use and integrate with the DE4A Playground.

1. Getting eDelivery certificates

The DE4A network makes use of the eDelivery components and infrastructure to support the exchange of evidence and messages. There are two eDelivery components that must be deployed and operated by participants in the DE4A network: an SMP and an AS4 Gateway (also know as Access Point). Both must be configured to use a certificate that conforms to the DE4A PKI, following the Trust Management Model established for the DE4A project. DE4A uses a PKI provided by CommisSign-2, which is the Certificate Authority of the European Commission for eDelivery. Getting the eDelivery certificates is necessary to finish the set up of the SMP and DE4A Connector.

In order to obtain the corresponding certificates, a new partner would need to get in contact with the coordination team of DE4A, who can initiate the process to request new certificates. This process is designed by the Certificate Authority.

2. Setting up an SMP for DE4A

Within the DE4A network, at least one eDelivery SMP must be deployed per participating country. There can be more than one SMP per country, although only one is needed. Therefore, multiple participants from the same country can use the same SMP provided by the corresponding national entity.

The SMP must be installed, configured and populated with the right information. To install and configure the SMP, the following two documents are of help:

Once the SMP is set up, the operating entity must populate it with the appropriate information of participants and evidence types that the relevant national DE4A participants are going to request and provide. Each SMP must only store and manage the information related to the participants of the same country as where the SMP is located, so that each country is only responsible for its own information.

Governance procedure

When populating/updating the information in the SMP, the Useful information on pilots and participants Wiki page should also be updated to stay aligned. After that, both ATOS (Ana María Piñuela, Alberto Crespo, Javier Presa) / WP5 (Javier Ferrero, Javier Baena, Eduardo Moreno, Hugo Berdón) should also be informed about these changes.

TIP

What information needs to be added?

Create a service group with your participantID:

Scheme: iso6523-actorid-upis
Identifier value: 99XX:pt000000026-test-it2

For that participant (service group) you need to create an endpoint.

Endpoints will have the Document type ID for the Canonical Evidence Type.

If you are a DE, then you need to register a response endpoint with the Connector URL endpoint and the certificate.

If you are a DO, then you need to register a request endpoint with the Connector URL endpoint and the certificate.

The URL for the Connector must be the base URL, followed by “/phase4"

For this example, the endpoint URL should be: https://de4a.simplegob.com/de4a-it2-connector/phase4

3. Setting up a DE4A Connector

The DE4A Connector is needed to be able to exchange messages with other participants, since the communication is realised via these Connectors.The latest release version of the DE4A Connector is available at the GitHub of WP5. To install the DE4A Connector, an Installation and configuration guide of the DE4A Connector it2 is available.

4. Development and integration of the final participant

In DE4A, there are two types of the so-called "final participants": Data Evaluators and Data Owners. These are the entities that request or provide evidence, repectively. Each DE4A participant must develop its own final participant and integrate it with the other components.

In order to understand the common specifications each partner needs to follow to properly exchange messages with the rest of the DE4A components, the following resources are available within the Common specifications section of the WP5 part of the DE4A Wiki:

Common behaviour and interactions between components
- Description of the interaction patterns of the second iteration through communication diagrams. Data structures used during exchanges are also described there.
Central IAL interface
- Description of the software interface of the Central IAL.
Summary of software interfaces
- Reference information on the software interfaces of the DE4A components.
DE4A Logs and error messages
- Updated version for the second iteration of the specification of the common error and logs messages used during exchanges.

Once the Data Evaluator or Data Owner has been developed and deployed, it must be integrated with the DE4A Connector and SMP that will be supporting the communication of that final participant:

The de-do.json must properly updated to include the endpoint of the new final participant.
The SMP must also be updated with the participant ID and the evidence that the final participant will request (DE) or provide (DO).

5. Integration with the Playground it2

The Playground can only be used in two ways:

By exchanging messages between the DemoUI and the Mocked DO as the participants involved.
By using the infrastructure of a partner to act as a Data Consumer or Data Provider.

For the second option, it is mandatory to set up a complete interaction side: either the sender (DC) or the recipient (DP). This means that, in this second iteration, the use of only a DE or a DO to exchange messages via the Playground is not supported.

For example, if a partner wants to send a message from its DE to the Mocked DO, that partner needs to set up the complete infrastructure of a Data Consumer:

A national SMP available to that partner.
A DE4A Connector.
A Data Evaluator.

On the other hand, if a partner wants to receive a message in its DO from the DemoUI, that partner needs to set up the complete infrastructure of a Data Provider:

A national SMP available to that partner.
A DE4A Connector.
A Data Owner.

The Shared SMP cannot be used for participants other than the imaginary ones.

URL addresses for the Playground environment

The Playground environment has a cross border infrastructure. Data consumer side is deployed at the University of Maribor in Slovenia where the DemoUI is acting as Data Evaluator and the Connector as Data Requestor.

DemoUI DE - https://de4a-demoui-dev.informatika.uni-mb.si/
Connector DR - https://de4a-connector-dev.informatika.uni-mb.si/

The Data Provider side is deployed at SGAD in Spain where the Connector is a Data Transferor and the Data Owner is the Mocked DO.

Connector DT - https://pre-as4gw-dt-de4a.redsara.es/de4a-it2-connector/
Mocked DO - https://pre-smp-dr-de4a.redsara.es/de4a-mock-connector/

A Kafka tracker is available through the following URL: https://de4a.simplegob.com/package-tracker/#!detail

For detailed traceability, these are the topics where each component is logging to Kafka.

KAFKA
Component	Topic
DemoUI	wp5-demoui-it2
Connector DR	log-test
Connector DT	de4a
Mocked DO	test

@@ Line 1: / Line 1: @@
-This guide provides a list of steps to be taken by each partner wishing to deploy and join the DE4A infrastructure of iteration 2. There are three main milestones: SMP, DE4A Connector and DE/DO. Each milestone must be properly completed before moving on to the next one. This is due to the way the Playground will be used in the second iteration.
+<nowiki>[[Media:File.ogg]]</nowiki>This guide provides a list of steps to be taken by each partner wishing to deploy and join the DE4A infrastructure of iteration 2. There are four main activities: getting eDelivery certificates, setting up an SMP for DE4A, setting up a DE4A Connector and the development and integration of the final participant. There is an additional chapter for those participants who wish to use and integrate with the DE4A Playground.
-Usage of the Playground it2
+== 1. Getting eDelivery certificates ==
+The DE4A network makes use of the eDelivery components and infrastructure to support the exchange of evidence and messages. There are two [[eDelivery]] components that must be deployed and operated by participants in the DE4A network: an SMP and an AS4 Gateway (also know as Access Point). Both must be configured to use a certificate that conforms to the DE4A PKI, following the Trust Management Model established for the DE4A project. DE4A uses a PKI provided by '''CommisSign-2''', which is the Certificate Authority of the European Commission for eDelivery. Getting the eDelivery certificates is necessary to finish the set up of the SMP and DE4A Connector.
-The Playground can only be used in two ways:
+In order to obtain the corresponding certificates, a new partner would need to get in contact with the coordination team of DE4A, who can initiate the process to request new certificates. This process is designed by the Certificate Authority.
+== 2. Setting up an SMP for DE4A ==
-* By exchanging messages between the DemoUI and the Mocked DO.
+Within the DE4A network, at least one eDelivery SMP must be deployed per participating country. There can be more than one SMP per country, although only one is needed. Therefore, multiple participants from the same country can use the same SMP provided by the corresponding national entity.
-* By using the infrastructure of a partner as a Data Consumer or Data Provider.
-For the second option, it is mandatory to set up a complete interaction side: either the sender (DC) or the recipient (DP). This means that, in this second iteration, the use of only a DE or a DO to exchange messages via the Playground is not supported.
-For example, if a partner wants to send a message from its DE to the Mocked DO, that partner needs to set up the complete infrastructure of a Data Consumer:
+The SMP must be installed, configured and populated with the right information. To install and configure the SMP, the following two documents are of help:
+* [[Media:Setting up a Service Metadata Publisher for DE4A.pdf|2022-04-01 Setting up a Service Metadata Publisher for DE4A]]
+* [[Media:Configuring the SMP for the IAL.pdf|2022-05-02 Configuring the SMP for the IAL]]
+Once the SMP is set up, the operating entity must populate it with the appropriate information of participants and evidence types that the relevant national DE4A participants are going to request and provide. Each SMP must only store and manage the information related to the participants of the same country as where the SMP is located, so that each country is only responsible for its own information.
-* A national SMP available to that partner.
+=== Governance procedure ===
-* A DE4A Connector.
+When populating/updating the information in the SMP, the [[Useful information on pilots and participants]] Wiki page should also be updated to stay aligned. After that, both ATOS (Ana María Piñuela, Alberto Crespo, Javier Presa) / WP5 (Javier Ferrero, Javier Baena, Eduardo Moreno, Hugo Berdón) should also be informed about these changes.
-* A Data Evaluator.
-On the other hand, if a partner wants to receive a message in its DO from the DemoUI, that partner needs to set up the complete infrastructure of a Data Provider:
-* A national SMP available to that partner.
+=== TIP ===
-* A DE4A Connector.
-* A Data Owner.
-The Shared SMP cannot be used for participants other than the imaginary ones.
-=== URL addresses for playground environment ===
-The playground environment has a cross border infrastructure. Data consumer side is deployed at University of Maribor in Slovenia where DemoUI is acting as Data Evaluator and Connector as Data Requestor.
-* DemoUI DE - https://de4a-demoui-dev.informatika.uni-mb.si/
-* Connector DR - https://de4a-connector-dev.informatika.uni-mb.si/
-The Data Provider side is deployed at SGAD in Spain where the Connector is a Data Transferor and the Data Owner is the mocked DO
-* Connector DT - https://pre-as4gw-dt-de4a.redsara.es/de4a-it2-connector/
-* Mocked DO - https://pre-smp-dr-de4a.redsara.es/de4a-mock-connector/
-Kafka tracker is deployed at this URL
-https://de4a.simplegob.com/package-tracker/#!detail
-For detailed traceability, these are the topics where each component is logging to Kafka.
-* DemoUI - wp5-demoui-it2
-* Connector DR - log-test
-* Connector DT - de4a
-* Mocked DO - test
-=== SMP ===
-''This section only applies for those participants required to install an SMP instance.''
-Setup your own national SMP. The SMP must be installed, configured and populated with the right information. To install and configure the SMP, two documents are available on the OwnCloud:
-* 2022-04-01 Setting up a Service Metadata Publisher for DE4A.pdf
-* 2022-05-02 Configuring the SMP for the IAL.pdf
-Both documents can be found [https://newrepository.atosresearch.eu/index.php/apps/files?dir=/DE4A-Project/06%20Workpackages/WP5%20Components%20design/Setup%20documents/Setting%20up%20a%20SMP&fileid=1145283 here].
-To populate the SMP with the appropriate information, each partner must know the participants and evidence their national SMP should store. The Wiki page [[Useful information on pilots and participants]] may help in this task.
-==== TIP ====
 What information needs to be added?
@@ Line 78: / Line 39: @@
 For this example, the endpoint URL should be: <nowiki>https://de4a.simplegob.com/de4a-it2-connector/phase4</nowiki>
-=== DE4A Connector ===
+== 3. Setting up a DE4A Connector ==
-''Only applies for those participants required to install a Connector instance.''
+The DE4A Connector is needed to be able to exchange messages with other participants, since the communication is realised via these Connectors.The latest release version of the DE4A Connector is available at the [https://github.com/de4a-wp5/de4a/releases GitHub of WP5]. To install the DE4A Connector, an [[Installation and configuration guide of the DE4A Connector it2]] is available.
-Deploy the release version of the Connector from the [https://github.com/de4a-wp5/de4a/releases GitHub of WP5]. To do so, follow the DE4A [[Connector iteration 2 installation and configuration guide]].
+== 4. Development and integration of the final participant ==
+In DE4A, there are two types of the so-called "final participants": Data Evaluators and Data Owners. These are the entities that request or provide evidence, repectively. Each DE4A participant must develop its own final participant and integrate it with the other components.
-=== Data Evaluator / Data Owner ===
+In order to understand the common specifications each partner needs to follow to properly exchange messages with the rest of the DE4A components, the following resources are available within the Common specifications section of the WP5 part of the DE4A Wiki:
-In order to understand the common specifications each partner needs to follow to properly exchange messages with the rest of the DE4A components, the following resources are available within the Common specifications section:
-* [[DE4A common specifications and components|Common behaviour and interactions between components]]
+*[[Common behaviour and interactions between components]]
-** Description of the interaction patterns of the second iteration through communication diagrams. Data structures used during exchanges are also descripted there.
+** Description of the interaction patterns of the second iteration through communication diagrams. Data structures used during exchanges are also described there.
-* [[Summary of software interfaces.|Summary of software interfaces]]
+* [[Central IAL interface]]
+** Description of the software interface of the Central IAL.
+*[[Summary of software interfaces.|Summary of software interfaces]]
 ** Reference information on the software interfaces of the DE4A components.
-* [[DE4A Logs and error messages it2|DE4A Logs and error messages]]
+*[[DE4A Logs and error messages it2|DE4A Logs and error messages]]
 ** Updated version for the second iteration of the specification of the common error and logs messages used during exchanges.
+Once the Data Evaluator or Data Owner has been developed and deployed, it must be integrated with the DE4A Connector and SMP that will be supporting the communication of that final participant:
+* The de-do.json must properly updated to include the endpoint of the new final participant.
+* The SMP must also be updated with the participant ID and the evidence that the final participant will request (DE) or provide (DO).
+== 5. Integration with the Playground it2 ==
+The Playground can only be used in two ways:
+* By exchanging messages between the DemoUI and the Mocked DO as the participants involved.
+* By using the infrastructure of a partner to act as a Data Consumer or Data Provider.
+For the second option, it is mandatory to set up a complete interaction side: either the sender (DC) or the recipient (DP). This means that, in this second iteration, the use of only a DE or a DO to exchange messages via the Playground is not supported.
+For example, if a partner wants to send a message from its DE to the Mocked DO, that partner needs to set up the complete infrastructure of a Data Consumer:
+* A national SMP available to that partner.
+* A DE4A Connector.
+* A Data Evaluator.
+On the other hand, if a partner wants to receive a message in its DO from the DemoUI, that partner needs to set up the complete infrastructure of a Data Provider:
+* A national SMP available to that partner.
+* A DE4A Connector.
+* A Data Owner.
+The Shared SMP cannot be used for participants other than the imaginary ones.
+=== URL addresses for the Playground environment ===
+The Playground environment has a cross border infrastructure. Data consumer side is deployed at the University of Maribor in Slovenia where the DemoUI is acting as Data Evaluator and the Connector as Data Requestor.
+* DemoUI DE - https://de4a-demoui-dev.informatika.uni-mb.si/
+* Connector DR - https://de4a-connector-dev.informatika.uni-mb.si/
-USI and IM patterns have been updated compared to iteration 1. Subscription, notification and lookup patterns are new for this iteration 2.
+The Data Provider side is deployed at SGAD in Spain where the Connector is a Data Transferor and the Data Owner is the Mocked DO.
-=== Checklist for Connectathons ===
+* Connector DT - https://pre-as4gw-dt-de4a.redsara.es/de4a-it2-connector/
-A quick check points guide has been made to make Connectathon sessions more productive it is available [[DE4A Checklist for Connectathon|here]].
+* Mocked DO - https://pre-smp-dr-de4a.redsara.es/de4a-mock-connector/
+A Kafka tracker is available through the following URL: https://de4a.simplegob.com/package-tracker/#!detail
+For detailed traceability, these are the topics where each component is logging to Kafka.
+{| class="wikitable"
+|+KAFKA
+!Component
+!Topic
+|-
+|DemoUI
+|wp5-demoui-it2
+|-
+|Connector DR
+|log-test
+|-
+|Connector DT
+|de4a
+|-
+|Mocked DO
+|test
+|}