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:

Attribute	Description	Notes
name	Name of the field in the request, e.g. position	Lowercase and snakecase is recommended
type	The type of the field. See below for more information	Supported types: label, text, string, markdown, phone, date
label	Label to display above the data entry field, e.g. Position
placeholder	Placeholder text placed within the data entry field to guide the user, e.g. enter your job title	Not supported for types: label, phone, markdown
defaultValue	The auto-populated value for the data entry field	Not supported for types: label
preferredCountries	Country codes that will appear at the top of phone input fields	Only supported for types: phone
country	The default country displayed on the phone input field, e.g. +44 UK	Only supported for types: phone
validation/required	Is the field required or not	Not supported for types: label
validation/minimum	Minimum character length for data entry	Only supported for types: text, string, markdown, date
validation/maximum	Minimum character length for data entry	Only supported for types: text, string, markdown, date
validation/identifier	Ensure this field is used for the request ID/Code required by FAIR	Only 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

Custom DAR Forms

Creating a Custom DAR Form

DAR Field Attributes

DAR Field Types

Assigning a DAR Form to a Workflow

Was this article helpful?