Contents
1. Introduction
This version of the OOTS includes support for an updated Evidence Preview Service feature. A component that implements the service is referred to using the term Preview Space. This specification aims to define a service with the following main features:
The service is provided by or on behalf of an Evidence Provider.
The service complements and supports the Data Service of the Evidence Provider.
A single Preview Space may serve more than one Data Service and more than one Evidence Provider.
A Data Service may use different Preview Spaces (for example, for different evidence types).
The operation of the preview service is linked to the regular processing of the Data Service as further detailed in 2 and 3 below.
The operation of the preview service is linked to the regular processing of the Online Procedure Portal as further detailed in 5 below.
The Preview Space may be implemented as an integrated feature of a Data Service component or as a standalone component.
Use of the service by a user for a particular evidence request is identified by a preview URL (Uniform Resource Locator). This URL is also the means for the user to access the service.
The preview URL shall be unique to the request and therefore to the user, requested evidence type, evidence requester and evidence provider that the request relates to. However, the specific format for the URL is up to the implementation.
The preview URL is communicated by the Data Service to the Online Procedure Portal, along with other preview metadata as described below in section 4, as a response to an initial evidence request.
Any pieces of evidence selected for use in the procedure are returned by the Data Service to the Online Procedure Portal, as a response to a second follow-on request that includes a previously provided preview URL. This response is made after the user completes his or her interaction with the Preview Space for the specified URL.
The Preview Space may ask the user to re-authenticate himself or herself as an additional security control, complementing and confirming the prior authentication of the user on the side of the Online Procedure Portal. This is an implementation and/or policy decision.
The Preview Space may use re-authentication to help to uniquely identify the user, in case the identity attributes in the evidence request (based on the authentication of the user to the Online Procedure Portal) are not unique to a single person.
The Preview Space shall allow the user to decide, for each piece of evidence matching the evidence request, whether or not to use it in the procedure.
Before deciding whether or not to use a piece of evidence, the Preview Space shall offer the user the option to preview it. However, under the SDG regulation the user is not obliged to preview.
The details of user experience, interaction and user interfaces are out of scope for this specification but this does not affect interoperability.
The Preview Space shall also facilitate the smooth navigation of the user back to the Online Procedure Portal to allow him or her to continue the online procedure that he or she was executing as described in section 5 below.
The Preview Space, like all OOTS components, may be integrated indirectly, using integration middleware.
2. Evidence Preview Service Flow
The OOTS Preview feature consists of two separate but related evidence request-response message flows, executed in sequence. The first of these flows is a machine-to-machine flow, in which the response is to be returned immediately. The second of these flows occurs in parallel to an interactive preview browsing session. The response is only sent after completion of that session, which in many cases could be minutes after the request.
The following diagram specifies an expected successful operation of preview feature and the expected processing of the Preview Space and Data Service. Variations and exceptions are explained in the summary table following the diagram.
Step | Description | Notes |
1 | The procedure starts when the user, while executing an electronic procedure, is offered to use the OOTS to retrieve evidence. | This step is provided for context purposes only. The diagram omits the user authentication steps and the interaction with common services. |
2-8 | The first request-response loop is executed. | |
2 | The evidence request is sent to the Data Service. | As a result of the preceding steps (authentication, interaction with common services), the Online Procedure Portal constructs a an evidence request containing a query:QueryRequest as specified in section 4.5.1. Unlike the similar evidence request in step 9, this request does not include the “PreviewLocation” Slot. |
3, 5 | The Data Service and the Preview Service prepare and coordinate for the evidence preview. | In this step, a unique preview URL is generated and shared between the Preview Space and the Data Service. This serves to allow the two services to synchronize their operation in the second flow. Therefore the URL should be uniquely linked to the evidence request. |
4 | The Preview Service stores data. | Data is to be stored to prepare the Preview Space for the visiting user and to allow identity matching and request validation. Stored data should include:
Alternatively, the data could be stored by the Data Service and retrieved (see step 11) by the Preview Space, or in a separate component. |
6 | The preview URL is returned to the Online Procedure Portal | The message format is that of an evidence error response message, see section 4.5.3, where:
|
7, 8 | The Online Procedure Portal informs the user that the Data Service indicated that he or she needs to navigate to the Preview Space. | This can be done by presenting a clickable hyperlink, derived from the "PreviewLocation" and "PreviewMethod" as described in section 4 below. If provided, the content of the "PreviewLocationDescription" slot can used in the link. The Online Procedure Portal can filter the natural language alternatives to match its presentation language or (if known) user preference. |
9-23 | The second request-response flow is executed. | In parallel, the user interacts with the Preview Space. |
9 | The Online Procedure Portal sends a second evidence request. | For all rim:Slots except IssueDateTime, this evidence request have the same content as the first request. The eDelivery message that carries the request should have the same values for conversation identifier and other values. In addition to this, unlike the evidence request in step 2, this request does include the rim:Slot “PreviewLocation”. Its content is that of the rim:Slot “PreviewLocation” in the first response exchanged in step 6. This request shall not contain any "PreviewMethod" or "PreviewLocationDescription" slots. The receiving Data Service should validate this and return an error if validation fails, and alert the Preview Space. While the diagram show this step as preceding the user redirection of step (10), the request may be delayed due to operational circumstances. However, this is not an issue as the request is only needed to allow generation of a second response (in step 22), which in practice will be many seconds if not minutes later. |
10 | The user follows the link to the Preview Service. | The link includes the return URL as described in section 5 below. |
11 | Retrieve and validate data | Using the data from the initial request, stored in step 4, the Preview Service determines that the link has not expired and obtain data from the original request, including user identity attributes. If the link has expired, or expires while the user is using the Preview Service (not shown), the Preview Service shall inform the user. It shall also, through the Data Service, return an evidence error message of type rs:TimeoutExceptionType to cancel the second request sent under step 9. |
13-15 | The user is identified | While the preview URL should be unique, is exchanged securely to the Online Procedure Portal and should only be known to the user, proof of knowledge of the URL may be deemed insufficiently secure. Furthermore, the identity attributes in the original request may not uniquely identify the data subject. Therefore, the Preview Space may re-authenticate the user using either a national eID of the Evidence Provider Member State, or using eIDAS nodes. If re-authentication fails, the Preview Space should:
If the identity attributes of the user as expressed in the original request (steps 2, 4, 11 above) do not match the attributes obtained from the national re-authentication, the Preview Space should:
|
16, 17 | Find (list of) piece(s) of evidence | Now that the user is successfully and uniquely authenticated, the list of pieces of evidence for the user for the selected type of evidence for the selected evidence provider can be retrieved for preview. In the diagram, this is done by using the Data Service as a back-end to the Preview Space, but this is an implementation-specific choice. |
18, 19 | Interact with user | The Preview Space now interacts with the user, allowing him or her to decide which if any pieces of evidence to use in the procedure, and to preview it. |
20, 22, 23 | Provide decision | Once the user has made his or her decision, this is relayed to the Data Service. The selected pieces of evidence (if any) are packaged in an evidence response message as defined in section 4.5.2. |
21 | Return user | In parallel, the Preview Space presents a return link that allows the user to return to the Online Procedure Portal. The link is constructed from the return URL as described in section 5 below. |
| 22, 23 | Construct evidence response and send using eDelivery | This step requires the second evidence request (step 9) to have been received and processed successfully. The response query:QueryResponse/@requestId is set to the query:QueryRequest/@id of the request. |
25 | Complete exchange | Once returned, the user can continue his or her procedure. |
3. Coordination of Evidence Preview Service and Data Service
The Evidence Preview Service and the Preview Space that implements it shall coordinate their operation with the Evidence Query Service functionality of the Data Service. The details of this are up to the implementation of the two services but shall meet the following requirements:
For the purposes of the OOTS, the Preview Service only exists to support the Data Service.
For evidence requests that do not contain a preview URL, the Data Service and the Preview Service shall establish a preview URL. The format of the URL is described in section 4 below. The Data Service shall return the preview URL as defined under step 5 in the diagram in section 3 above.
The Preview Space shall only allow access for preview URLs that it issued and communicated to the Online Procedure Portal and the user using an evidence error response message as described under section 2.
The Preview Space and Data Service shall agree on any timeout values after which previously issued preview URLs are no longer valid. In particular, any time limits on access to the Preview Service for an evidence request shall not exceed the timeout intervals of the Data Service.
Access to the Evidence Preview Service for a particular set of pieces of evidence of a specific type shall be limited to users of OOTS and shall be available only after a request for evidence of that type has been made to a Data Service.
When the Data Service provides a response to an evidence request, the response shall include all and only those pieces of evidence that the user decided to use. This selection is made to the Preview Space and communicated to the Data Service.
Within timeout intervals, the Data Service shall not provide an evidence response to the evidence request before the user has decided whether or not to use any matching piece of evidence.
4. Preview Location Metadata
Preview Location Metadata is provided by the Data Service (in coordination with the Preview Service) to the Online Procedure Portal, as content of the following three slots in the rs:Exception in the the evidence error response:
A mandatory Slot “PreviewLocation” with a rim:SlotValue of type rim:StringValueType. This Slot provides the URL of the server on which the Preview Space is available for preview related to the evidence request. This slot is reused in the second evidence request message.
An mandatory Slot “PreviewMethod” with a rim:SlotValue of type rim:StringValueType. It has two allowed case-insensitive values: “PUT” or “POST”.
An optional Slot “PreviewLocationDescription” with a rim:SlotValue of type rim:InternationalStringType. This provides additional descriptions, in possibly multiple natural languages, of the preview location. At a minimum, a description should be provided in an official language of the Union that is broadly understood by the largest possible number of cross-border users.
The specific format for the preview URL, as communicated by the Data Service to the Online Procedure Portal, is up to the implementation of the Preview Space, but shall meet the following requirements:
The URL shall specify secure HTTP (“https://”) as transport.
The URL shall be unique to the request and therefore to the request parameters including the user identity attributes, requested evidence type, evidence requester and evidence provider that the request relates to.
The URL shall not include query parameters with the names “returnurl” or “returnmethod”. This is because parameters with those names are appended by the Online Procedure Portal as described in section 5 below.
5. Coordination of Evidence Preview Service and Online Procedure Portal
To support preview, the Online Procedure Portal needs to provide the following functionality:
Recognize, in the first flow, evidence error response messages of type rs:AuthorizationExceptionType that contain a “PreviewLocation” slot as indications of the use of the Preview Space.
Provide a departure page for the user to navigate to the Preview Space.
Process the language specific information of the preview location description metadata to allow the launch page to be customized to the user’s language choice (if known).
Provide a return address to which the user can return after completing his or her interaction with the Preview Space, using GET or POST methods.
Append the return address, in encoded form, as a value of the “returnurl” query parameter, to the preview URL prior to presenting the link to the user. This allows the Preview Space to return to the Online Procedure Portal, when finished previewing.
Append the HTTP method (PUT or GET) of the return address, as a value of the “returnmethod” query parameter. The allows the Preview Space to return the user to the Online Procedure Portal, when finished previewing, using the appropriate method.
6. Multiple Evidence Requests (Informative)
When executing an online procedure and using the OOTS, the user may want to retrieve multiple pieces of evidence. For example, a student may want to make available two diplomas that he or she obtained from different universities. This may result in two parallel evidence requests being sent to two different Data Services, in response to which two separate preview URLs for the two requests may be returned to the Online Procedure Portal.
Following the profiling of eDelivery for OOTS in chapter 4, section 4.7.2.5, different requests for the same user session have the same conversation identifier value. The Data Service and Preview Space could make use of this in the generation of the preview URL and are required to store the identifier. This allows the Preview Space to be aware that a user that visits it for one request may have other outstanding requests and may optimize its service accordingly.
In implementing OOTS, Member States are likely to implement a shared Preview Space component that can be used by multiple Data Services. The Preview Space implementation could optimize the user experience for handling multiple evidence requests. For example, when the user has authenticated himself or herself to the Preview Space after accessing the first preview URL, the Preview Space could set a session cookie that obviates the need for the user to authenticate again when he or she follows the second preview URL.
These and other optimizations are implementation-specific and out of scope for this specification.