Skip to main content

DiagnosticReport-update

Rad AI Reporting interprets the DiagnosticReport-update event in one of two ways:

  • As a set of resources that provide additional context to the open report. These resources will appear in the Measurements panel in Rad AI Reporting.
  • As a request to sign the open report.

Workflow​

The DiagnosticReport-update event signals Rad AI Reporting to make related resources accessible to the current report, or to sign it. If the study page isn't loaded, sign requests are ignored without a syncerror response. If the study page is loaded but has no active report or addendum to sign, a sign request receives a syncerror as described in Outcome. Updates that add or remove related resources are ignored if a report isn't currently open.

Today, Rad AI Reporting only acts on Observation and ImagingSelection resources found in this event, and on a DiagnosticReport resource explicitly marked as a sign request.

Each Observation is:

  • Added to the Measurements panel.
  • Matched against Formula Fields in the current template, if one is selected.
  • Inserted directly into the report if tagged for Quick-Paste.
  • Persisted, so it remains available in the Measurements panel if the report is closed and later reopened.

Each ImagingSelection is added to the Measurements panel. It's only persisted if it arrives in the same event as an Observation. See ImagingSelection for details.

Data Format​

The event object will look like this. Please note that any number of FHIR resources may be provided in the entry parameter. For each FHIR resource, you'll need a separate object in the entry array.

{
"id": "155cc6e5-0e85-41f9-b94a-a409d4769073",
"timestamp": "2024-01-01T00:00:00.000Z",
"event": {
"hub.topic": "test-topic",
"hub.event": "DiagnosticReport-update",
"context": [
{
"key": "report",
"reference": {
"reference": "DiagnosticReport/{report-id}"
}
},
{
"key": "updates",
"resource": {
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"request": {
"method": "PUT",
"url": "{resource-type}/{resource-id}"
},
"resource": {fhir-resource}
}
]
}
}
]
}
}

Using the above format, the event should contain one or more of the following resources.

Observation​

FHIR Observation resources can be used to provide measurements or annotations to Rad AI Reporting.

code Field​

The code field is used for both Observation.code (for single measurements) and Observation.component.code (for related measurements).

Display​

When displayed in Rad AI Reporting, the Observation.code.coding[0].display field is prefixed to the value display. See Single Measurement for an example of this.

Formula Fields​

Observation resources shared via FHIRcast can populate Formula Fields in a Rad AI Reporting template. See Template Integration for how values are matched, including how related measurements (Observation.component) are handled.

value[x] Field​

The value[x] field is used for both Observation.value[x] (for single measurements) and Observation.component.value[x] (for related measurements).

See Template Integration for which value[x] fields Rad AI Reporting supports and how they're displayed.

Single Measurement​

If you are providing a single measurement, use the Observation.value[x] field.

Here's a simplified example of a single measurement in an Observation resource. In this example, the Observation would be displayed as "Circumference: 12.0cm".

{
"resourceType": "Observation",
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "42405-0",
"display": "Circumference"
}
]
},
"subject": {
"reference": "Patient/c57334fc-0497-470f-b375-ac04e8967193"
},
"valueQuantity": {
"value": 12.0,
"unit": "cm"
}
}

If you are providing related measurements, use the Observation.component field, where each component has an Observation.component.value[x] field.

Here's a simplified example of related measurements in an Observation resource. In this example, the Observation would be displayed as a list of measurements:

  • "Circumference: 12.0cm"
  • "Diameter: 6.0cm"
  • "Area: 6.75cm²"
{
"resourceType": "Observation",
"status": "final",
"code": {
"text": "Measurements"
},
"subject": {
"reference": "Patient/c57334fc-0497-470f-b375-ac04e8967193"
},
"component": [
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "42405-0",
"display": "Circumference"
}
]
},
"valueQuantity": {
"value": 12.0,
"unit": "cm"
}
},
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "42406-8",
"display": "Diameter"
}
]
},
"valueQuantity": {
"value": 6.0,
"unit": "cm"
}
},
{
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "42798000",
"display": "Area"
}
]
},
"valueQuantity": {
"value": 6.75,
"unit": "cm²"
}
}
]
}

Quick-Paste​

An Observation resource tagged with a quick-paste meta.tag is, in addition to appearing in the Measurements panel, inserted directly into the report at the user's cursor position.

{
"resourceType": "Observation",
"meta": {
"tag": [
{
"code": "quick-paste"
}
]
},
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "42406-8",
"display": "Diameter"
}
]
},
"subject": {
"reference": "Patient/c57334fc-0497-470f-b375-ac04e8967193"
},
"valueQuantity": {
"value": 8,
"unit": "mm"
}
}

