Legacy Task Forms to Task Manager Protocol JSON - Conversion Specification

This document provides a detailed technical specification for converting Legacy Task forms (OHIF-based) to Task Manager protocol JSON format.

Protocol JSON File Structure

Task Manager protocol JSON files contain exactly two top-level keys:

1
2
3
4
5
6
7
8
9

{
  "form": {
    "title": "string",
    "description": "string",
    "defaults": {},
    "fields": []
  },
  "esignature_config": null
}

This is the complete structure for a protocol JSON file.

Additional metadata (label, group_id, task_type, protocol_config, completion_tags, notes) is provided through the UI or API when uploading the protocol, not in the JSON file itself.

Form Schema Differences

Legacy Form Structure

Legacy forms are wrapped in a studyForm object with a components array:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "studyForm": {
    "components": [
      {
        "key": "field_name",
        "type": "radio",
        "label": "Question text",
        "validate": {
          "required": true
        },
        "values": [
          {"value": "option1", "label": "Option 1"}
        ],
        "conditional": {
          "json": {
            "==": [{"var": "other_field"}, "value"]
          }
        }
      }
    ]
  }
}

Task Manager Form Structure

Task Manager forms have a flatter structure with a fields array:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "title": "Form Title",
  "description": "Form description",
  "defaults": {
    "field_name": ""
  },
  "fields": [
    {
      "key": "field_name",
      "type": "radio",
      "label": "Question text",
      "requiredWhenVisible": true,
      "options": [
        {"value": "option1", "label": "Option 1"}
      ],
      "visible": [
        {"===": [{"var": "other_field"}, "value"]}
      ]
    }
  ]
}

Conversion Rules

Structure Transformation

Property Mappings

Field Type Conversions

JsonLogic Operator Conversions

JsonLogic Negation Handling

Legacy forms often use != for negation. Task Manager prefers positive value checks with the in operator.

Legacy pattern:

1
2
3

{
  "!=": [{"var": "confidence"}, "CS3"]
}

Task Manager pattern:

1
2
3

{
  "in": [{"var": "confidence"}, ["CS1", "CS2"]]
}

List all valid positive values explicitly.

OHIF-Specific Properties (Remove from Form)

These properties are specific to the OHIF viewer and should be removed from field options:

• requireMeasurements - Remove from options
• measurementTools - Remove from options
• containerType - Remove from form
• contourVisibility - Remove from form

Conversion Process

Step 1: Extract Form Components

From your Legacy form, extract the components array:

1
2
3
4
5

{
  "studyForm": {
    "components": [...]
  }
}

Step 2: Create Title and Description

Add a title and description for the form (these don't exist in Legacy forms):

1
2
3
4

{
  "title": "Descriptive Form Title",
  "description": "Brief description of the form's purpose"
}

Step 3: Create Defaults Object

Build a defaults object with an entry for every field that accepts user input. Use appropriate empty values based on field type:

1
2
3
4
5
6
7
8

{
  "defaults": {
    "text_field": "",
    "checkbox_field": [],
    "radio_field": "",
    "select_field": ""
  }
}

Skip display-only fields like paragraph and instruction - they don't need defaults.

Step 4: Transform Each Component

For each component in the Legacy form:

1. Rename values to options
2. Convert validate.required or required to requiredWhenVisible
3. Unwrap conditional.json to visible
4. Change field type if needed (selectboxes → checkbox, textfield → text, textarea → text-area)
5. Convert == to === in all JsonLogic expressions
6. Convert != to positive in checks
7. Remove OHIF properties (requireMeasurements, measurementTools, containerType)

Step 5: Wrap in Protocol Structure

Wrap the converted form in the protocol JSON structure:

1
2
3
4
5
6
7
8
9

{
  "form": {
    "title": "...",
    "description": "...",
    "defaults": {...},
    "fields": [...]
  },
  "esignature_config": null
}

Step 6: Add E-signature Configuration (If Needed)

If your form requires e-signatures, replace null with an e-signature configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "form": {...},
  "esignature_config": {
    "required": true,
    "reasons": [
      "Initial assessment",
      "Quality assurance review",
      "Final approval"
    ]
  }
}

