# Custom Supervision
Using JSON Schema Form as a form builder to create customer-driven UIs for Supervision tasks.
A Custom Supervision task’s interface is configured directly in the JSON that defines the custom flow. Each custom flow can have its own Custom Supervision task logic, name, and interface. You can find more details about how to configure a Custom Supervision task’s interface and what the customization options are in the sections below.
> ⚠️ Keep in mind that Custom Supervision was designed to be as flexible as possible, but there are still recommended best practices to maximize the potential of the feature. Most of what is defined in this article is to outline those recommended practices.
> Additionally, please note that:
>
> - This article is intended to inform developers using the IDP Custom Supervision Block, which is a modified version of the more generic Custom Supervision Block and includes an IDP wrapper to handle reading/writing data from the IDP database.
>
> - For the purpose of illustration, JSON examples in this article reference what may appear to be hardcoded identifiers (ex: `layout_field_id: '2afd7a67-ddee-484f-ab6b-2d292752e5ee'`), but it is possible to dynamically reference entities using a Custom Code Block. This enables the Custom Supervision task interface to be completely dynamic in which transcription fields, pages, decisions, text blocks, etc that are presented to a user during the execution of a particular flow.
## JSON Configuration
### Custom Supervision Block Basics
The base of the custom portion of the Custom Supervision Block is the `supervision_template`. Defining the Supervision template and its version is the first step of configuring the Custom Supervision task’s interface.
> ⚠️ There is currently only a single template built for Custom Supervision - `three_column_template`. Details of this template are defined below.
#### Property Definitions
A template will always have a base with two properties:
| Property | Description |
| --- | --- |
| name | Name of the Supervision template that should be tied to the UI. Valid names are currently limited to the amount of development done by the Hyperscience team. As of v32.0.1, the only valid name is `three_column_template`. |
| version | The Supervision template’s version. This property is for future use to handle version control as Custom Supervision evolves. Currently, the only available version for `three_column_template` is `1.0`. |
```
{
supervision_template: [
{
name: 'three_column_template',
version: '1.0'
}
]
}
```
> ⚠️ While in the future you will be able to list multiple templates in the top-level list, currently only one is supported.
### Three Column Template - Basics
For v32.0.1, there is a single template that can be used with Custom Supervision, which is the `three_column_template`. There are three sections of this template: a thumbnail panel (left panel), an image panel (middle panel), and an actions panel (right panel). The thumbnail and actions panels are customizable, while the middle panel is not customizable and shows a full-page view of the document pages that are sent to Custom Supervision.
#### Property Definitions
| Property | Description |
| --- | --- |
| thumbnail | Configurable options for the thumbnail panel.
`group_by_document` \- boolean - Group pages at the document level.
`group_by_case` \- boolean - Group pages/documents at the case level. |
| actions | List of tabs to be included in the action panel. Representative of the structure used in JSON Schema Form. |
```
{
supervision_template: [
{
name: 'three_column_template',
version: '1.0',
thumbnail: {
group_by_document: true,
group_by_case: true
},
action: [
{
name: 'my_tab',
display: 'SSN Info',
input: [
{
name: 'ssn_field',
type: 'transcription',
layout_field_id: '2afd7a67-ddee-484f-ab6b-2d292752e5ee',
title: 'SSN'
}
],
ui: {
groups: [
{
title: 'My Group',
fields: ['ssn_field']
}
]
}
}
]
}
]
}
```
### Three Column Template - Thumbnail
There are two options available for configuration of the left thumbnail panel. Both options are independent boolean values, which makes four different combinations possible:
- Pages are listed individually and are not grouped (both options set to `false`)
- Group by documents
- Group by cases
- Group by both documents and cases (both options set to `true`)
Each screenshot is from the same set of pages, documents, and cases, but with different configurations.
```
thumbnail: {
group_by_document: false,
group_by_case: false
}
```
```
thumbnail: {
group_by_document: true,
group_by_case: false
}
```
```
thumbnail: {
group_by_document: false,
group_by_case: true
}
```
```
thumbnail: {
group_by_document: true,
group_by_case: true
}
```
### Three Column Template - Actions
The `action` property will be a list of Tab objects. Each Tab in the `action` property corresponds to a tab in the Custom Supervision task’s right panel.
> ⚠️ You can have a maximum of 3 tabs. If you configure more than 3, they will be automatically truncated in the UI.
#### Property Definitions
| Property | Description |
| --- | --- |
| name | Internal name of the tab; only used for internal navigation and not displayed in the UI. |
| display | Text to display on the tab in the UI. Users will see this text as the name of tab. |
| input | List of Input Fields as defined below. This list contains the bulk of the definition of what the Action pane is going to look like. |
| ui | Contains the `groups` property, which defines where the fields will appear and in what order. |
#### Input Field Types
There are several different types of fields that can be rendered in the first version of Custom Supervision. These fields are specifically defined by the `type` property of each of the inputs.
The following types of Input Fields are supported:
- Title fields
- Text block fields
- Transcription fields
- Decision fields
- Case fields
##### Title Fields
There are two title field subtypes:
- `document_title` \- Designed to be used as a header when displaying document-related data. It will display information for the currently selected document, including document ID and layout name.
- `case_title` \- Designed to be used as a header when displaying case-related data. It will display the case ID for the currently selected case.
###### Document Title
> ⚠️ The `name` property must be unique.
The `name` of the `document_title` input is needed for rendering, but it is not shown in the UI.
When defining a `document_title` field, set the `type` to `document_title`.
```
{
action: [
{
name: 'document_tab',
display: 'Document Data',
input: [
{
name: 'doc_title',
type: 'document_title'
},
...
]
}
]
}
```
###### Case Title
> ⚠️ The `name` property must be unique.
The `name` of the `case_title` input is needed for rendering, but it is not shown in the UI.
When defining a `case_title` field, set the `type` to `case_title`.
```
{
action: [
{
name: 'case_tab',
display: 'Case Data',
input: [
{
name: 'case_title',
type: 'case_title'
},
...
]
}
]
}
```
##### Text Block Fields
Text block fields show static text on a tab. Text block fields have a single subtype called `text_block`.
> ⚠️ The `name` property must be unique.
| Property | Description |
| --- | --- |
| `name` | The text block fields’s internal name. It is needed for rendering, but it is not shown in the UI. |
| `type` | The text block field’s subtype. Currently, `text_block` is the only valid value. |
| `title` | The text block field’s title that is displayed on the tab. |
| `description` | Static text displayed on the tab. You can use `\n` to move text to the next line. |
```
{
action: [
{
name: 'case_tab',
display: 'Case Data',
input: [
...
{
name: 'instructions',
type: 'text_block',
title: '',
description: 'Instructions:\n$100 Processing fee\n$50 optional fee for expediting case'
}
...
]
}
]
}
```
##### Transcription Fields
Transcription fields will be one of the more common fields used with the current version of Custom Supervision. They show the transcription of fields that have been processed earlier in the custom flow.
Transcription fields respect the Custom Supervision Block’s Custom Supervision Transcription Masking setting. Once the `data` is matched with the field, we take advantage of the `data_type_uuid` associated with the data piece to include masking and validation based on this block setting.
###### Property Definitions
> ⚠️ The `name` property must be unique. If you use the `field_name`, for example, it might not be unique and could cause issues when the Custom Supervision task is displayed.
| Property | Description |
| --- | --- |
| name | The transcription field’s internal name. It is needed for rendering, but it is not shown in the UI. |
| type | The transcription field’s subtype. Currently, `transcription` is the only valid value. |
| layout_field_id | UUID of the layout field that the transcription field is linked to. This UUID will match up with what is provided in the `data` portion of the payload. |
```
{
action: [
{
name: 'document_tab',
display: 'Document Data',
input: [
...
{
name: 'courtesy_amount',
type: 'transcription',
layout_field_id: 'd82c1d10-45ff-4a66-b4a1-f300a0ff0a07',
title: 'Courtesy Amount'
},
{
name: 'legal_amount',
type: 'transcription',
layout_field_id: 'b31c2239-d184-4914-8f17-d281c4df493b',
title: 'Legal Amount'
},
...
]
}
]
}
```
###### Decision Fields
Unique to Custom Supervision is the ability to make decisions on different entities. Decisions, or decision fields, are drop-down menus with options from a predetermined set of choices set in the JSON configuration. A decision field can be tied to a document, case, page, or field.
To add a decision field, you need to define the properties described in the sections below.
###### title
The display header, or name, for the decision field
###### relation
A nested object containing a required type property. If the decision applies to a field, you need to define another required property called `match`.
- `type` \- string - Type of entity you want to associate with the decision field. The possible values for the `type` property are the following:
- `case` \- Associates the decision with the currently selected case.
- `document` \- Associates the decision with the currently selected document.
- `page` \- Associates the decision with the currently selected page.
- `field` \- Associates the decision with a predefined field.
- `match` \- string - Only used for `field` type decisions. This value is the same as the field’s `layout_field_uuid` property. The `relation` object uses this `match` property to associate the decision with a predefined field.
> ⚠️ Even though we use `layout_field_id` to match the decision for fields, we still save it back to the specific Field ID when a decision is made.
###### schema
A nested object containing an array. You need to define one of the following arrays:
- `oneOf` \- array - Selection type for a single-select decision.
- `anyOf` \- array - Selection type for multi-select decision.
Regardless of the array type, it contains a list of choices with these properties:
```
{
const: 'my_internal_choice_name',
title: 'Display Choice Name'
}
```
The `title` is the option’s name that will be displayed in the UI.
The `const` is the option’s internal name. It is used if there is a need to define an internal value that will be passed along in the workflow and eventually stored in the database.
* * *
Single-select document decision
```
{
action: [
{
name: 'document_tab',
display: 'Document Data',
input: [
...
{
name: 'check_decision',
type: 'decision',
title: 'Decision',
relation: {
type: 'document'
},
schema: {
oneOf: [
{
const: 'accept',
title: 'Accept Check'
},
{
const: 'reject',
title: 'Reject Check'
},
{
const: 'return',
title: 'Return overpaid fees'
}
]
}
},
...
]
}
]
}
```
Default state - No option previously selected
When the `type` property is `case`, `document`, or `page`, a footer label appears below the decision field to provide context.
Open state:
When opened, the decision field displays the available options.
* * *
### External Sources
In addition to customizing the three-panel interface, you can also display pages that come from submissions that the Custom Supervision Block is not currently processing (“external submissions”). Users can compare these pages with the documents and pages being processing through the Custom Supervision Block.
To display pages from external submissions, you need to define their respective page IDs at the same level as `supervision_template`. Here is an example of defining page IDs:
```
{
page_ids: [1, 2, 3, 15],
supervision_template: [
{
name: 'three_column_template',
version: '1.0'
}
]
}
```
> ⚠️ There are restrictions that come with this added flexibility. Since these fields are not in the current submission and thus may have already gone through transcription and other Supervision tasks, all fields that are displayed for these pages will be uneditable.
## Examples
Here is a full example of a two-tab setup. Again, we used mock UUIDs for readability.
```
{
supervision_template: [
{
name: 'three_column_template',
version: '1.0',
thumbnail: {
group_by_document: true,
group_by_case: true,
},
action: [
{
name: 'document_tab',
display: 'Document Data',
input: [
{
name: 'doc_title',
type: 'document_title',
},
{
name: 'check_amount',
type: 'transcription',
layout_field_id: '',
title: 'Check Amount',
ui: {
hidden: true,
},
dependencies: [
{
condition: {
properties: { layoutId: { const: '' } },
},
override: { ui: { hidden: false } },
},
],
},
...
]
},
{
name: 'case_tab',
display: 'Case Data',
input: [
{
name: 'case_title',
type: 'case_title',
},
...
],
}
]
}
]
}
```
Images and data are all mocked (and often repeated), but hopefully, you now have an idea of what can be done with Custom Supervision.