Unlike the Measurements panel, the inserted text is just the value (with its unit): the example above inserts "8 mm", not "Diameter: 8mm". If more than one quick-paste Observation (or related measurement component) arrives at once, each value is inserted as a comma-separated list, e.g. "8 mm, 12 mm".

Quick-paste only fires once per unique Observation.code (or Observation.component.code). Sending an Observation with a code that's already been quick-pasted updates its value in the Measurements panel, but does not insert it into the report again.

If no report editor is focused when a quick-paste Observation arrives, the value is not inserted.

ImagingSelection​

warning

The ImagingSelection resource is not profiled in the FHIRcast Implementation Guide; Rad AI Reporting's implementation references the FHIR R5 definition.

FHIR ImagingSelection resources can be used to specify series and imaging information from the PACS. When providing measurements, this can be used to specify which series/image(s) the measurements originated from.

An ImagingSelection appears in the Measurements panel as its own row, displayed as "Series 1, Image 2" (or "Series 1, Images 2, 3" for multiple instances). When it's sent in the same DiagnosticReport-update event as one or more Observation measurements, it's grouped alongside them in the panel. As with any Measurements panel row, clicking it inserts its displayed text into the report at the user's cursor.

Here's a simplified example of an ImagingSelection resource.

{
"resourceType": "ImagingSelection",
"status": "available",
"code": {
"coding": [
{
"system": "http://dicom.nema.org/resources/ontology/DCM",
"code": "113000"
}
]
},
"seriesNumber": 1,
"instance": [
{
"uid": "2.16.840.1.113669.632.21.1650549011.2966824467.36921496302286845",
"number": 2
}
]
}

Example Message​

For a comprehensive DiagnosticReport-update event, see below. This event contains:

{
"id": "155cc6e5-0e85-41f9-b94a-a409d4769073",
"timestamp": "2024-01-01T00:00:00.000Z",
"event": {
"hub.topic": "test-topic",
"hub.event": "DiagnosticReport-update",
"context": [
{
"key": "report",
"reference": {
"reference": "DiagnosticReport/2402d8c6-3a1d-4a4a-9b1e-6f0c8a5d7e21"
}
},
{
"key": "updates",
"resource": {
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"request": {
"method": "PUT",
"url": "Observation/f408aa75-04ca-431e-ac9c-7cb6b33c8a27"
},
"resource": {
"resourceType": "Observation",
"id": "f408aa75-04ca-431e-ac9c-7cb6b33c8a27",
"status": "final",
"code": {
"coding": [
{
"system": "https://example.com/fhir/CodeSystem/measurements",
"code": "length",
"display": "Length"
}
]
},
"subject": {
"reference": "Patient/c57334fc-0497-470f-b375-ac04e8967193"
},
"valueQuantity": {
"value": 123.456,
"unit": "mm"
}
}
},
{
"request": {
"method": "PUT",
"url": "Observation/7c1d2f4e-5b8a-4e3f-9a6d-2c0b1e8f4a93"
},
"resource": {
"resourceType": "Observation",
"id": "7c1d2f4e-5b8a-4e3f-9a6d-2c0b1e8f4a93",
"status": "final",
"code": {
"text": "Measurements"
},
"subject": {
"reference": "Patient/c57334fc-0497-470f-b375-ac04e8967193"
},
"component": [
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "42405-0",
"display": "Circumference"
}
]
},
"valueQuantity": {
"value": 12.0,
"unit": "cm"
}
},
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "42406-8",
"display": "Diameter"
}
]
},
"valueQuantity": {
"value": 6.0,
"unit": "cm"
}
},
{
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "42798000",
"display": "Area"
}
]
},
"valueQuantity": {
"value": 6.75,
"unit": "cm²"
}
}
]
}
},
{
"request": {
"method": "PUT",
"url": "ImagingSelection/3287df10-7d51-472f-9d62-7cbb36056df1"
},
"resource": {
"resourceType": "ImagingSelection",
"id": "3287df10-7d51-472f-9d62-7cbb36056df1",
"status": "available",
"code": {
"coding": [
{
"system": "http://dicom.nema.org/resources/ontology/DCM",
"code": "113000"
}
]
},
"seriesNumber": 1,
"instance": [
{
"uid": "2.16.840.1.113669.632.21.1650549011.2966824467.36921496302286845",
"number": 2
}
]
}
}
]
}
}
]
}
}

Signing the Report​

A DiagnosticReport-update event can ask Rad AI Reporting to sign the open report, as if the radiologist had signed it from Rad AI Reporting.

info

Signing through FHIRcast is disabled by default and is enabled per organization. Contact Rad AI to enable it. While it's disabled, sign requests are ignored and no syncerror is published.

