Communication

Overview

The Communication resource is a conveyance of information from one entity, a sender, to another entity, a receiver. The information includes encoded data and optionally a related Patient and a related Encounter.

The following fields are returned if valued:

Note: The examples provided here are non-normative and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.

Errors

The common errors and OperationOutcomes may be returned.

Terminology Bindings

Communication.category
  • Description
    • The category of the communication.
  • Details: Communication Category
    System: http://terminology.hl7.org/CodeSystem/communication-category

  • Details: SNOMED CT
    System: http://snomed.info/sct

Communication.email-status

Extensions

Custom Extensions

All URLs for custom extensions are defined as https://fhir-ehr.cerner.com/r4/StructureDefinition/{id}

ID Value[x] Type Description
reply-to Reference Directs where replies to the communication are sent. Must be a group.
email-status CodeableConcept The status of the electronic communication (in-progress, completed, or received).

Search for communications that meet supplied query parameters.

GET /Communication?:parameters

Notes

Authorization Types

Parameters

Name Required? Type Description
_id Conditionally token The logical resource ID associated with the resource. This parameter is required if category, -email-status, recipient, and received are not used. Example: 489580643.0.-4.prsnl
category Conditionally token A token for a CodeableConcept that points to the CodeableConcept used for Communication.category. This parameter is required with recipient, received, and -email-status if _id is not used. Example: http://terminology.hl7.org/CodeSystem/communication-category|notification
recipient:Group or recipient:Practitioner Conditionally reference The recipient of the communication. This parameter is required with category, received, and -email-status if _id is not used. Example: 3456783
received Conditionally date The date range that the communication falls within. This parameter is required with category, recipient, and -email-status if _id is not used. Example: ge2017-02-01T10:30:00Z
-email-status Conditionally token The status of the email. This parameter is required with category, recipient, and received if _id is not used. Example: http://hl7.org/fhir/task-status|in-progress

Notes:

Headers

Accept: application/fhir+json
Authorization: <OAuth2 Bearer Token>

Example

Request

GET https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Communication?_id=489580643.0.-4.prsnl

Response

Status: 200 OK
{
  "resourceType": "Bundle",
  "id": "e989e20d-5cfc-4b11-ab43-95ba1a684063",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Communication?_id=489580643.0.-4.prsnl"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Communication/489580643.0.-4.prsnl",
      "resource": {
        "resourceType": "Communication",
        "id": "489580643.0.-4.prsnl",
        "meta": {
          "versionId": "0",
          "lastUpdated": "2020-07-16T21:31:35.457Z"
        },
        "text": {
          "status": "generated",
          "div": "&lt;div xmlns='http://www.w3.org/1999/xhtml'>&lt;p>&lt;b>Communication&lt;/b>&lt;/p>&lt;/div>"
        },
        "extension": [
          {
            "valueCodeableConcept": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/task-status",
                  "code": "completed",
                  "display": "Completed"
                }
              ],
              "text": "Completed"
            },
            "url": "https://fhir-ehr.cerner.com/r4/StructureDefinition/email-status"
          }
        ],
        "inResponseTo": [
          {
            "reference": "Communication/512657279.0.-4.prsnl"
          }
        ],
        "status": "completed",
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/communication-category",
                "code": "notification",
                "display": "Notification"
              }
            ],
            "text": "Notification"
          }
        ],
        "priority": "urgent",
        "subject": {
          "reference": "Patient/12505984",
          "display": "JOHNSON, MARIE"
        },
        "topic": {
          "text": "CDI Query"
        },
        "encounter": {
          "reference": "Encounter/97739401"
        },
        "sent": "2020-07-16T21:31:35.457Z",
        "received": "2020-07-16T21:31:35.457Z",
        "recipient": [
          {
            "reference": "Practitioner/12093978",
            "display": "Stone, RN, Sally Cerner"
          },
          {
            "reference": "Group/1568",
            "display": "HEALTHE Receiver Group"
          }
        ],
        "sender": {
          "reference": "Practitioner/11875977",
          "display": "Stratford, Angela Cerner"
        },
        "payload": [
          {
            "contentReference": {
              "reference": "Binary/489580643.0.-4.prsnl"
            }
          }
        ]
      }
    }
  ]
}

Retrieve by ID

List an individual communication by its ID.

GET /Communication/:id

Authorization Types

Headers

Accept: application/fhir+json
Authorization: <OAuth2 Bearer Token>

Example

Request

