VERSION 1.0.0 MANDATORY

Contents

1. Overview

The Exchange Data Model makes use of the functional capabilities that are provided by the RegRep V4 Query Protocol. In the following section, we describe the query that is supported by the OOTS.

2. Common Query Attributes

2.1. Common Query Attributes

The following table depicts the attributes that are common between all the types of requests and are expressed as Top-Level Slots and specific Query Slots of the RegRep Information Model.

2.2. Evidence Request Subject

The Evidence Subject is either a Natural Person or a Legal Person. The Query Slots contain the required information to identify the Evidence Subject. 

A Query Request may either contain a NaturalPerson OR a LegalPerson depending on the subject of the query, but NOT both. An additional Authorized Representative may be specified.

In order to describe the Natural Person and the Legal Representative, the eGovernment Core Person Vocabulary is used. For the Legal Person, the eGovernment Core Business Vocabulary is used. The vocabularies are maintained by Interoperable Europe which succeeds the ISA²  action.  

The Document-Based Query defines a structure for requesting unstructured or structured pieces of evidence that will be used in a specific procedure. The Query Response contains the evidence and evidence metadata with a reference to the document itself.

3. Evidence Query

3.1. Evidence Query attributes 

The Evidence Exchange is always based on an evidence query. The ER requests for the evidence document and its metadata to be provided in the response. The table below shows the query attributes and their value/structure.

3.2. Query Request

The ER needs to provide an Evidence Request that contains several evidence-related request parameters. The details contain the following attributes which act as a filtering mechanism to the EP:

• The Identifier of the Data Service Evidence Type received from the Data Service Directory
• The Evidence Type Classification and Title of the evidence received from the Evidence Broker and/or Data Service Directory 
• The Format and and in case of structured Evidence a Conformance Profile of the selected Distribution retrieved from the Data Service Directory.
• A desired Transformation of the Evidence pointing to a subset of a the conformance profile described in the Semantic Repository. 
  
• Optional Classification Values indicated in the Data Service Directory for the EP that help the EP to identify the evidence or data service.

The response option attribute 'returnType' is set to "LeafClassWithRepositoryItem" in order to explicitly state that the requested document MUST be inside Query Response from the EP.

The Evidence Request is expressed along the Evidence Request Syntax Mapping.

3.3. Query Responses

The Query Response can be either an Evidence Response or an Error Response whereas the status of the Evidence Response can be success of unavailable.

Success: The Evidence Response is sent after a successful validation of the request received and it contains the Evidence Metadata of the attached Evidence together with the Evidence documents themselves. The status of the Evidence Response is set to 'Success'. The Evidence Response with the status 'success' is specified along the Evidence Response Syntax Mapping. The Evidence Metadata described in the Evidence Request is expressed using DCAT Application Profile. 

Unavailable: In situations where evidences may exist that are not immediately available, a Data Service may notify the user and start a process to make these evidences available at a later point in time in the Evidence Response. The status of the Evidence Response is set to 'Unavailable'.  The status may be used by a Data Service that generates evidences using a process that cannot be completed within the duration of an interactive user session. Based on this response, the Online Procedure Portal has an obligation to inform the user accordingly. It is up to the user to decide whether to proceed with the procedure without the unavailable evidences, or to stop (or, if supported by the Online Procedure Portal, pause) the procedure and re-start (or, if supported, continue) it at a later point in time and re-request the evidences at that later time. This mechanism is opt-in for Data Services. A Data Service that supports the mechanism may, optionally, indicate at which date and time any evidences may be made available, helping the user decide whether and when to return to the Online Procedure Portal and continue the procedure. The Evidence Response with the status 'unavailble' is specified along the Evidence Response Syntax Mapping.

Failure: The Error Response contains the exception raised by the EP. The exception can be either a handled one, which means that the ER SHOULD retry the submission of the Evidence Request fulfilling the requirements present in the exception or an unhandled one which the ER must accept and inform the user of the unsuccessful transaction. The Query Model caters for both handled and unhandled exceptions. A typical example for a managable exception is the need for an Evidence Provider side preview which is declared in the Error response. The Error Request is expressed along the Error Response Syntax Mapping. 

