PID Registration

Introduction

This document describes how MDM uses the da|ra API to register Persistent Identifiers (PIDs) for variables. The following questions are answered:

• How can PIDs be registered via MDM?
• Which metadata does MDM use for the registration process?
• What happens if errors occur during registration?
• What happens if the variables in this specific version have already been registered?
• Where can I check if the PID registration service is available?
• How do I know if the registration has been successful?

How can PIDs be registered via MDM?

PIDs can be registered on a per-project basis for each variable contained in the project via the release process. For projects with variables, the selection option “Registration of Persistent Identifiers (PIDs) for the variables of the data package” is available in the release dialog (see screenshot).

If the option is activated, the variables are registered collectively following the release process. The PIDs are transferred to the variable data records in MDM if the registration is successful. The registration process can take up to an hour. The user is informed about this fact by a toast notification. The message reads: “The release process has been initiated. The data package will be available in a few minutes. The registration of the PIDs for variables is carried out in the background and can take up to an hour.”

Which metadata does MDM use for the registration process?

Field	Value	Example
studyDOI	data package DOI	"10.17889/DZHW:gsl2008:1.0.0"
variableName	variable name	"bstu07b_g1"
variableLabel	variable label	"2nd entry: subject"
pidProposal	21.T11998/dzwh:[dapid]_[varname]:[dapid_version]	"21.T11998/dzhw:gsl2008_bstu07b_g1:1.0.0"
landingPage	URL variables detail page incl. version parameters	"https://metadata.fdz.dzhw.eu/en/variables/var-nac2018-ds1-adbi01?page=1&size=10&type=questions&version=2.0.0"
resourceType	always "variable"	"variable"
title	[variable name]: [variable label]	"bstu07b_g1: 2nd entry: subject"
creators.firstname	first name of creator listed in projectContributors (reference every contributor in single creator object)	"John"
creators.lastName	last name of creator listed in projectContributors (reference every contributor in single creator object)	"Doe"
publisher	always "FDZ-DZHW"	"FDZ-DZHW"
publicationDate	publication date of current version of data package	"2021-04-09"
availability	If a accessway is defined (cuf, download, remote, onsite) the type should be "delivery" else "not available"	"delivery"

Here you can see an example JSON object that could be used for registering PIDs:

{
      "studyDOI": "10.17889/DZHW:gsl2008:1.0.0",
      "variableName": "bstu07b_g1",
      "variableLabel": "2nd entry: subject",
      "pidProposal": "21.T11998/dzhw:gsl2008_bstu07b_g1:1.0.0",
      "landingPage": "https://metadata.fdz.dzhw.eu/en/variables/var-gsl2008-ds1-bstu07b_g1?version=1.0.0",
      "resourceType": "Variable",
      "title": "bstu07b_g1: 2nd entry: subject",
      "creators": [
        {
          "firstName": "John",
          "lastName": "Doe"
        },
        {
          "firstName": "Jane",
          "lastName": "Doe"
        }
      ],
      "publisher": "FDZ-DZHW",
      "publicationDate": "2021-04-09",
      "availability": "delivery"
    }

What happens if errors occur during registration?

In the event of errors in the registration process, an email notification is sent to the user who made the release and to the admins. This email contains a description of the error that has occurred. No PIDs are saved in the system. The project will still get released.

How can variables be registered for already released projects?

To prevent projects that have already been released from having to be published again in order to register PIDs, admins can view the PID registration status of the project via the status page of the project cockpit (see screenshot). This is only displayed if the project is currently released.

The PIDs can be registered using the button in the PID registration status display. This process can also be used if errors occurred during a previous registration and the registration is to be carried out again.

What happens if the variables in this specific version have already been registered?

If the registration option was activated in the release dialog even though the variables for the specified version have already been registered, the registration process is skipped. The release continues as usual. The user is informed about this by a toast notification. The message reads: “PIDs are already registered for the variables in this version, no new registration will be made. The data package is released as usual, no further action is required.”

Where can I check if the PID registration service is available?

The status of the PID registration service can be checked in the administration area under “Availability of external services” under “Dara PID Registration”. If the status is “Up”, the service is available (see screenshot).

If the service is not available and a user still wants to perform a release, a warning message is displayed before the release dialog informing the user that no PIDs can be registered during the release (see screenshot). The user needs to confirm whether they want to continue the release process or not. The release process can then be aborted or continued without PID registration.

How do I know if the registration has been successful?

If the registration has been completed successfully the PIDs are saved to the variables objects in MDM. If one variable of the data package has a PID available on MDM you can be sure that all variables of this data package have been registered successfully.