GET https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Communication/489580643.0.-4.prsnl

Response

Status: 200 OK
{
  "resourceType": "Communication",
  "id": "489580643.0.-4.prsnl",
  "meta": {
    "versionId": "0",
    "lastUpdated": "2020-07-16T21:31:35.457Z"
  },
  "text": {
    "status": "generated",
    "div": "&lt;div xmlns='http://www.w3.org/1999/xhtml'>&lt;p>&lt;b>Communication&lt;/b>&lt;/p>&lt;/div>"
  },
  "extension": [
    {
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/task-status",
            "code": "completed",
            "display": "Completed"
          }
        ],
        "text": "Completed"
      },
      "url": "https://fhir-ehr.cerner.com/r4/StructureDefinition/email-status"
    }
  ],
  "inResponseTo": [
    {
      "reference": "Communication/512657279.0.-4.prsnl"
    }
  ],
  "status": "completed",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/communication-category",
          "code": "notification",
          "display": "Notification"
        }
      ],
      "text": "Notification"
    }
  ],
  "priority": "urgent",
  "subject": {
    "reference": "Patient/12505984",
    "display": "JOHNSON, MARIE"
  },
  "topic": {
    "text": "CDI Query"
  },
  "encounter": {
    "reference": "Encounter/97739401"
  },
  "sent": "2020-07-16T21:31:35.457Z",
  "received": "2020-07-16T21:31:35.457Z",
  "recipient": [
    {
      "reference": "Practitioner/12093978",
      "display": "Stone, RN, Sally Cerner"
    },
    {
      "reference": "Group/1568",
      "display": "HEALTHE Receiver Group"
    }
  ],
  "sender": {
    "reference": "Practitioner/11875977",
    "display": "Stratford, Angela Cerner"
  },
  "payload": [
    {
      "contentReference": {
        "reference": "Binary/489580643.0.-4.prsnl"
      }
    }
  ]
}

Create

Create a new communication.

POST /Communication

Notes

Authorization Types

Headers

Authorization: <OAuth2 Bearer Token>
Accept: application/fhir+json
Content-Type: application/fhir+json

Body Fields

Name Required Type
resourceType Yes string
  • Description
    • The type of the FHIR resource.
  • Example
    • {
        "resourceType": "Communication"
      }
      
  • Notes
    • The resourceType must be 'Communication'.
status Yes code
  • Description
    • The status of the communication.
  • Example
    • {
        "status": "completed"
      }
      
  • Notes
    • All communications must be in 'completed' status.
category Yes CodeableConcept
  • Description
    • Codeable definition of the communication type.
  • Example
    • {
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/communication-category",
                "code": "notification"
              }
            ]
          }
        ]
      }
      
  • Notes
      • Only CommunicationCategory values of notification and reminder and SNOMED CT 312853008 are supported.
priority No code
  • Description
    • The priority of the communication.
  • Example
    • {
        "priority": "routine"
      }
      
  • Notes
    • Only 'routine' and 'urgent' priorities are supported.
subject No Reference (Patient)
  • Description
    • The patient that is the focus of the communication.
  • Example
    • {
        "subject": {
          "reference": "Patient/9836548"
        }
      }
      
  • Notes
    • Only Patient is supported as subject.
topic No code
  • Description
    • The topic of the communication, similar to the subject field of an email.
  • Example
    • {
        "topic" : {
           "text": "Patient Consult Request"
        }
      }
      
  • Notes
    • Currently only free-text topics are supported.
encounter No Reference (Encounter)
  • Description
    • The encounter associated to the communication.
  • Example
    • {
        "encounter" : {
          "reference" : "Encounter/89363836"
        }
      }
      
  • Notes
    • Subject is required when writing an encounter.
recipient Yes Reference (Practitioner, Group)
  • Description
    • The entity receiving the communication.
  • Example
    • {
        "recipient": [
          {
            "reference" : "Practitioner/6373634"
          },
          {
            "reference" : "Group/44466678"
          }
        ]
      }
      
  • Notes
    • Each recipient must be a Practitioner or Group.
sender Yes Reference (Practitioner)
  • Description
    • The entity sending the communication.
  • Example
    • {
        "sender": {
          "reference": "Practitioner/631923"
        }
      }
      
  • Notes
    • The sender must be a Practitioner.