Sign Request​

Rad AI Reporting treats an event as a sign request only when its updates Bundle contains a DiagnosticReport entry that:

  • Uses request.method PUT and request.url DiagnosticReport/{id}, where {id} is the DiagnosticReport.id.
  • Has a workflow-reasonCode extension with the coding below.
  • Sets DiagnosticReport.status to the status to sign with.
{
"url": "http://hl7.org/fhir/StructureDefinition/workflow-reasonCode",
"valueCodeableConcept": {
"coding": [
{
"system": "http://fhir.radai.com/CodeSystem/reason-code",
"code": "sign"
}
]
}
}

A DiagnosticReport without this extension is never treated as a sign request, even if it changes status.

Status​

DiagnosticReport.statusAction in Rad AI Reporting
preliminaryPreliminarily signs the open report.
finalSigns the open report or addendum.
amendedSigns the open report or addendum.
Any other statusRejects the sign request and publishes a syncerror.

report Context Key​

A sign request must include exactly one report context key holding a Reference to the same DiagnosticReport being PUT, e.g. { "key": "report", "reference": { "reference": "DiagnosticReport/{id}" } }. An embedded DiagnosticReport resource isn't accepted in place of the Reference. If the report key is missing, or doesn't match the DiagnosticReport being PUT, the sign request is rejected and a syncerror is published.

note

The report key is only checked for sign requests. Events that only add Observation or ImagingSelection resources aren't checked against it today, but may be in the future. Include a report key in every DiagnosticReport-update event, as the FHIRcast Implementation Guide requires.

One Purpose per Event​

A sign request should contain only the DiagnosticReport being signed. Don't include Observation or ImagingSelection resources in the same event: Rad AI Reporting handles them independently of the sign request and doesn't guarantee they're applied before the report is signed. Send them in an earlier DiagnosticReport-update event instead. An event may contain at most one DiagnosticReport marked as a sign request.

Outcome​

Rad AI Reporting handles sign requests one at a time, in the order received. Signing follows the same rules as when the radiologist signs from Rad AI Reporting. On success, Rad AI Reporting publishes the same events it does after the radiologist signs, including a DiagnosticReport-update with the new status.

note

Sign requests received before the study page has loaded, or while the radiologist is on another page, are ignored without a syncerror response. Send sign requests after the study page has loaded.

For sign requests handled on a loaded study page, if Rad AI Reporting can't sign the report, it publishes a syncerror whose OperationOutcome identifies the DiagnosticReport-update event by its id, with one of these diagnostics messages:

Reasondiagnostics
Missing or mismatched report key, url or IDThe sign request must update the anchored DiagnosticReport.
Unsupported statusThe sign request must specify preliminary, final, or amended status.
The loaded study has no active report or addendumThere is no active report to sign.
The report can't be signed in its current stateThis report cannot be signed in its current state.
The report editor isn't readyThe report editor is not available for signing.
Another report action is in progressAnother report action is in progress. Try again shortly.
The radiologist must confirm signingSigning requires confirmation in Reporting.
The report is locked while Omni completesThe report is locked until Omni completes.
The order was canceledThe order was canceled. Review the order before signing.
The order changedThe order changed. Review the order before signing.
Signing failedThe report could not be signed. Try again or contact support.

An active report or addendum is one still being worked on, rather than an already signed document. Opening a study whose report is already signed or finalized does not by itself make that report active. Without an active addendum, a sign request on that loaded study therefore receives There is no active report to sign. This does not mean the study page is unavailable or still loading.

When signing requires confirmation, Rad AI Reporting opens its sign confirmation dialog so the radiologist can complete signing there.

Example Sign Request​

{
"id": "6a1f1d1e-3b0f-4b7f-9a52-0f3c8f3c5b21",
"timestamp": "2024-01-01T00:00:00.000Z",
"event": {
"hub.topic": "test-topic",
"hub.event": "DiagnosticReport-update",
"context": [
{
"key": "report",
"reference": {
"reference": "DiagnosticReport/2402d3bd-e988-414b-b7f2-4322e86c9327"
}
},
{
"key": "updates",
"resource": {
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"request": {
"method": "PUT",
"url": "DiagnosticReport/2402d3bd-e988-414b-b7f2-4322e86c9327"
},
"resource": {
"resourceType": "DiagnosticReport",
"id": "2402d3bd-e988-414b-b7f2-4322e86c9327",
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "18748-4"
}
]
},
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/workflow-reasonCode",
"valueCodeableConcept": {
"coding": [
{
"system": "http://fhir.radai.com/CodeSystem/reason-code",
"code": "sign"
}
]
}
}
]
}
}
]
}
}
]
}
}