Skip to content

Legacy Task Form Conversion - Complete Example

This page demonstrates a complete conversion of a Legacy Task form to Task Manager protocol JSON format using a real diabetic retinopathy grading form.

Overview

This example shows how to convert a Legacy Task form used for grading color fundus images for diabetic retinopathy lesions. The form includes sequential assessment of multiple lesion types with conditional visibility and image annotation requirements.

The conversion produces a protocol JSON file with form and esignature_config keys that can be pasted or uploaded into the Task Manager protocol editor.

Example Source

This example uses a real Legacy Task form from the OHIF viewer repository.

Source: GitLab MR #463 - OHIF Viewer

The form JSON is included in the merge request overview and represents an actual diabetic retinopathy grading workflow used in production.

Before: Legacy Task Form Format

The Legacy form uses OHIF's studyForm structure with a components array. Each component represents a form field with OHIF-specific properties for image annotation.

Legacy Form Structure

  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
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
{
  "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": "Presense 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"
            }
          ]
        }
      ]
    }
  }
}

Legacy Form Key Features

  1. Nested Structure: Form wrapped in form.studyForm.components
  2. Conditional Logic: Uses conditional.json wrapper around JsonLogic
  3. Operator Style: Uses == (double equals) for comparisons
  4. Options Array: Called values instead of options
  5. OHIF Integration: Includes requireMeasurements, measurementTools, and contourVisibility properties
  6. Required Flag: Simple boolean required property

Conversion Process

Step 1: Transform Structure

Convert from OHIF studyForm structure to Task Manager protocol JSON format:

Changes:

  • Remove form.studyForm wrapper
  • Wrap form in protocol structure with form and esignature_config keys
  • Rename components → fields
  • Add title and description to form
  • Add defaults object to form

Step 2: Update Field Properties

For each field, update property names:

Legacy Task Manager
values options
required requiredWhenVisible
conditional.json visible

Step 3: Standardize JsonLogic

Update JsonLogic syntax:

Legacy (loose equality):

1
2
3
{
  "==": [{"var": "is_gradable"}, "yes"]
}

Task Manager (strict equality):

1
2
3
{
  "===": [{"var": "is_gradable"}, "yes"]
}

Step 4: Remove OHIF-Specific Properties

Remove properties that are specific to OHIF viewer:

  • requireMeasurements
  • measurementTools
  • contourVisibility

These will be configured at the project level instead.

Step 5: Create Defaults Object

Build the defaults object with all field keys:

1
2
3
4
5
6
7
8
{
  "defaults": {
    "is_gradable": "",
    "pres_MA": "",
    "pres_MA_contour": "",
    ...
  }
}

After: Task Manager Protocol JSON Format

The converted form is wrapped in a protocol JSON structure with proper field types and JsonLogic validation.

