Profiles & Operations > Interaction: Create Subscription

Interaction: Create Subscription

The Create Subscription interaction creates a subscription to a specified event, enabling the subscriber to receive notifications when the event occurs.

Scope

This interaction involves a request by a Point of Service system to create Subscription on the Subscription server. The request is received by the Subscription service which stores the Subscription resource and returns an HTTP response code and an OperationOutcome resource if applicable.

Interaction Sequence Diagram

Specification

Subscription Create Request

Client creates and submits a request to the FHIR server to express interest to subscribe for notifications about changes to specific resources. Client use HTTP POST method to submit subscritpion request in the following manner

POST [base]/Subscription HTTP/1.1

Host: example.com

Content-Type: application/fhir+json

where the HTTP Body contains a FHIR R5 Backport Subscription resource, conformant to Profile: Subscription

Example Create Subscription Interaction

Request Message:

HTTP Method:

POST

Headers:

Content-Type: application/fhir+json

Address:

[base]/Subscription/

Response message body:

{
    "resourceType": "Subscription",
    "id": "f63b8b72-23b4-4c3f-8a07-8fbe93d46f9d",
    "identifier": [
        {
            "system": "https://oh-subscriptions.ca/ids",
            "value": "emr_subscription-12345_GUID"
        }
    ],    
    "meta": {
        "profile":  [
            "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
        ]
    },
    "text": {
        "status": "generated",
        --- We have skipped the narrative for better readability of the resource ---
    },
    "status": "active",
    "end": "2020-12-31T12:00:00Z",
    "reason": "R4/B Example Topic-Based Subscription for Patient Admission",
    "criteria": "http://hl7.org/SubscriptionTopic/admission",
    "_criteria": {
        "extension":  [
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
                "valueString": "Encounter?patient=Patient/123"
            }
        ]
    },
    "channel": {
        "extension":  [
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
                "valueUnsignedInt": 86400
            },
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
                "valueUnsignedInt": 60
            },
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
                "valuePositiveInt": 20
            }
        ],
        "type": "rest-hook",
        "endpoint": "https://example.org/Endpoints/d7dcc004-808d-452b-8030-3a3a13cd871d",
        "payload": "application/fhir+json",
        "_payload": {
            "extension":  [
                {
                    "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
                    "valueCode": "id-only"
                }
            ]
        }
    }
}

Supported Profiles

Profile Name URL
Backport Subscription R4/B Topic-Based Subscription

Expected Behaviour

Case Scenario Description HTTP Status Code Response Payload
1 A valid Subscription is submitted, accepted, and created in the repository HTTP 201 Created. Returns the created resource.
2 The subscribtion has been received but is being processed asynchronously HTTP 202 Accepted.
3 The submitted Subscription cannot be validated as it does not conform to the specification HTTP 400 Bad Request. Returns an OperationOutcome resource indicating an issue. The client must fix the request and try again.
4 Subsciprtion API validates the request but cannot return a valid response due to internal issues. HTTP 500 Internal Server Error. Returns an OperationOutcome resource indicating an issue.