Pan-Canadian HALO Specification

Operation: $clear-context

Overview

The $clear-context operation allows launching applications, such as Point of Care (PoC) systems, to remove clinical contexts previously established during a SMART on FHIR Accelerator (SoFA) launch. This operation ensures data hygiene and supports compliance with jurisdictional data retention policies by deleting context-related data that is no longer needed.

The operation requires the launchID generated by a prior $set-context invocation to identify and remove associated FHIR resources stored in the SoFA for the specified session. These resources may include those created by the launching application through the $set-context operation or by the SMART application after the launch.

The outcome of the operation is returned in an OperationOutcome resource, which provides details on the success or failure of the context-clearing process.

To view the underlying FHIR OperationDefinition resource, see ClearContext.

Invocations

URL: [base]/$clear-context

Parameters (In)

Name	Cardinality	Type	Documentation
launchID	1..1	string	The launchID is a required parameter. It is returned by the $set-context operation when the context was first established.

Return Values (Out)

Name	Cardinality	Type	Documentation
outcome	1..*	OperationOutcome	An OperationOutcome resource detailing the outcome (e.g., success, failure) of the operation.

Operation Failure

In the event of an operation failure, PoC vendors MAY choose to log the failure and proceed with their workflow as normal (e.g., application logout). To account for such cases, the SoFA SHALL implement a mechanism for automatically deleting residual contexts and their associated data after a preconfigured amount of time. This ensures that stale or unused data will not persist unnecessarily, maintaining data integrity, security, and compliance with applicable privacy regulations.

HTTP Response Codes

Given that the result of the $clear-context operation is equivalent to performing one or more FHIR delete interactions, the standard set of HTTP status codes implementers may support are as follows:

200 OK - success code - context cleared successfully and response body contains OperationOutcome
400 Bad Request - error code - Operation failure due to an issue with one or more of the provided parameters (e.g., a missing launchID parameter).
404 Not Found - error code - no context found for the specified launchID
405 Method Not Allowed - error code - server doesn't allow the $clear-context operation

Other standard HTTP status codes such as 202, 204, 401, 403, 409, 412, and 500 may be returned by the SoFA, depending on the jurisdictional SoFA implementation. For more information on how FHIR defines these and other HTTP status codes, see the HTTP section of the base FHIR specification. As more implementations of HALO mature, this list of officially support HTTP status codes may expand with each iteration of the HALO specification.

Examples

Invocation

See the clear-context-invocation-example example for more information.

Parameters

id : clear-context-invocation-example

parameter

name : launchID

value : 123456

{
    "resourceType": "Parameters",
    "id": "clear-context-invocation-example",
    "parameter":  [
        {
            "name": "launchID",
            "valueString": "123456"
        }
    ]
}

<Parameters xmlns="http://hl7.org/fhir">
    <id value="clear-context-invocation-example" />
    <parameter>
        <name value="launchID" />
        <valueString value="123456" />
    </parameter>
</Parameters>

Success Response

See the clear-context-success-response-example example for more information.

Parameters

id : clear-context-success-response-example

parameter

name : outcome

resource

issue

severity : information

code : informational

details

text : Context cleared successfully

{
    "resourceType": "Parameters",
    "id": "clear-context-success-response-example",
    "parameter":  [
        {
            "name": "outcome",
            "resource": {
                "resourceType": "OperationOutcome",
                "issue":  [
                    {
                        "severity": "information",
                        "code": "informational",
                        "details": {
                            "text": "Context cleared successfully"
                        }
                    }
                ]
            }
        }
    ]
}

<Parameters xmlns="http://hl7.org/fhir">
    <id value="clear-context-success-response-example" />
    <parameter>
        <name value="outcome" />
        <resource>
            <OperationOutcome>
                <issue>
                    <severity value="information" />
                    <code value="informational" />
                    <details>
                        <text value="Context cleared successfully" />
                    </details>
                </issue>
            </OperationOutcome>
        </resource>
    </parameter>
</Parameters>

Error Response

See the clear-context-error-response-example example for more information.

Parameters

id : clear-context-error-response-example

parameter

name : outcome

resource

issue

severity : error

code : processing

details

text : Failed to clear the context

{
    "resourceType": "Parameters",
    "id": "clear-context-error-response-example",
    "parameter":  [
        {
            "name": "outcome",
            "resource": {
                "resourceType": "OperationOutcome",
                "issue":  [
                    {
                        "severity": "error",
                        "code": "processing",
                        "details": {
                            "text": "Failed to clear the context"
                        }
                    }
                ]
            }
        }
    ]
}

<Parameters xmlns="http://hl7.org/fhir">
    <id value="clear-context-error-response-example" />
    <parameter>
        <name value="outcome" />
        <resource>
            <OperationOutcome>
                <issue>
                    <severity value="error" />
                    <code value="processing" />
                    <details>
                        <text value="Failed to clear the context" />
                    </details>
                </issue>
            </OperationOutcome>
        </resource>
    </parameter>
</Parameters>