Custom DAR Forms

DAR forms allow information to be supplied during the course of requesting access to a dataset. FAIR Data Services provides a default DAR form template however data owners can create custom DAR forms that can then be assigned to their DAR workflow.

Currently the creation and assignment of DAR forms is only available via the API.

Creating a Custom DAR Form

DAR forms are created in the JSON format. The JSON is composed of two mandatory sections:

  • project: information about the requesting user's research project and why they require access to the dataset
  • about: information about the requesting user, e.g. affiliation
{
"fields": {
       "project": \[
           {
                "name": "project\_name",
                "type": "string",
                "label": "Project name",
                "defaultValue": "",
                "placeholder": "Add the name of the project and project ID if applicable",
                "validation": {
                    "required": true,
                    "maximum": "250"
                }
            }
            ...more DAR project fields here...
        \],
        "about": \[   
           {
                "name": "position",
                "type": "string",
                "label": "Position",
                "defaultValue": "",
                "placeholder": "Add your position in the project",
                "validation": {
                    "required": true,
                    "maximum": "256"
                }
            }
            ...more DAR about fields here...
        \]
    }
}

DAR Field Attributes

Each DAR field can contain a number of attributes as detailed below:

AttributeDescriptionNotes
nameName of the field in the request, e.g. positionLowercase and snakecase is recommended
typeThe type of the field. See below for more informationSupported types: label, text, string, markdown, phone, date
labelLabel to display above the data entry field, e.g. Position
placeholderPlaceholder text placed within the data entry field to guide the user, e.g. enter your job titleNot supported for types: label, phone, markdown
defaultValueThe auto-populated value for the data entry fieldNot supported for types: label
preferredCountriesCountry codes that will appear at the top of phone input fieldsOnly supported for types: phone
countryThe default country displayed on the phone input field, e.g. +44 UKOnly supported for types: phone
validation/requiredIs the field required or notNot supported for types: label
validation/minimumMinimum character length for data entryOnly supported for types: text, string, markdown, date
validation/maximumMinimum character length for data entryOnly supported for types: text, string, markdown, date
validation/identifierEnsure this field is used for the request ID/Code required by FAIROnly supported for types: code

Note: all custom DAR forms must collect the Request Name and Request ID/Code, where the latter can be specified using 'identifier: true'. For example, all DAR forms could include the following in either 'project' or 'about' sections:


{
                "name": "code",
                "type": "string",
                "label": "ID",
                "defaultValue": "",
                "placeholder": "Enter a unique ID or leave blank and we will allocate one for you",
                "validation": {
                    "maximum": "256",
                    "identifier": true
                }
            },
            {
                "name": "name",
                "type": "string",
                "label": "Request name",
                "defaultValue": "",
                "placeholder": "Name this request",
                "validation": {
                    "required": true,
                    "maximum": "250"
                }
            }

DAR Field Types

The following types are supported for use with the 'type' field: * date: Renders a date input * label: Renders a markdown built-in label/paragraph displayed at the top of the DAR form. * markdown: Multiline text entry with support for formatting and links * phone: Renders a telephone data entry field * string: single line text entry * text: multiline text entry

Assigning a DAR Form to a Workflow

A 1:1 mapping exists between a DAR form and a DAR Workflow, with many datasets being tied to a single DAR workflow. Therefore assigning a DAR form to a workflow, updates the DAR forms for all datasets associated with the workflow.

Assigning a DAR form to the DAR Workflow is currently only available via the API.

Users with the appropriate permissions (i.e. workflow.update) can issue an PUT request to the /workflows/{key} endpoint, where {key} is the key of the workflow, e.g. 'basic_access_request' and the DAR Form JSON present in the request body.

curl --location --request PUT \\
'https://fair.<customer>.aridhia.io/api/workflows/basic\_access\_request' \\
--header 'Content-Type: application/json' \\
--data-raw '**dar\_json\_here**'
</customer>
Updated on September 26, 2024

Was this article helpful?