Skip to content

E-Signature Technical Reference

Overview

The e-signature configuration in a protocol defines whether tasks require electronic signatures and what reasons readers can select when signing. E-signatures are available when the Validated Instance module is enabled and provide secure, legally binding authentication of task completion. This satisfies regulatory requirements for clinical trials and FDA-regulated studies.

This technical reference provides detailed specifications for configuring e-signature requirements in protocol JSON.

Basic E-Signature Configuration

The esignature_config property is an optional object at the root level of the protocol JSON. When present and required is set to true, all tasks created with this protocol will require electronic signatures upon completion.

Simple E-Signature Configuration 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "form": {
    "title": "Tumor Assessment",
    "description": "RECIST 1.1 tumor measurement form",
    "defaults": {},
    "fields": []
  },
  "esignature_config": {
    "required": true,
    "reasons": [
      "Initial read per protocol",
      "Adjudication read",
      "Quality assurance review"
    ]
  }
}

E-Signature Properties

Property Description Value Required
required Whether tasks using this protocol require electronic signatures. When true, users must e-sign the task to complete it. When false, tasks can be completed without e-signature. Boolean (true or false) yes
reasons Array of signature reasons that users can select from when signing a task. The first reason in the array is shown first in the UI and should be used as the default/most common reason. Array of strings yes (if required is true)

Signature Reasons

The reasons array defines the list of reasons users can select when applying their e-signature.

Reason Ordering

The first reason in the array is shown first in the e-signature UI and should be the most commonly used reason.

When users open the e-signature dialog, the reasons appear in the same order as defined in the protocol. The first reason is typically pre-selected or appears at the top of the list, making it the easiest to select.

Best Practice: Place the most frequently used signature reason first in the array.

Example Reason Configurations

Clinical Trial Protocol Adjudication:

1
2
3
4
5
6
7
"reasons": [
  "Initial read per protocol",
  "Consensus read",
  "Adjudication read",
  "Quality assurance review",
  "Protocol deviation review"
]

Radiology Quality Control:

1
2
3
4
5
6
"reasons": [
  "Primary interpretation",
  "Secondary review",
  "Quality control check",
  "Teaching file curation"
]

Image Quality Assessment:

1
2
3
4
5
"reasons": [
  "Initial quality check",
  "Post-processing verification",
  "Study coordinator review"
]

Reason Naming Guidelines

Be Specific: Use clear, unambiguous reason text that describes the purpose of the signature

  • ✅ Good: "Initial read per protocol"
  • ❌ Avoid: "Read"

Use Consistent Terminology: Standardize reason text across protocols within your organization

  • Consistent: "Quality assurance review" used across all protocols
  • Inconsistent: "QA review", "Quality check", "QC review" used interchangeably

Align with Study Procedures: Reasons should match the terminology in your study documentation

  • If your protocol document refers to "consensus reads", use "Consensus read" as the reason

Keep Concise: Reasons should be brief but descriptive (typically 2-6 words)

  • ✅ Good: "Adjudication read"
  • ❌ Avoid: "This signature is being applied because I am performing an adjudication read as part of the study protocol"

Configuration Examples

Required E-Signature with Multiple Reasons

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "form": {
    "title": "Tumor Assessment - RECIST 1.1",
    "description": "Target lesion measurement and response assessment",
    "defaults": {
      "target_lesion_present": false
    },
    "fields": [
      {
        "key": "target_lesion_present",
        "type": "radio",
        "label": "Target Lesion Present",
        "options": [
          { "label": "Yes", "value": true },
          { "label": "No", "value": false }
        ]
      }
    ]
  },
  "esignature_config": {
    "required": true,
    "reasons": [
      "Initial read per protocol",
      "Adjudication read",
      "Quality assurance review",
      "Protocol deviation review"
    ]
  }
}

No E-Signature Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "form": {
    "title": "Data Quality Check",
    "description": "Internal quality control form",
    "defaults": {},
    "fields": []
  },
  "esignature_config": null
  }
}

Note: If e-signatures are not required, you can set the esignature property to null.

E-Signature Requirements

Validated Instance Module

E-signatures are only available when the Validated Instance module is enabled on your Flywheel instance. If Validated Instance is not enabled, the esignature configuration will be ignored and tasks will not require signatures.

Multi-Factor Authentication (MFA)