payload Yes BackboneElement
  • Description
    • The text of the communication.
  • Example
    • {
        "payload" : [
          {
            "contentAttachment" : {
              "contentType" : "application/xhtml+xml",
              "data" : "PCFET0NUWVBFIGh0bWwgUFVCTElDICItLy9XM0MvL0RURCBYSFRNTCAxLjAgVHJhbnNpdGlvbmFsLy9FTiIKImh0dHA6Ly93d3cudzMub3JnL1RSL3hodG1sMS9EVEQveGh0bWwxLXRyYW5zaXRpb25hbC5kdGQiPjxodG1sPjxib2R5PjwvYm9keT48L2h0bWw+"
            }
          }
        ]
      }
      
  • Notes
      • content must be supplied as a contentAttachment with contentType and data defined
      • contentType can be set to:
        • application/xhtml+xml
        • text/plain
      • contentType can contain a charset set to:
        • utf-8
        • us-ascii
      • data should be base64 encoded
      • If the contentType is "application/xhtml+xml", then the data (when decoded) should at least contain the following:
        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
              "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
reply-to No Reference (Group)
  • Description
    • The entity replies will be directed to.
  • Example
    • {
        "url": "https://fhir-ehr.cerner.com/r4/StructureDefinition/reply-to",
        "valueReference": {
          "reference": "Group/123"
        }
      }
      
  • Notes
    • The reply-to must be a Group.

Example

Request

POST https://fhir-ehr.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Communication

Body

{
  "resourceType": "Communication",
  "extension": [
    {
      "url": "https://fhir-ehr.cerner.com/r4/StructureDefinition/reply-to",
      "valueReference": {
        "reference": "Group/6345478364"
      }
    }
  ],
  "status": "completed",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/communication-category",
          "code": "reminder"
        }
      ]
    }
  ],
  "priority": "urgent",
  "subject": {
    "reference": "Patient/12457978"
  },
  "topic": {
    "text": "CDI Query"
  },
  "encounter": {
    "reference": "Encounter/97697401"
  },
  "recipient": [
    {
      "reference": "Practitioner/744113"
    },
    {
      "reference": "Group/6345478364"
    }
  ],
  "sender": {
    "reference": "Practitioner/593923"
  },
  "payload": [
    {
      "contentAttachment": {
        "contentType": "text/plain",
        "data": "Q29tbXVuaWNhdGlvbg=="
      }
    }
  ]
}

Response

Status: 201 Created
Cache-Control: no-cache
Content-Length: 0
Content-Type: application/json
Date: Tue, 04 Aug 2020 17:59:03 GMT
Etag: W/"0"
Location: https://fhir-ehr.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Communication/472894781.0.-4.0
Last-Modified: Tue, 04 Aug 2020 17:59:03 GMT
Server-Response-Time: 22.810143
Status: 201 Created
Vary: Origin
X-Request-Id: b89310ef-51ef-4b76-b92e-d070496c999c
X-Runtime: 0.022706

The ETag response header indicates the current If-Match version to use on subsequent updates.

Patch

Patch an existing communication.

PATCH /Communication/:id

Notes

Authorization Types

Headers

Authorization: <OAuth2 Bearer Token>
Accept: application/fhir+json
Content-Type: application/json-patch+json
If-Match: W/"<Current version of the Communication resource>"

Patch Operations

Path Operation Value Type
/extension replace Extension
  • Description
    • Replace the value of an extension.
  • Example
    • {
        "path": "/extension",
        "op": "replace",
        "value": [
          {
            "valueCodeableConcept": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/task-status",
                  "code": "completed"
                }
              ]
            },
            "url": "https://fhir-ehr.cerner.com/r4/StructureDefinition/email-status"
          }
        ]
      }
      
  • Notes

Example

Request

PATCH https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Communication/123

Body

[
  {
    "path": "/extension",
    "op": "replace",
    "value": [
      {
        "valueCodeableConcept": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/task-status",
              "code": "completed"
            }
          ]
        },
        "url": "https://fhir-ehr.cerner.com/r4/StructureDefinition/email-status"
      }
    ]
  }
]

Response

Status: 200 OK
Cache-Control: no-cache
Content-Length: 0
Content-Type: application/json
Date: Wed, 11 Nov 2020 18:42:40 GMT
Etag: W/"2"
Last-Modified: Wed, 11 Nov 2020 18:42:40 GMT
Server-Response-Time: 826.746885
Status: 200 OK
Vary: Origin
X-Request-Id: 1594889a-8278-43f2-9c83-d84d6d2b3c72
X-Runtime: 0.826616

The ETag response header indicates the current If-Match version to use on subsequent updates.