Converted Protocol JSON File Structure

  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
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
{
  "form": {
    "title": "Color Fundus Grading Form",
    "description": "Diabetic retinopathy lesion grading form for color fundus images",
    "defaults": {
    "is_gradable": "",
    "pres_MA": "",
    "pres_MA_contour": "",
    "pres_HMA": "",
    "pres_HMA_contour": "",
    "pres_H": "",
    "pres_H_contour": "",
    "pres_CWS": "",
    "pres_CWS_contour": "",
    "pres_HE": "",
    "pres_HE_contour": "",
    "pres_IRMA": "",
    "pres_IRMA_contour": "",
    "pres_VB": "",
    "pres_VB_contour": "",
    "pres_NVE": "",
    "pres_NVE_contour": "",
    "pres_NVD": "",
    "pres_NVD_contour": "",
    "pres_FPE": "",
    "pres_FPE_contour": "",
    "pres_FPD": "",
    "pres_FPD_contour": "",
    "pres_PRH": "",
    "pres_PRH_contour": "",
    "pres_VH": "",
    "pres_VH_contour": "",
    "pres_FL": "",
    "pres_FL_contour": "",
    "pres_PRP": "",
    "pres_PRP_contour": "",
    "FUNDUS_complete": "",
    "notes": ""
  },
  "fields": [
    {
      "key": "is_gradable",
      "type": "radio",
      "label": "COLOR FUNDUS - Is this image gradable for at least 1 lesion?",
      "requiredWhenVisible": true,
      "options": [
        {
          "value": "yes",
          "label": "Yes"
        },
        {
          "value": "possible",
          "label": "Possible"
        },
        {
          "value": "no",
          "label": "No"
        }
      ]
    },
    {
      "key": "pres_MA",
      "type": "radio",
      "label": "Presense of MA?",
      "requiredWhenVisible": true,
      "visible": [
        {
          "or": [
            {
              "===": [
                {
                  "var": "is_gradable"
                },
                "yes"
              ]
            },
            {
              "===": [
                {
                  "var": "is_gradable"
                },
                "possible"
              ]
            }
          ]
        }
      ],
      "options": [
        {
          "value": "yes",
          "label": "Yes"
        },
        {
          "value": "possible",
          "label": "Possible"
        },
        {
          "value": "no",
          "label": "No"
        },
        {
          "value": "ungradable",
          "label": "Ungradable"
        }
      ]
    },
    {
      "key": "pres_MA_contour",
      "type": "radio",
      "label": "Completed drawing MA?",
      "requiredWhenVisible": true,
      "visible": [
        {
          "or": [
            {
              "===": [
                {
                  "var": "pres_MA"
                },
                "yes"
              ]
            },
            {
              "===": [
                {
                  "var": "pres_MA"
                },
                "possible"
              ]
            }
          ]
        }
      ],
      "options": [
        {
          "value": "yes",
          "label": "Yes"
        },
        {
          "value": "no",
          "label": "No"
        }
      ]
    }
  ]
  },
  "esignature_config": null
}

Task Manager Protocol JSON Key Features

  1. Flat Structure: Direct top-level properties
  2. Clear Naming: fields array, options for choices
  3. Strict JsonLogic: Uses === for equality comparisons
  4. Explicit Defaults: All field keys defined with initial values
  5. Viewer-Agnostic: No viewer-specific properties in form
  6. Conditional Required: Uses requiredWhenVisible for dynamic requirements

Conversion Mapping Table

Top-Level Properties

Legacy Task Manager Protocol JSON Notes
form.studyForm.components form.fields Array of field definitions
Not present form Added: Wrapper for form object
Not present esignature_config Added: E-signature configuration (or null)
Not present form.title Added: Form title
Not present form.description Added: Form description
Not present form.defaults Added: Default values for all fields

Field-Level Properties

Legacy Property Task Manager Property Conversion Notes
label label No change
key key No change
type type No change
required requiredWhenVisible Renamed
values[] options[] Renamed
conditional.json visible[] Unwrapped from .json
requireMeasurements Removed Move to protocol viewer config
measurementTools Removed Move to protocol viewer config
contourVisibility Removed Move to protocol viewer config

JsonLogic Operators

Legacy Operator Task Manager Operator Reason
== === Strict equality for better type safety
!= Positive in check Task Manager prefers positive value checks over negation

Complete Form Comparison

This section provides access to the complete Legacy form and converted Task Manager protocol JSON files. The diabetic retinopathy grading form includes 27 fields covering multiple lesion types (MA, HMA, H, CWS, HE, IRMA, VB, NVE, NVD, FPE, FPD, PRH, VH, FL, PRP) with sequential workflow logic.

Complete JSON Files

Legacy Form (1,644 lines): 15536_form.json - Complete Legacy Task form in OHIF studyForm format

Converted Protocol (1,488 lines): 15536_protocol_task_manager.json - Complete Task Manager protocol JSON

The sections below show the first three fields from each file to illustrate the conversion patterns. Refer to the complete files to see all 27 fields and their conversion.

Legacy Form: Sample Fields

