Document References (Clinical Notes)

Overview

The getDocumentReference method allows users to access all their document references. It provides various filtering options that can be employed to specifically retrieve the clinical notes (a specific type of document reference).
The getBinary method is a companion method used for fetching the content which is stored in a binary resource.

Method Signature

getDocumentReference signature

The function which fetches all document references related to a user.

suspend fun getDocumentReference(request: DocumentReferenceRequest): BwellResult<DocumentReference>

Return Type

BwellResult<> containing list of DocumentReference. Type of DocumentReference is described below

data class DocumentReference( 
    val id: String,
    val meta: Meta,
    val language: String,
    val text: DocumentReferenceNarrative,
    val identifier: List<Identifier?>?,
    val status: String?,
    val type: CodeableConcept?,
    val category: List<CodeableConcept?>?,
    val date: Date?,
    val author: List<DocumentReferenceReference?>?,
    val description: String?,
    val context: DocumentReferenceContext?,
    val subject: DocumentReferenceReference?,
    val content: List<DocumentReferenceContent?>?,   <---- Binary data uri or the actual content will be inside
)

data class DocumentReferenceContent(
    val attachment: DocumentReferenceAttachment?,
    val format: Coding?,
    val status: String?,
)

data class DocumentReferenceAttachment(
    val attachment: String?,
    val contentType: String,
    val data: String?,
    val url: String?          <----- The binary resource id can be extracted
)

data class DocumentReferenceNarrative(
    val div: String,
    val status: String?,
)

Parameters

• category (SearchToken): Filters based on the category of the document reference
• ids (List<String>): A list of resource IDs to filter the search results.
• lastUpdated (SearchDate): Specifies a date filter for retrieving resources updated after a certain date.
• page (Int)
• pageSize (Int)

Special Features (e.g., Filters)

• Category Filtering: The category filter allows retrieval of documents based on specific categories. Example values that can be passed into the SearchToken code http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category.

🔜

Status Filtering: The status filter allows retrieval of documents with specific status. Different statusCode that can be used for filtering are

* kotlin current | superseded | entered-in-error

* Type Filtering: The type filter allows retrieval of documents based on specific document categories. Example values that can be passed into the SearchToken code https://build.fhir.org/ig/HL7/US-Core/ValueSet-us-core-documentreference-type.html.

* ContentType Filtering: The contentType filter allows retrieval of documents based on the content type of the attachment the document has.
eg: text/html | text/rtf

Example Usage

Kotlin

var request = DocumentReferenceRequest.Builder() 
.ids(listOf("document-reference-id-1", "document-reference-id-2")) 
.lastUpdated(
	SearchDate.Builder()
            .greaterThan(dateFormat.parse("2024-01-01"))
            .build()
)
.category(listOf(Coding(code = "clinical-note")))
.page(0)
.pageSize(20)
.build()

val result = BWellSdk.health.getDocumentReference(request)

getBinary Signature

The function which fetches the binary resources using the binary resource uri’s/id’s passed in.

Kotlin

suspend fun getBinary(request: BinaryRequest): BwellResult<Binary>

Return Type

BwellResult<> containing list of Binary. Type of Binary is described below

Kotlin

data class Binary(
    val id: String,
    val data: String,         <--- Base64encoded string
    val contentType: Code,
)

Parameters

* ids (List<String>): A list of resource IDs to filter the search results.
* page (Int)
* pageSize (Int)

Example Usage

Kotlin

var request = BinaryRequest.Builder() 
.ids(listOf("binary-id-1", "Binary/binary-id-2"))   <----- Binary resource id's
.page(0)
.pageSize(20)
.build()

WorkFlows

Getting Clinical Notes

The getDocumentReference request DocumentReferenceRequest enables users to apply filters based on the document reference category. By inputting "clinical-note" into the category, users can effectively isolate clinical notes from the comprehensive set of document references.

Kotlin

var request = DocumentReferenceRequest.Builder() 
.category(listOf(Coding(code = "clinical-note")))
.build()

val result = BWellSdk.health.getDocumentReference(request)

Handling Binary Attachments

The DocumentReference resource includes binary content in two ways.

1. Directly within the DocumentReference (within the resource). The content can be accessed within resource.content.attachment[0].data.
2. It can also reference an external binary resource, the ID of that resource can be extracted from resource.content.attachment[0].url.

Binary Content within the documentReference

The type of attachment[0].data will be a base64 string. The contentType of the data will be present inside attachment[0].contentType. The contentType indicates how the base64 data should be interpreted and rendered.

Kotlin

val result = BWellSdk.health.getDocumentReference(request)
val documentReference = result.data?.firstOrNull()

// Assumming that the document reference is present.
val documentReferenceAttachment = documentReference.content.first().attachment
val base64Data = documentReferenceAttachment.data
val contentType = documentReferenceAttachment.contentType?.code

Binary Content when referencing to a binaryResource

If the content is referenced to a binary resource, then the binary resource id can be extracted from attachment[0].url. This url can be passed into getBinary to retrieve the content. The binary resource received will also contain both contentType resource.contentType and the base64String data resource.data

Note: It’s recommended to trim the Binary/ part from the url property of the Binary Resource if present.
“Binary/1HVsE2R909H1R6UgPGU5QS2L5D|6NgPU” → “1HVsE2R909H1R6UgPGU5QS2L5D|6NgPU”

Kotlin

// Get the document reference
val result = BWellSdk.health.getDocumentReference(request)
val documentReference = result.data?.firstOrNull()

// Assumming that the document reference is present.
val documentReferenceAttachment = documentReference.content.first().attachment

// Trimming the `Binary/` if present.
val binaryResourceId = documentReferenceAttachment.url.removePrefix("Binary/")

val binaryRequest = BinaryRequest.Builder()
					.ids(listOf(binaryResourceId))
					.build()

val documentReferenceContent = BWellSdk.health.getBinary(binaryRequest)
val base64Data = documentReferenceContent.data?.firstOrNull().data
val contentType = documentReferenceContent.data?.firstOrNull().contentType

Getting author of the document reference

The Document reference object includes an author property that contains both the author's display name and reference. If the author.display is available, we can retrieve the author's name from this property. However, if it is not present, we must obtain and resolve the reference from author.reference.

Getting encounter details from the document reference

The encounter references are found within context.encounter. Each encounter reference includes a reference URI and a display name, which acts as the text alternative for the resource. This reference URI can be used in the getEncounters method to obtain the details of the encounter.

Kotlin

// Assumming that the document reference is present.
val documentReference = documentReference.content.first()

val encounterReference = documentReference.context?.encounter?.firstOrNull()

val encounterRequest = EncounterRequest.Builder()
.ids(listOf(encounterReference.reference))
.build()

val encounter = BWellSdk.heakth.getEncounters(encounterRequest)