Data Integration

Last updated: 23 Jan 2026

The Canvas SDK allows you to manage documents in the Data Integration queue.

Updating Document Fields #

To prefill fields on a document in the Data Integration queue, import the PrefillDocumentFields class from canvas_sdk.effects.data_integration and create an instance of it. This effect creates or updates an IntegrationTaskPrefill record for a document, enabling automated field extraction workflows typically used when an LLM system extracts values from a document.

Attribute		Type	Description
document_id	required	string	The ID of the IntegrationTask document to update.
templates	required	list[Template]	List of templates with fields to prefill.
annotations	optional	list[Annotation]	Top-level annotations to display alongside the prefill in UI.

Template #

The templates parameter is a list of template objects, each representing a report template with fields to prefill:

Key		Type	Description
templateId	required	int	The ID of the report template.
templateName	required	string	The name of the report template (non-empty).
fields	required	dict[string, FieldData]	Fields keyed by LOINC code or field label.

FieldData #

Each field in the fields dictionary contains:

Key		Type	Description
value	required	string	The field value.
unit	optional	string	The unit of measurement (e.g., “mg/dL”).
referenceRange	optional	string	The reference range (e.g., “0.45 - 4.50 uIU/mL”).
abnormal	optional	boolean	Whether the value is abnormal.
annotations	optional	list[Annotation]	Field-level annotations.

Annotation #

Annotations can be applied at both the top level and field level:

Key		Type	Description
text	required	string	The annotation label (e.g., “AI 92%”).
color	required	string	Hex color code for the annotation (e.g., “#4CAF50”).

An example of prefilling fields on a lab report:

from canvas_sdk.effects import Effect
from canvas_sdk.effects.data_integration import PrefillDocumentFields
from canvas_sdk.events import EventType
from canvas_sdk.handlers import BaseHandler


class PrefillHandler(BaseHandler):
    RESPONDS_TO = EventType.Name(EventType.DOCUMENT_RECEIVED)

    def compute(self) -> list[Effect]:
        document_id = self.event.context.get("document", {}).get("id")
        if not document_id:
            return []

        prefill = PrefillDocumentFields(
            document_id=document_id,
            templates=[
                {
                    "templateId": 620,
                    "templateName": "Thyroid Profile With TSH",
                    "fields": {
                        "11580-8": {
                            "value": "2.35",
                            "unit": "uIU/mL",
                            "referenceRange": "0.45 - 4.50 uIU/mL",
                        },
                    },
                }
            ],
        )

        return [prefill.apply()]

An example with field-level annotations for LLM confidence scores:

from canvas_sdk.effects.data_integration import PrefillDocumentFields

prefill = PrefillDocumentFields(
    document_id="d2194110-5c9a-4842-8733-ef09ea5ead11",
    templates=[
        {
            "templateId": 620,
            "templateName": "Thyroid Profile With TSH",
            "fields": {
                "11580-8": {
                    "value": "2.35",
                    "unit": "uIU/mL",
                    "referenceRange": "0.45 - 4.50 uIU/mL",
                    "annotations": [{"text": "AI 92%", "color": "#4CAF50"}],
                },
                "3026-2": {
                    "value": "7.8",
                    "unit": "ug/dL",
                    "referenceRange": "4.5 - 12.0 ug/dL",
                    "annotations": [{"text": "AI 89%", "color": "#4CAF50"}],
                },
            },
        }
    ],
    annotations=[
        {"text": "1 template matched", "color": "#2196F3"},
        {"text": "2 fields extracted", "color": "#00BCD4"},
    ],
)

An example with multiple templates and abnormal value flagging:

from canvas_sdk.effects.data_integration import PrefillDocumentFields

prefill = PrefillDocumentFields(
    document_id="d2194110-5c9a-4842-8733-ef09ea5ead11",
    templates=[
        {
            "templateId": 620,
            "templateName": "Thyroid Profile With TSH",
            "fields": {
                "11580-8": {
                    "value": "8.50",
                    "unit": "uIU/mL",
                    "referenceRange": "0.45 - 4.50 uIU/mL",
                    "abnormal": True,
                    "annotations": [
                        {"text": "AI 95%", "color": "#4CAF50"},
                        {"text": "AI 55%", "color": "#F44336"},
                    ],
                },
            },
        },
        {
            "templateId": 621,
            "templateName": "Complete Blood Count",
            "fields": {
                "718-7": {
                    "value": "14.2",
                    "unit": "g/dL",
                    "referenceRange": "12.0 - 16.0 g/dL",
                    "annotations": [{"text": "AI 90%", "color": "#4CAF50"}],
                },
            },
        },
    ],
)