Complete Conversion Example

This example uses a real diabetic retinopathy grading form for fundus images.

Legacy Form (Before)

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

{
  "form": {
    "studyForm": {
      "components": [
        {
          "label": "COLOR FUNDUS - Is this image gradable for at least 1 lesion?",
          "key": "is_gradable",
          "required": true,
          "type": "radio",
          "values": [
            {"value": "yes", "label": "Yes"},
            {"value": "possible", "label": "Possible"},
            {"value": "no", "label": "No"}
          ]
        },
        {
          "label": "Presence of MA?",
          "key": "pres_MA",
          "conditional": {
            "json": {
              "or": [
                {"==": [{"var": "is_gradable"}, "yes"]},
                {"==": [{"var": "is_gradable"}, "possible"]}
              ]
            }
          },
          "required": true,
          "type": "radio",
          "values": [
            {
              "value": "yes",
              "label": "Yes",
              "requireMeasurements": ["MA"],
              "measurementTools": ["CircleRoi"]
            },
            {
              "value": "possible",
              "label": "Possible",
              "requireMeasurements": ["MA"],
              "measurementTools": ["FreehandRoi"]
            },
            {"value": "no", "label": "No"},
            {"value": "ungradable", "label": "Ungradable"}
          ]
        },
        {
          "label": "Completed drawing MA?",
          "key": "pres_MA_contour",
          "conditional": {
            "json": {
              "or": [
                {"==": [{"var": "pres_MA"}, "yes"]},
                {"==": [{"var": "pres_MA"}, "possible"]}
              ]
            }
          },
          "required": true,
          "type": "radio",
          "values": [
            {"value": "yes", "label": "Yes"},
            {"value": "no", "label": "No"}
          ]
        },
        {
          "label": "Additional Notes",
          "key": "notes",
          "required": false,
          "type": "text"
        }
      ]
    }
  }
}

Task Manager Protocol JSON (After)

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

{
  "form": {
    "title": "Diabetic Retinopathy Grading - Fundus",
    "description": "Form for grading diabetic retinopathy lesions in color fundus images",
    "defaults": {
      "is_gradable": "",
      "pres_MA": "",
      "pres_MA_contour": "",
      "notes": ""
    },
    "fields": [
      {
        "label": "COLOR FUNDUS - Is this image gradable for at least 1 lesion?",
        "key": "is_gradable",
        "requiredWhenVisible": true,
        "type": "radio",
        "options": [
          {"value": "yes", "label": "Yes"},
          {"value": "possible", "label": "Possible"},
          {"value": "no", "label": "No"}
        ]
      },
      {
        "label": "Presence of MA?",
        "key": "pres_MA",
        "visible": [
          {
            "or": [
              {"===": [{"var": "is_gradable"}, "yes"]},
              {"===": [{"var": "is_gradable"}, "possible"]}
            ]
          }
        ],
        "requiredWhenVisible": true,
        "type": "radio",
        "options": [
          {"value": "yes", "label": "Yes"},
          {"value": "possible", "label": "Possible"},
          {"value": "no", "label": "No"},
          {"value": "ungradable", "label": "Ungradable"}
        ]
      },
      {
        "label": "Completed drawing MA?",
        "key": "pres_MA_contour",
        "visible": [
          {
            "or": [
              {"===": [{"var": "pres_MA"}, "yes"]},
              {"===": [{"var": "pres_MA"}, "possible"]}
            ]
          }
        ],
        "requiredWhenVisible": true,
        "type": "radio",
        "options": [
          {"value": "yes", "label": "Yes"},
          {"value": "no", "label": "No"}
        ]
      },
      {
        "label": "Additional Notes",
        "key": "notes",
        "type": "text"
      }
    ]
  },
  "esignature_config": null
}

Key Changes Highlighted

1. Wrapped in form object with title, description, defaults, fields
2. components → fields
3. values → options
4. validate.required → requiredWhenVisible
5. conditional.json → visible (unwrapped)
6. selectboxes → checkbox
7. textarea → text-area
8. == → === in JsonLogic
9. != → in with positive value list in JsonLogic
10. Removed required: false (not needed when field is optional)

Conversion Checklist