4. Flows and Flow Choreography

4.1. Basic Flow 

The following diagram shows a successful evidence request-response flow. It includes the Online Procedure Portal in the Evidence Request Member State and the Data Service in the Evidence Provider Member State. Both connect to Access Points that are connected using eDelivery. Both eDelivery Messages use the QueryManager service, with the ExecuteQueryRequest action in the request and the ExecuteQueryResponse action in the response. The response RegRep message contains a RegistryObjectList which includes zero or more RegistryObject structures.

Note that instead of an Online Procedure Portal or Data Service,  an Intermediary Platform may be used.

Query requests are unique and carry a unique identifier attribute. An Online Procedure Portal MUST NOT use an identifier more than once. A Data Service MUST reject requests that use identifiers that were used in previously processed requests.  Query responses refer to query requests by referencing the unique identifier of the request. An Online Procedure Portal MUST NOT process responses that use request identifiers of previous requests to which it already received a response. This means that to return more references to the Online Procedure Portal, even if it is for the same user in the same session, for the same evidency type and data service, a new unique request MUST be issued.  

The following diagram shows an error request-response flow. It includes the Online Procedure Portal in the Evidence Request Member State and the Data Service in the Evidence Provider Member State. Both connect to Access Points that are connected using eDelivery. Both eDelivery Messages use the QueryManager service, with the ExecuteQueryRequest action in the request and the ExceptionResponse action in the response. The response RegRep message contains an Exception structure.

Note that instead of an Online Procedure Portal or Data Service,  an Intermediary Platform may be used.

4.2. Complex Flows 

Basic flows can be combined in various ways:

• When using the Preview Feature, two basic flows are executed in sequence. The response of the first flow is an exception containing a preview link. This feature is defined in section 4.9.
• When requesting multiple different types of evidence from a different Data Service,  or when interacting with multiple Data Services, different basic flows may be executed sequentially and/or in parallel.

Examples of complex flows are provided in chapter 4.10. 

4.3. Correlation 

Since eDelivery is based on asynchronous AS4 messaging, each request from an ER and each response (successful or error) from an EP use different HTTP connections.  Correlation can be established using data in the AS4 message and in the RegRep structures:

• All exchanges relating to a single user session use the same value for the AS4 ConversationId header.
• Each request - response pair can be correlated using the the query:QueryRequest/@id and query:QueryResponse/@requestId attribute pairs.
• An error response that signals that a preview loop is required can be correlated to the subsequent response in that follow-up request using the unique preview URI.

4.4. Timeouts

Both Online Procedure Portals,  Data Services and Preview Spaces shall provide a configurable timeout feature. The configuration shall control whether timeout handling is provided and, if yes, the maximum duration between delivery of a query:QueryRequest and the creation and submission of the query:QueryResponse. 

• If a Data Service implements timeout, then it shall return a timeout exception response (see section 4.5.3.2.1) instead of a successful response when the process of processing the request exceeds a configured timeout value. Online Procedure Portals are REQUIRED to support processing of timeout exception responses.
• If an Online Procedure Portals implements timeout, then it shall generate a timeout error in case the Data Service did not reply using either a successful evidence response or an exception response to an issued evidence request within a configured timeout interval.   The timeout interval used by Online Procedure Portals shall be configured to a value that exceeds the timeout interval of the Data Service and also takes into account the time needed for transmission and processing of the response including eDelivery. Note: As there is not guideline and evidence yet, the value must be assumed by the Online Procedure Portal.      

Note that in the case of Basic Flows (see 4.4.4.1 above), the timeout applies to automated processing.  In the case of Complex Flows (see 4.4.4.2 above) in particular flows involving Preview (see section 4.9), the timeout should take into account the time needed for the user to (re)authenticate,  to preview evidences, and to decide on whether or not to use them.  The nature of evidence types in OOTS varies and some cover complex data that may require a significant amount of time for the user to review.