Users must have multi-factor authentication (MFA) configured on their accounts to complete e-signature tasks.

MFA Enforcement:

  • If a user attempts to submit an e-signature task without MFA configured, the system will block submission
  • Users will be prompted to set up MFA before they can proceed
  • See Multi-Factor Authentication Setup for details

User Permissions

Users must have appropriate permissions to complete tasks:

  • Read/Write permissions on the project containing the task
  • Assigned to the task (or task assigned to a staffing pool they belong to)

E-Signature Data Captured

When a user applies an e-signature, the system captures:

User Identity

  • Full name
  • Email address
  • User identifier (unique ID)
  • Authentication method (MFA verified)

Signature Details

  • Timestamp (precise date and time)
  • Selected signature reason
  • Protocol version

Signed Content

  • Task identifier
  • Form responses
  • Annotations created
  • Container (session/acquisition/file) associated with the task

All e-signature events are recorded in the audit trail when Validated Instance is enabled.

Validation Rules

The protocol validation system checks e-signature configuration:

Required Property Validation

  • required must be a boolean (true or false)
  • Cannot be a string, number, or other type

Valid:

1
2
3
4
"esignature_config": {
  "required": true,
  "reasons": ["Initial read"]
}

Invalid:

1
2
3
4
"esignature_config": {
  "required": "yes",  // Must be boolean, not string
  "reasons": ["Initial read"]
}

Reasons Array Validation

  • reasons must be an array
  • Array must contain at least one string if required is true
  • Each reason must be a non-empty string
  • Reasons should be unique (no duplicates)

Valid:

1
2
3
4
5
6
7
"esignature_config": {
  "required": true,
  "reasons": [
    "Initial read per protocol",
    "Adjudication read"
  ]
}

Invalid:

1
2
3
4
"esignature_config": {
  "required": true,
  "reasons": []  // Must have at least one reason if required is true
}

Invalid:

1
2
3
4
5
6
7
8
"esignature_config": {
  "required": true,
  "reasons": [
    "Initial read",
    "",  // Empty strings not allowed
    "Adjudication read"
  ]
}

Best Practices

Design for Common Workflows

Order reasons from most to least frequently used:

1
2
3
4
5
"reasons": [
  "Initial read per protocol",      // Most common
  "Quality assurance review",       // Moderately common
  "Protocol deviation review"       // Least common
]

Use Standard Terminology

Adopt consistent reason naming across all protocols in your organization:

  • "Initial read per protocol" (not "First read", "Primary read", "Initial assessment")
  • "Adjudication read" (not "Adjudication", "Third read", "Tie-breaker")
  • "Quality assurance review" (not "QA", "Quality check", "QC review")

Align with Regulatory Requirements

If your study follows specific regulatory frameworks (FDA 21 CFR Part 11, GxP), ensure reason terminology matches your regulatory documentation.

Document Reason Meanings

In your study procedures documentation, clearly define what each signature reason means:

  • When should "Initial read per protocol" be used?
  • What conditions require an "Adjudication read"?
  • Who is authorized to perform "Quality assurance review"?

Limit Number of Reasons

Keep the number of reasons manageable (typically 3-6 reasons):

  • Too many reasons create confusion and increase selection errors
  • Too few reasons may not capture necessary context
  • Consider whether different task types need different protocols with different reason lists

Test Before Publishing

Before publishing a protocol with e-signature requirements:

  1. Create a test task in a development project
  2. Complete the task and verify the e-signature dialog appears
  3. Confirm all reasons are displayed correctly
  4. Verify reason ordering matches your intent
  5. Check that the first reason is the most appropriate default

Troubleshooting

E-Signature Dialog Does Not Appear

Possible causes:

  • Validated Instance module is not enabled
  • esigesignature_config.required is set to false or omitted
  • Protocol JSON has validation errors

Solutions:

  • Verify Validated Instance is enabled on your Flywheel instance
  • Check the protocol JSON: ensure "required": true
  • Validate the protocol JSON syntax

User Cannot Submit Task (MFA Required Error)

Possible causes:

  • User has not configured multi-factor authentication

Solutions:

Signature Reasons Not Displaying as Expected

Possible causes:

  • reasons array is empty
  • Reasons contain formatting issues (extra whitespace, special characters)

Solutions:

  • Verify reasons array has at least one non-empty string
  • Remove extra whitespace from reason text
  • Check for special characters that may not display correctly