• [ ] Extract Legacy form components array
• [ ] Create form title and description
• [ ] Create defaults object with all input field keys
• [ ] Rename components to fields
• [ ] Rename values to options for all select/radio/checkbox fields
• [ ] Convert validate.required and required to requiredWhenVisible
• [ ] Unwrap conditional.json to visible
• [ ] Convert field types: selectboxes → checkbox, textfield → text, textarea → text-area
• [ ] Replace all == with === in JsonLogic
• [ ] Convert all != to positive in checks in JsonLogic
• [ ] Remove OHIF properties (requireMeasurements, measurementTools, containerType)
• [ ] Wrap form in protocol structure with form and esignature_config keys
• [ ] Add e-signature configuration if needed
• [ ] Validate JSON syntax
• [ ] Test by pasting into Task Manager protocol editor

Common Issues

Issue 1: Forgot to Create Defaults

Problem: Missing defaults object

Solution: Add a defaults object with an entry for every input field with appropriate empty value:

1
2
3
4
5
6
7

{
  "defaults": {
    "text_field": "",
    "checkbox_field": [],
    "radio_field": ""
  }
}

Issue 2: Didn't Unwrap Conditional

Problem: Left conditional.json structure intact

Solution: Unwrap to visible:

1
2
3
4
5
6
7
8
9

// Wrong
"conditional": {
  "json": {"===": [{"var": "field"}, "value"]}
}

// Correct
"visible": [
  {"===": [{"var": "field"}, "value"]}
]

Issue 3: Didn't Convert Field Types

Problem: Used selectboxes, textfield, or textarea types

Solution: Convert to Task Manager types:

• selectboxes → checkbox
• textfield → text
• textarea → text-area

Issue 4: Didn't Convert JsonLogic Operators

Problem: Used == or != in JsonLogic

Solution:

• Replace == with ===
• Replace != with positive in check listing all valid values

Issue 5: Left OHIF Properties in Form

Problem: Fields still have requireMeasurements or measurementTools

Solution: Remove these properties from the form JSON. Configure measurement tools at the project level instead.

Validation Rules

JsonLogic validation rules use the same syntax in both systems (with === for equality):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "key": "score",
  "type": "text",
  "label": "Score",
  "validation": [
    {
      "logic": {
        "and": [
          {">": [{"var": "score"}, 0]},
          {"<": [{"var": "score"}, 100]}
        ]
      },
      "message": "Score must be between 0 and 100"
    }
  ]
}

Best Practices

Form Design

1. Descriptive Titles: Use clear form titles that describe the assessment
2. Use Affirmative Logic: Prefer positive in checks over negation
3. Provide Helper Text: Use helperText to guide users
4. Validate Early: Use validation rules to catch errors before submission
5. Test Conditional Logic: Verify all visible and requiredWhenVisible rules work correctly

Conversion Process

1. Validate Source: Ensure Legacy form JSON is valid before starting
2. Create Defaults First: Build the complete defaults object before converting fields
3. Convert One Field at a Time: Systematic field-by-field conversion reduces errors
4. Test Incrementally: Test form after converting each major section
5. Keep Backups: Save both Legacy and converted versions

Conclusion

Converting Legacy Task forms to Task Manager protocol JSON requires systematic transformation of structure, properties, and operators.

Key Transformation Steps:

1. Add title, description, and defaults (not present in Legacy forms)
2. Rename components → fields, values → options
3. Convert validate.required/required → requiredWhenVisible
4. Unwrap conditional.json → visible
5. Convert field types (selectboxes, textfield, textarea)
6. Update JsonLogic operators (== → ===, != → in)
7. Remove OHIF-specific properties
8. Wrap in protocol JSON structure

Migration Effort:

• Medium Complexity: Systematic transformations required
• Checklist-Driven: Follow conversion checklist to ensure completeness
• Testable: Each transformation can be verified incrementally

Related Documentation

• Protocol Form Technical Reference - Complete technical reference for protocol form schema, field types, validation rules, and JSON structure
• E-signature Configuration Reference - E-signature configuration options and examples
• Legacy Form Conversion Example - Detailed walkthrough of a diabetic retinopathy form conversion with before/after comparison