Contents
1. Introduction
1.1 Goals of this section
In the execution of evidence exchange, for a variety of reasons there may be variations in the flows that may occur. This section aims to provide an overview of the main flow variation categories and to illustrate this using some sample flows.
All content in this section is informative. It does not cover all potential flows, In many flows, at some step, more than one alternative action is possible. The choice between such alternatives may be dependent on policy, system limitations or other factors.
Regular process variations include:
- Whether or not the procedure requires preview.
- Whether or not re-authentication is needed to determine the user's identity on the side of the evidence provider.
- Whether there exists 0, 1 or more than one piece of evidence of the requested type for the user.
- Whether the evidence is structured or unstructured
- Degree to which the identity attributes in the request allow to determine whether there may be pieces of evidence for the request.
- For a structured piece of evidence, if it conforms to an agreed data model registered in the Semantic Repository or is another structured piece of evidence.
Error situations could emerge in either of the two request-response loops due to the reasons including the following:
- Any of the eDelivery message transfers may fail due to technical reasons (e.g. an Access Point is down).
- There may be errors or timeouts in connections between Access Points and Portal, or between Access Points and Data Service.
- There may be errors or timeouts in connections between the Data Service (a component that handles the OOTS interface) and the base registry or other source from which the evidence is obtained.
- Responses may not be returned, or not returned in time.
- The Data Service may categorize error situations differently (e.g. use a generic or more specific error)
- The user may stop interacting (e.g. Internet connection is down, browser window closed by mistake, or some interruption).
- The user may not be able to authenticate on the evidence provider side.
- The preview link or return link may have expired.
- There may be mismatches in identity attribute values between the two requests
- There may be mismatches in identity attribute values between the first (included in request) and second (in preview area) authentication.
- Expected dependencies or synchronizations may not apply. For example, the second loop evidence request may be issued, but the user does not visit the preview area or vice versa.
The source of all diagrams is in https://code.europa.eu/oots/tdd/tdd_chapters/-/tree/master/spec_diagrams/ch4/flows.
The content in this section is informative, preliminary and incomplete. It is provided as a first pass.
In the diagrams, it is assumed that:
- the Data Service and Preview Space are separate components. Since their processing is interdependent, some synchronization steps are needed. A tighter integration of the two components is an implementation option and could make some of this processing easier.
- the Data Service is an OOTS specific component that acts as a facade for a(n existing) Base Registry. It is responsible for interaction with other OOTS components including the eDelivery Access Point, but does not store any pieces of evidence and does not perform the matching of pieces of evidence to requests.
- the Data Service also intermediates between the Preview Space and the Base Registry. But it is also possible for the Preview Space to be directly connected to the Base Registry..
Details of formats, protocols used by the internal interfaces between Data Service, Preview Space and Base Registry are out-of-scope for the Technical Design Documents as they are within the national domain.
1.2. Relation to Common Services flows
All flows described in this section assume that the user has successfully authenticated and that the Online Procedure Portal has used (directly or indirectly, using a shared service) the Common Services to determine the Data Services that may hold pieces of evidence of a selected type in a selected Member State. So for the user, the first step in all the diagrams as shown is not in fact the first step in the use of OOTS in the procedure, but is a step that follows on other successfully completed steps for authentication and common service interaction.
To see descriptions of the flows of the Common Services, you can visit:
Evidence broker
- API documentation: https://oots.pages.code-europa-eu.gitlab.host/tdd/apidoc/evidence-broker.
Data Service Directory
- API documentation: https://oots.pages.code-europa-eu.gitlab.host/tdd/apidoc/data-services-directory.
1.3. Relation to Projectathon test cases
This section covers the evidence exchange related aspects of the test cases defined for use in the OOTS Projectathons other than the two LCM test cases.
The labels [TC01] refer to the test case labels defined for the test cases.
2. First loop, sample success flows
2.1 A flow not involving preview that returns zero pieces of evidence [TC02]
The following sample flow involves a request for evidence of a particular evidence type to a Data Service that has no pieces of evidence of that type for the user. This flow is successful in the sense that OOTS was successfully used, it just did not result in any evidences being exchanged. No second preview loop takes place.
| Step | Description | Notes |
|---|---|---|
| 1 | From the list of potential evidence providers, the user selects one and instructs the Online Procedure Portal to query the associated Data Service. | |
| 2 | The Online Procedure Portal constructs an OOTS evidence request. | The evidence request contains a requestId attribute that uniquely identifies the request and allows subsequent correlation of the response. See section 4.5.1. |
| 3-4 | The evidence request is packaged and submitted to the Access Point (C2). The submission sets the To/PartyId to the value of the C3 Access Point discovered in the interaction with the Data Service Directory and the finalRecipient to the Data Service identifier. It also sets the AS4 ConversationId to a new unique value. | The submission may involve middleware or other integration technology. The details of the interface depend on implementation. See section 4.7 on the use of conversation identifier for correlation. |
| 5 | The Access Point of the Online Procedure Portal (C2) successfully sends the message to the Access Point of the Data Service (C3). | |
| 6 | The C3 node delivers the request to the Data Service | If a single Access Point supports multiple Data Services, the finalRecipient attribute can be used for routing the message towards the intended destination. See section 4.7 and the eDelivery AS4 specification. |
| 7 | The delivered eDelivery message is unpackaged. | |
| 8 | To process the request, it should be validated. In this flow, the validation passes successfully. | Validation covers schema and business rules. The GIT repository has the relevant schemas and Schematron encodings of the business rules. It will also provide the relevant code lists in Genericode format that can be used for automated validation. |
| 9 | The Data Service interacts with the Base Registry. | The interface between Data Service and Base Registry is not defined in OOTS as it is internal to the Member State. |
| 10 | In this sample flow, the Base Registry is able to indicate that there are no pieces of evidence for the user. This may be because:
In this flow, it is assumed that the policy of the Evidence Provider is to not force the user to be redirected in situations where this is clearly pointless. For this specific flow, the PossibilityForPreview slot can have any value, but in other flows presented in this section, the processing depends on the value of the slot. | An example of the first case is where the request contains a unique and processable natural or (represented) legal person identifier issued by an eID scheme in the evidence provider Member State and that identifier is stored with pieces of evidence in the Base Registry. An example of the second case could be where the person was born in a particular year and the base registry has no evidence about any person born in that particular year. (For example, only evidences issued recently are available). Even though the user identity may still be ambiguous, re-authentication serves no purpose. In other situations (see other flows), it will be impossible to determine if there are pieces of evidence for the user. In those situations, the second loop with preview applies. |
| 11 | The Data Service constructs an evidence response indicating that there are no pieces of evidence available. | Absences of any evidence is encoded as a RegistryObjectList that does not contain any RegistryObject elements. |
| 12-13 | The evidence response is used in a submission to the Access Point | See section 4.7.2.4 for a description on reverse routing of OOTS eDelivery messages. The originalSender and finalRecipient values are swapped compared to the request, as are the value of the From/PartyId and To/PartyId. The ConversationId is copied. |
| 14 | The message is successfully transmitted by C3 to the C2 Access Point. | |
| 15 | The OOTS response payload and associated metadata are delivered to the online procedure portal. | If a single Access Point supports multiple Online Procedure Portals, the finalRecipient attribute of the response (copied from the originalSender in the request) can be used for routing to the correct destination. |
| 16 | Correlation information is used to link the response to the correct user session. | Multiple users may be interacting with the Online Procedure Portal. Since message exchange is asynchronous, responses for requests from multiple users may arrive out-of-order. Correlation is encoded at eDelivery level (conversation identifier) and at RegRep level (requestId attribute). See step 2 where this is stored for the user session. |
| 17-18 | No evidences are made available to the procedure and user session, and there is no second loop. The portal should notify the user. Use of OOTS ends here for this Data Service. | Details are implementation dependent. |
2.2 A flow not involving preview that returns one or more pieces of evidence [TC01], [TC05]
The following sample flow involves a request for evidence of a particular type to a Data Service that has pieces of evidence of that type for that user. The procedure does not require preview and the request can be processed without re-authentication. Therefore, no redirection of the user takes place.
In the following table, steps that are the same as in the first flow on this section are omitted.
| Step | Description | Notes |
|---|---|---|
| 2 | The Online Procedure Portal constructs an OOTS evidence request. For this specific flow, the PossibilityForPreview slot is set to a false value, as the procedure does not require offering the user the possibility to preview pieces of evidence. | |
| 9-10 | The Data Service and Base Registry are able to match the user to specific pieces of evidences. | This could happen if the request contains a unique and processable natural or represented legal person identifier issued by an eID scheme in the evidence provider Member State and that identifier is stored with (or otherwise, directly or indirectly, linked to) pieces of evidence in the Base Registry. |
2.3 A flow involving preview due to ambiguous match
The following flow shows an exchange where identity attributes in the request do not allow unambiguous identification of a unique user for which evidence may be available. This means that the user needs to be re-authenticated on the side of the evidence provider in order to uniquely identify the user and find any pieces of evidences for her. The preview link that is returned is therefore not a link to a specific piece of evidence, but to an interactive page at which the user can re-authenticate herself. The re-authentication may provide additional identity attributes that were not shared via eIDAS (such as national identifiers) and allow determining to which specific person the request relates.
| Step | Description | Notes |
|---|---|---|
| 10 | A response is provided by the Base Registry. It is determined that there may be evidence about the person but the identity attributes provided in the request are not sufficient. | In this case, the value of the PossibilityForPreview slot is irrelevant. The redirect is needed to precisely identity the person to whom the request relates. |
| 11-13 | A link is constructed that can be used in the second loop. This link must be restricted to users with identity attributes matching those used in the evidence request, the session, the requested evidence type and the requested evidence requester and provider. | The diagram assumes that some state information is stored (in step 12) that can be retrieved in the second loop, so that the link itself does not have to include this state information or personal data but can be a random value, e.g. using a GUID (e.g. something like https://preview.some.domain/sess/9cd74f46-4162-4e34-9d4e-5c8f83d44e54). But this is an implementation choice. Also note that the link could be time-limited. |
In case the value of the PossibilityForPreview slot is set to a true value, the redirect is needed even if there is only a single precisely identified person whose identity attributes match the identity attributes of the request.
3. First loop, sample flows with error occurring in Data Service
3.1 Error in connection to base registry [TC03]
This flow shows a scenario in which an evidence request is successfully created, exchanged using eDelivery and delivered to the Data Service. In this diagram, the assumption is that the Data Service does not manage the evidence data itself but is a facade for one or more base registries. An error occurs in connecting to the base registry.
| Step | Description | Notes |
|---|---|---|
| 8-9 | In the connection to a base registry, an error may occur. The Data Service constructs a QueryException response which it sends back to the requester. |
3.2. Timeout in connection to base registry
This flow shows a scenario in which an evidence request is successfully created, exchanged using eDelivery and delivered to the Data Service. In this diagram, the assumption is that the Data Service does not manage the evidence data itself but is a facade for one or more base registries. In the connection to such a base registry, a timeout may occur. The Data Service constructs a TimeoutException response which it sends back to the requester.
| Step | Description | Notes |
|---|---|---|
| 8-9 | In the connection to a base registry, an internal timeout may occur. The Data Service constructs a TimeoutException response which it sends back to the requester. |
3.3. Error in validating the request
| Step | Description | Notes |
|---|---|---|
| 7-8 | Data Services should validate evidence requests prior to further processing. If the request is not valid, the Data Service constructs a InvalidRequestException response and uses eDelivery to send it back to the requester. |
4. First loop, sample flows with error occurring in Online Procedure Portal
4.1. Response that cannot be correlated
In this scenario, a data service constructs and returns an evidence response to a particular evidence requester. Since there may be multiple users in the portal using OOTS, responses must be correlated to the requests they relate to, so that pieces of evidence are linked to the right user and/or user session. This correlation is to be done using the eDelivery conversation identifier and the requestId attribute value of the QueryResponse. In case this value is not linked to any known current user and/or user session, the event is logged for investigation. This error can occur in both the first or second loop.
4.2. Problem sending evidence request [TC04]
In this scenario, all steps up to and including the selection of a Data Source in the portal proceed correctly and successfully, but there is an error in the submission of the evidence request to the Access Point. In this case the use of OOTS is impossible.
5. Second loop sample success flows
5.1 Successful redirection, re-authentication, evidence retrieval and transfer [TC06], [TC07], [TC08], [TC10]
This diagram shows a successful execution of preview. It is limited to the second loop and presupposes a prior successful execution of the first loop such as the one in 2.3 above.
The flow covers variations across three dimensions:
- Whether the preview re-direction is a unique redirection for one Data Service or whether it is a redirection for one among more than one queried Data Services.
- In case there are multiple re-directions, the flow assumes the user simply executes multiple re-directions in sequence [TC06]
- However, redundant re-authentication after a first visit to a Preview Space can be avoided using regular cookies [T0C7]. This is consistent with testing by the User Experience team.
- Whether there are pieces of evidence for the user or none.
- Evidences are available for the identified and re-authenticated user, the user previews and makes a decision on whether or not any of them are to be used.
- There are no evidences for the identified and re-authenticated user.
- If any pieces of evidence need to be transformed to a viewable format to be previewed.
In case the user decides to not use any piece of evidence, or if there are none, an empty RegistryObjectList is returned [TC08].
If there are any pieces of evidence that the user selects to use, they are used to populate the RegistryObjectList [TC06].
| Step | Description | Notes |
|---|---|---|
| 1 | The user, shown the presented link, decides to continue the OOTS process. | This assumes the redirection is done by presenting a link or other user interface control to the user. |
| 2-5 | A second request-response loop is started. This is a behind-the-scenes action, invisible to the user. | Content of the second request and how it relates to the first is described in 4.5.1 and 4.8. As explained in 4.7.2.5. the value of the AS4 conversation identitifier will be the same for all requests and responses in the two loops. |
| 6 | In parallel to the second request being sent, the user moves to the Preview Space using the selected link. So if the preview URL is https://preview.some.domain/sess/9cd74f46-4162-4e34-9d4e-5c8f83d44e54 the return URL is https://portal.requester.domain/oots/5aa8f1a4-ab4c-43e5-9e42-c3c3911ef10e and the return method is GET, then the user is moving to https://preview.requester.domain/sess/9cd74f46-4162-4e34-9d4e-5c8f83d44e54?returnurl=https%3A%2F%2Fportal.some.domain%2Foots%2F5aa8f1a4-ab4c-43e5-9e42-c3c3911ef10e&returnmethod=GET. | The link needs to include a return URL and return method as described in 4.7.5. This needs to be stored as it is needed in step 20. It is an error if no return URL is provided (Flow not yet covered in this section). |
| 7 | The user accesses the Preview Space using a URL that includes the unique URL issued in the first loop. Using the URL as key, data stored in the first loop is retrieved. This includes identity data of the user, the requested evidence type, the evidence provider. This allow the Preview Space to prepare the preview for the user. | It is an error if the visited URL is unknown or is known but has expired (Flow not yet covered in this section). |
| 8 | The Preview Space tries to obtain the identity of the user based on cookies issued to the user agent (a Web browser used on a computer or other device) that can be used to manage session state information. | It is up to the Preview Space to decide about the "freshness" of the session identity. |
| 9-12 | In case the user cannot be identified based on session state, the Preview Space allows the user to re-authenticate. | |
| 13 | If the user recently used the Preview Space to preview another piece of evidence, she is already known to the Preview Space and a cookie was issued to the user agent she used. This includes any use of a Preview Space for a specific user in the context of single procedure session, even for different Data Services. | |
| 14 | The Preview Space needs to validate that the identity attributes from the evidence request match the attributes obtained from re-authentication. | This validation is required to protect against certain potential fraudulent situations. It is an error if the attributes do not match (Flow not yet covered in this section). |
| 15 | Some synchronisation is performed between the Preview Space and the Data Service. | This synchronisation has to be done before the user completes the interaction with the Preview Space. In this case, it is done after the re-authentication. It is an error if no second request has been transmitted, or vice versa if a request has been transmitted but the user has not visited the URL. (Flow not yet covered in this section). |
| 16-18 | Using the information from the evidence request and the user identity, the Data Service can determine if any pieces of evidence for the requested type are available for the user. | |
| 19-23 | If there are any pieces of evidence, they are each individually retrieved and presented for preview to the user. The Preview Space records the decisions of the user and also communicates the outcome (which may be an empty list) to the Data Service. | |
| 20 | The evidence may need to be transformed to allow the user to preview it. For example, if it is in a structured format. | |
| 24-25 | Alternative, if there are no evidences, there is no need to preview any of them. In this case the response registry object is empty. The user needs to be informed. She can return directly to the Online Procedure Portal, | |
| 26 | The user, having finished previewing and selecting any pieces of evidence, returns to the online procedure portal. | The return link and method were made available in the visit, see step 6 above. |
| 27-31 | Any pieces of evidence, if available and selected are wrapped in an evidence response and sent, using eDelivery, to the Online Procedure Portal. | If there were evidences but the user decides not to use them, the RegistryObjectList is the empty list. |
5.2 Support for evidence unavailable feature
This flow covers the "evidence unavailable" feature.
| Step | Description | Notes |
|---|---|---|
| 1-5 | As before, a second evidence request is made and the user accesses the Preview Space. After (re)authentication, the Data Service queries the base reqistry for any available evidences for the user for the requested evidence type. In this flow we assume the base registry distinguishes and can report on two different situations:
| The feature does not distinguish between situations where the Base Registry already knows definitely that a number of specific pieces of evidence exist but are not yet available, or just that there may be (an unknown or unspecified number of) evidence of the requested type. |
| 6-7 | The query result status is initialized to a default status urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success, with an empty list of registry objects. | This step is implicit in any flow but was omitted from the other flow descriptions and diagrams. |
| 8 | If there are no results from the base registry query, so no available and no unavailable pieces of evidence, the user is informed and her interaction on the evidence provider side ends. | |
| 9 | If there are results from the base registry, an interaction with the user in the Preview Space is started, for each result. | |
| 10-14 | If a piece of evidence is available, the system interacts with the user for preview and confirmation on whether or not to use the piece of evidence. | This diagram simplifies the user interaction and omits users changing their opinion, skipping a preview or previewing a piece of evidence more than once etc. |
| 15-19 | If a piece of evidence, or an unknown number of pieces of evidences, of the requested type is not available, the user is informed. This scenario assumes the user has the option of explicitly requesting that the (piece of) evidence be made available so that at a future point in time it will be available. If the user chooses not to make such a request, the response status is not updated. | |
| 17-19 | The user indicates that she wants the evidence to be available for use in the procedure, and through the Data Service notifies the Base Registry to start a process to make the evidence available. The evidence response status is set to urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Unavailable to inform the evidence requester that (additional pieces of) evidence may be available in the future. | As an implementation option, the evidence provider systems may allow the user to provide contact information (for example, her email address) so that she may be informed if/when the evidence is available. |
| 20 | After completing her interaction on the side of the evidence provider, the user returns to the evidence requester side. | |
| 21 | The Data Service constructs and submits an evidence response. The response
| In the common case where there is at most one piece of evidence of a particular type for a user, the response will:
|
| 22-27 | All remaining steps are as in the preceding situations. |
6. Second loop sample flows with error in Data Service - Preview Space
6.1 Timeout triggered by inactivity in Preview Space [TC09]
This scenario covers the second loop of OOTS evidence exchange. The user has been presented a preview link by the portal and decides to follow it. This triggers the sending of the second evidence request and the movement of the user to the Preview Space. When the second request is received by the Data Service, it sets an expiration date and time, which limits the time during which the user must complete her preview actions. After navigation to the Preview Space, the user successfully re-authenticates. Her identity attributes are compatible with the attributes in the OOTS evidence request. However, at this point in time the user does not continue the preview steps. It could be that she is distracted or by mistake closes her Web browser, or that her Internet connection is interrupted. After a while, a timeout occurs. This is reported back to the Online Procedure Portal using an exception message.
