Input data into the common services
These guidelines aim to help you when inputting your data into the Common Services.
The guidelines aim help you to:
- explain the role of the different components in the Common Services;
- differentiate between the two main roles (evidence requester and evidence provider) Member States need to consider when inputting their data, and the key tasks for each;
- understand the different types of experts you will need to collaborate with in your Member State to input and complete data in the Common Services.
The first part of the guidelines introduces you to the Common Services and the Common Services Administration Tool. The following part then provides you with guidance on how to input your data as complete your tasks in the Common Services Administration Tool in the role of evidence provider.
Introduction to the Common Services
- Introduction to the Common Services
- What is the Common Services Administration Tool?
- Who needs access to the tool?
- What user roles are in the tool?
- What do the statuses of the assets mean?
What do I need to do in the Common Services as an evidence provider?
- What do I need to do in the Common Services as an evidence provider?
- Checklist: Do I need to connect as an evidence provider to the OOTS?
- Create your evidence type
- Link your evidence type to a requirement
- Create your evidence provider
- Link your evidence provider to an evidence type
Introduction to the Common Services
The Common Services support the exchange of evidences between evidence providers and evidence requesters. These services are composed of three independent modules that have access to all information required to enable evidence exchange.
The three modules aim to answer the following questions:
- Evidence broker - What evidence to request?
- Data Service Directory - Who to send the evidence to?
- Semantic repository - Which semantic agreement should I respect?
Watch the video explaining the Common services
The first part of the guidelines introduces you to the Common Services and the Common Services Administration Tool. The following part then provides you with guidance on how to input your data as complete your tasks in the Common Services Administration Tool in the role of evidence provider.
You can read more about the Common Services by clicking on the link to the relevant Technical Design Documents below:
What is the Common Services Administration Tool?
The Common Services Administration Tool is the user interface to the Common Services. You will be able to manage your Member State procedures, procedural requirements, evidence types, evidence providers and data services through the application.
You can access the production version of the tool here:
Who needs access to the tool?
You will need access to the Common Services Administration Tool if you are:
- User manager (SDG national coordinator) go through an identity checking process so they can manage access to the Common Services Administration Tool for users in their respective Member State
- MS member(s) of the evidence mapping subgroup support competent authorities in the evidence mapping process and help them access the tools and locate online resources
- Competent authorities responsible for requesting evidence in online procedures
- Competent authorities responsible for providing evidence in online procedures (responding to evidence requests)
- Technical architect who can provide input on the more technical data required in the Common Services
Access to the Common Services Administration Tool is granted by the National Coordinator of each Member State. If you have any issues related to your access, or would like to request access to the tool, please contact your SDG National Coordinator.
What user roles are in the tool?
There are four main user roles in the Common Services:
- MS Editors (EB/DSD) are representatives of an organisation authorised to manage EB/DSD data on its behalf. Editors can manage data in Draft status and request reviews of data by the Administrators.
- MS Administrators (EB/DSD) have the same permissions as editors but can also publish, archive and delete data.
- Observers have read-only privileges.
- User Managers are responsible for assigning roles. MS User Managers are responsible for the management of OOTS users in their Member States. The EC User Manager is responsible for the management of OOTS users.
If you have questions or need support related to your user role in the Common Services, you can contact your national coordinator who will be able to provide you with access via the user management application. You can find the detailed guidance for this procedure on the OOTS Service Desk: Common Services Admin UI access management procedure
What do the statuses of the assets mean?
Each asset in the Common Services Administration Tool can be saved as one of the four main statuses. The status of an asset may impact what actions you can take. An asset at any given time can be in one of the four main statuses:
Assets include Member State procedures, evidence types and evidence providers that have been input into the Common Services.
- Draft means it is not published and depending on the role (MS Editor/ MS Administrator) can be submitted for review/published/edited/deleted/linked with other entities.
- In review means it is frozen for reviewing purposes and depending on the role (MS Editor/ MS Administrator ) can be published/ set back to draft.
- Published means the asset it is published and can be set back to draft/ archived.
- Archived means that the asset is inactive and can be set back to draft/ deleted.
What do I need to do in the Common Services as an evidence provider?
This section covers the tasks that evidence providers may perform in the Common Services Administration Tool.
First, before completing any tasks in the tool, evidence providers should:
1) Understand two key concepts:
- Evidence Types: a category of structured or unstructured evidence with a common purpose or content.
- Evidence Providers: a Competent Authority that lawfully issues evidence falling within scope of Article 14(2) of Regulation (EU) 2018/1724.
Member States should try and identify evidence types and evidence providers for every procedural requirement listed in the Common Services. If a citizen or business tries to complete a procedure in another country and no evidence type has been defined for the procedural requirement in your Member State, they will not be able to retrieve the evidence through the OOTS.
2) Determine if they need to connect to the OOTS by following the checklist provided in the next section "Do I need to connect as an evidence provider to the OOTS?"
Checklist: Do I need to connect as an evidence provider to the OOTS?
Article 14(2) of the SDGR provides the legal basis for connecting as an evidence provider to the OOTS: Where competent authorities lawfully issue, in their own Member State and in an electronic format that allows automated exchange, evidence that is relevant for the online procedures referred to in paragraph 1, they shall also make such evidence available to requesting competent authorities from other Member States in an electronic format that allows automated exchange.
If you do need to connect to the OOTS as an evidence provider, you will need to follow the steps below:
Create your evidence type
Evidence types may be exchanged as either structured or un-structured evidences. In OOTS, structured evidence is (in digital format) based on a data model that is machine-readable. Non-structured evidence is considered as evidence stored in a document format, like PDF, and is human readable. Evidence itself must be issued in one of three formats:
- Evidence that is in a human readable format (e.g., PDF);
- Structured evidence that complies with an OOTS data model relevant for the evidence type; or
- Structured evidence that does not comply with an OOTS data model must be accompanied by a human-readable version of the evidence (e.g., a PDF) to ensure the receiving competent authority can read the evidence.
- Adding the general information of your evidence type in English helps to facilitate understanding amongst the Member States using the Common Services Administration Tool.
- Describe the evidence type and refer to any legal frameworks that govern the definition of that evidence type.
- Adding the general information of your evidence type in other most relevant languages is important because it enables the evidence type to be displayed in the right language to citizens and businesses using the OOTS.
- Evidence types may be the same across the whole country, a birth certificate for example.
-
Evidence types may also be specific to a region or even a municipality. - Different jurisdictions may use different evidence types.
- Different regions may map different evidence types to the same procedural requirement.
- In situations where different regions provide different evidence types, the user will have to choose between the jurisdictions to identify the right evidence type to request.
Editors can:
- Save evidence types as a draft
- Submit the evidence type for review by an administrator
Administrators can:
- Save the evidence type as a draft
- Submit the evidence type for review by an administrator
- Publish the evidence type
Member States are encouraged to add the evidence types in English language and in few characters as possible, providing enough information to determine what the file is: [Document Name], e.g. Birth Certificate.
Please also note that it is unnecessary to differentiate the document name per Member States. If for example the official document name is " Birth Certificate", it can be used as an evidence type for all the Member States.
What to avoid:
- Adding Member State initials (e.g., "Birth Certificate_AT");
- Identifying the evidence as "proof" (e.g., "Proof of Birth"), which is already part of the requirements (being Proof of Birth, Proof of Marriage, etc.)
Once the evidence type is correctly added, requirements should be linked to it.
Link your evidence type to a requirement
- Check the description of the requirement that you would like to link an evidence type to, before performing the linking.
- Ensure the evidence type can meet all the minimum information described in the procedural requirement so the requesting competent authority has all the information they need to process the procedure on behalf of the user.
- It is OK for your evidence type to contain more information than what is requested.
Requirements are linked to evidence type lists, not directly to evidence types.
- Provide a name of your evidence type list that helps it to be easily distinguishable from the other lists.
- Evidence type lists may contain one or more evidence types. You can combine different evidence types in a list if it is necessary to meet all the minimum information in the relevant procedural requirement.
- You can also create more than one evidence type list and map it to the same procedural requirement. For example, proof of university diploma could be linked to three different evidence type lists. One for Bachelor, one for Masters and one for PhD diplomas.
- Now you have successfully linked your evidence type to a requirement, you can view the linking by clicking on the "Evidence type(s) linked" tab.
- Once published, your evidence type will be live in the OOTS. If you don’t publish your evidence type and a portal requests the evidence type for your country for a requirement, the user will receive a message that the evidence type is not defined, and they won’t be able to proceed. Only published evidence types appear in queries to the Common Services.
- For the whole evidence type to be published, it must be linked to a published evidence provider in order to be exchanged via the OOTS.
- Once published, the evidence type metadata becomes publicly accessible in the Semantic Repository. The Semantic Repository URIs contain machine-readable information (XML, JSON) about the asset metadata, including name, description, identifier, publisher, and available languages.
Create your evidence provider
- Provide the legal name of the evidence provider.
- Provide a description to help end-users to select between providers.
- The identifier scheme is up to each Member State to decide.
- The identifier value specifically identifies the evidence provider in your Member State and allows your access point to route the evidence request message to the right provider.
- The Access service refers to the national eDelivery access point the evidence provider is connected to.
- Adding the official address of the evidence provider to make it easier for end users to verify the authority.
- Add the name of your evidence provider in relevant languages so that it can be displayed in the right language for end users when they use the OOTS.
- You may have multiple evidence providers that provide the same evidence type in your country.
- For example, university diplomas may be held in education databases specific to region in country.
- To ensure the user can help the system identify the right evidence provider, define the jurisdiction for your evidence providers.
Editors can:
- Save evidence providers as a draft.
- Submit the evidence providers for review by an administrator.
Administrators can:
- Save evidence providers as a draft.
- Submit the evidence providers for review by an administrator.
- Publish evidence providers.
Link your evidence provider to an evidence type
- Select the evidence provider that you want to link to an evidence type
- Select the evidence type that you want to link the evidence provider to
- Metadata is the information that links an evidence type to an evidence provider.
- This metadata may be different for the same evidence type. For example, one university may provide university diplomas in one format (PDF) and the other may provide the same evidence in a different format (XML and PDF).
- If multiple providers provide the same evidence type with the same values for the metadata, you can reuse existing metadata.
- The minimum level of assurance refers to the minimum level of assurance of the eID that users need to have to authenticate to request evidence from the evidence provider.
- Art 15.2 (e) of the Implementing Regulation states that "where structured evidence does not comply with the OOTS data model relevant for the evidence type concerned, a human-readable version of the evidence."
- If you want to add a distribution format like XML, you will need to add a PDF distribution too. In future data models for all structured evidences will be included in the semantic repository.
- If the jurisdiction level is not national. You can add a jurisdiction context. For example, you may need to tell users to select the municipality where they were born to get their birth certificate, rather than selecting the municipality where they live now.
- When your evidence provider and your evidence type are published, you are ready to exchange evidence through the OOTS.