Click to expand sample Legacy form fields (showing 3 of 27 fields) 
 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
{
  "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": "Presense 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"}
          ]
        }
      ]
    }
  }
}
**Note:** The complete form includes 24 more fields following this pattern for all lesion types, plus a notes field. See the full file linked above.

Task Manager Protocol JSON: Sample Fields

Click to expand sample Task Manager protocol fields (showing 3 of 27 fields) 
 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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
{
  "form": {
    "title": "Color Fundus Grading Form",
    "description": "Diabetic retinopathy lesion grading form for color fundus images",
    "defaults": {
    "is_gradable": "",
    "pres_MA": "",
    "pres_MA_contour": "",
    "pres_HMA": "",
    "pres_HMA_contour": "",
    "pres_H": "",
    "pres_H_contour": "",
    "pres_CWS": "",
    "pres_CWS_contour": "",
    "pres_HE": "",
    "pres_HE_contour": "",
    "pres_IRMA": "",
    "pres_IRMA_contour": "",
    "pres_VB": "",
    "pres_VB_contour": "",
    "pres_NVE": "",
    "pres_NVE_contour": "",
    "pres_NVD": "",
    "pres_NVD_contour": "",
    "pres_FPE": "",
    "pres_FPE_contour": "",
    "pres_FPD": "",
    "pres_FPD_contour": "",
    "pres_PRH": "",
    "pres_PRH_contour": "",
    "pres_VH": "",
    "pres_VH_contour": "",
    "pres_FL": "",
    "pres_FL_contour": "",
    "pres_PRP": "",
    "pres_PRP_contour": "",
    "FUNDUS_complete": "",
    "notes": ""
  },
  "fields": [
    {
      "key": "is_gradable",
      "type": "radio",
      "label": "COLOR FUNDUS - Is this image gradable for at least 1 lesion?",
      "requiredWhenVisible": true,
      "options": [
        {"value": "yes", "label": "Yes"},
        {"value": "possible", "label": "Possible"},
        {"value": "no", "label": "No"}
      ]
    },
    {
      "key": "pres_MA",
      "type": "radio",
      "label": "Presense of MA?",
      "requiredWhenVisible": true,
      "visible": [
        {
          "or": [
            {"===": [{"var": "is_gradable"}, "yes"]},
            {"===": [{"var": "is_gradable"}, "possible"]}
          ]
        }
      ],
      "options": [
        {"value": "yes", "label": "Yes"},
        {"value": "possible", "label": "Possible"},
        {"value": "no", "label": "No"},
        {"value": "ungradable", "label": "Ungradable"}
      ]
    },
    {
      "key": "pres_MA_contour",
      "type": "radio",
      "label": "Completed drawing MA?",
      "requiredWhenVisible": true,
      "visible": [
        {
          "or": [
            {"===": [{"var": "pres_MA"}, "yes"]},
            {"===": [{"var": "pres_MA"}, "possible"]}
          ]
        }
      ],
      "options": [
        {"value": "yes", "label": "Yes"},
        {"value": "no", "label": "No"}
      ]
    }
  ]
  },
  "esignature_config": null
}
**Note:** The complete protocol includes 24 more fields following this pattern for all lesion types, plus a notes field. See the full file referenced above.

Handling Removed OHIF Properties

The Legacy form included OHIF-specific properties for image annotation that have no direct equivalent in Task Manager forms.

OHIF Properties in Legacy Form

Example field with OHIF annotation properties:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "label": "Presense of MA?",
  "key": "pres_MA",
  "type": "radio",
  "values": [
    {
      "value": "yes",
      "label": "Yes",
      "requireMeasurements": ["MA"],
      "measurementTools": ["CircleRoi"]
    }
  ]
}

Properties removed from form:

  • requireMeasurements: ["MA"] - Requires MA measurement before form submission
  • measurementTools: ["CircleRoi"] - Only CircleRoi tool available for this option
  • contourVisibility: true - Shows/hides measurement contours

OHIF Viewer Configuration

These properties are OHIF viewer-specific and should be configured at the project level in Task Manager, not in the protocol JSON file.

Protocol JSON File Structure for Task Manager

The converted protocol JSON file contains only the form and e-signature configuration (no viewer configuration):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "form": {
    "title": "Color Fundus Grading Form",
    "description": "Diabetic retinopathy lesion grading form for color fundus images",
    "defaults": {
      "is_gradable": "",
      "pres_MA": "",
      "pres_MA_contour": "",
      ...
    },
    "fields": [...]
  },
  "esignature_config": null
}

Form Features Preserved

Despite the structural changes, all core form functionality is preserved:

Sequential Workflow

The form implements a sequential workflow where each question becomes visible only after the previous is answered:

graph TD
    A[Is image gradable?] -->|Yes/Possible| B[Presence of MA?]
    B -->|Yes/Possible| C[Completed drawing MA?]
    C -->|Yes| D[Presence of HMA?]
    D -->|Yes/Possible| E[Completed drawing HMA?]
    A -->|No| Z[Drawing Complete?]

This is preserved through the visible JsonLogic rules.

Conditional Required Fields

Fields that are conditionally visible are also conditionally required using requiredWhenVisible: true.

Complex Visibility Logic

Multi-condition visibility rules are preserved:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "visible": [
    {
      "or": [
        {"===": [{"var": "pres_MA_contour"}, "yes"]},
        {"===": [{"var": "pres_MA"}, "no"]},
        {"===": [{"var": "pres_MA"}, "ungradable"]}
      ]
    }
  ]
}

Testing Your Converted Form

After converting your form, verify these aspects:

Functionality Tests

  • [ ] Form renders correctly in Task Manager viewer
  • [ ] Sequential visibility logic works (questions appear in correct order)
  • [ ] All radio buttons display proper options
  • [ ] Text fields accept input
  • [ ] Form submission captures all field values
  • [ ] JsonLogic validation rules execute correctly

Data Validation Tests

  • [ ] All field keys are present in defaults object
  • [ ] All visible rules use === (not ==)
  • [ ] All requiredWhenVisible values are boolean or JsonLogic
  • [ ] All options arrays have both value and label
  • [ ] No OHIF-specific properties remain in form

Integration Tests

  • [ ] Form works within protocol context
  • [ ] Form responses save correctly
  • [ ] Viewer configuration integrates properly (if using OHIF)
  • [ ] All lesion assessments can be completed
  • [ ] Final form submission succeeds

Common Conversion Issues

Issue 1: Forgotten Defaults

Problem: Field keys missing from defaults object

Solution: Ensure every field key is present in defaults with an appropriate empty value:

  • Radio/Select fields: ""
  • Checkbox fields: []
  • Text fields: ""

Issue 2: Inconsistent Operators

Problem: Mixed use of == and === in JsonLogic

Solution: Use === consistently throughout Task Manager forms for strict type checking

Issue 3: Options vs Values

Problem: Using values instead of options

Solution: Always rename values → options in field definitions

Issue 4: Nested Conditional

Problem: Leaving conditional.json wrapper

Solution: Unwrap to direct visible property:

1
2
3
4
5
6
7
8
9
// Wrong
"conditional": {
  "json": {"===": [...]}
}

// Correct
"visible": [
  {"===": [...]}
]

Summary

Converting Legacy Task forms to Task Manager protocol JSON format involves:

  1. Protocol structure - Wrap form in protocol JSON with form and esignature_config keys
  2. Structural transformation - Flatten the form hierarchy and add required form properties (title, description, defaults)
  3. Property renaming - Update field property names to Task Manager conventions (values → options, required → requiredWhenVisible, etc.)
  4. JsonLogic standardization - Use strict equality operators (===) and unwrap conditional.json to visible
  5. OHIF property removal - Remove viewer-specific properties from form (configure at project level instead)
  6. Defaults creation - Build comprehensive defaults object with all field keys

The core form logic (visibility, validation, conditional requirements) remains identical. The conversion primarily addresses structural and naming differences, plus the addition of the protocol wrapper structure.