Clinical

Clinical is where all clinical work is recorded such as billable-records, clinical notes and other clinical related records such as documents on a patients history.

Clinical in Merlin?

Clinical is also known as the Treatment screen in Merlin, this is where all work is logged for the patients treatment.

Entities within Clinical

1. Billable Records - Chargeable work
2. Clinical Notes
3. Clinical Records
4. Modalities - Future
5. Vital Metrics
6. Referrals - Future
7. Prescriptions

Relationships

The clinical domain will reference other domains, such as Contact for Practitioners, Patients, Formulary, Inventory for batch records, and Billing for references to submit billable records.

Related Limitations

1. Billable materials must use formulary records, currently this cannot use ad-hoc charges
2. Some entities are not currently available, marked as Future above.

---

Clinical Schema

Please take note of the following points for this schema:

1. Invoice-Number Is only unique within the Tenant-Id, this is generated upon creation.
2. Donations can only be used on tenants for charity's.
3. Payments can be allocated at the time of recording, currently this cannot be done afterwards.

What are ...

1. Billable Records? - These are all records being submitted to the clinical record which require additional processing for billing.
2. Clinical Notes? - These are notes written by practitioners, these follow the Protocol structure and have specific configurations.
3. Clinical Records? - These are all other clinical work that needs to be recorded, such as lab requests, imaging references, documents, ad-hoc note.

How do Clinical Notes work?

Clinical notes have a series of relationships which may be used to create a more complex series of questions for the practitioner to work through.

Where relationships exist, these are used in the validation of the POST clinical-notes so it is important to ensure that the correct options are provided, e.g. answer is allowed for the question.

Relationships

1. Protocols - The header providing a list of protocols to follow for various situations.
2. Protocol Questions - Groups the available questions into a protocol and defines what is expected of this question when answering, e.g. mandatory fields or methods of answering (free text, clinical codes, or selectable answers).
3. Questions - A predefined list of questions.
4. Question Answers- Linking the library of answers to questions.
5. Answers - A predefined list of answers.
6. Clinical Codes - A predefined list of clinical does such as VeNOM.
7. Clinical Code Category - A grouping of Clinical Codes to help filter the allowed list of codes.

erDiagram Protocol ||--|{ ProtocolQuestions : contains ProtocolQuestions ||--|| Questions : assigned ProtocolQuestions o|--|{ ClinicalCodes : assigned Questions ||--o{ Answers : assigned ProtocolQuestions { bool allow-free-text bool allow-clinical-codes bool answer-mandatory bool answer-mandatory-clinical-code bool answer-mandatory-free-text uuid clinical-code-category }

Submitting a Clinical Note

When adding a clinical note you should follow this checklist:

1. Submit the entire protocol in a single POST
2. If a question has mandatory-answer it must be provided, otherwise it can be skipped.
3. If a question has answer-allow-free-text entry then an entry is expected but not required unless answer-mandatory-free-text is also true.
4. If a question has answer-allow-clinical-codes it is expected, but not required unless answer-mandatory-clinical-code is also true.
5. If a question has a clinical-code-category-uuid then the provided clinical-code-uuid must be within that category.
6. If a question have answers assigned, any provided answer-uuid must be within the assigned list.

Vital Metric Specifics

Currently Vital metrics are limited to Patient Weight.

The system records the weight in KG (Kilograms).

How to Billable Records work?

POSTing to the billable-records endpoint will do 2 things:

1. Adds a record to the patient's clinical history.
2. Adds a record to the Billing as a draft-invoice.
3. Adds movement of inventory.

Extra Datapoints

Referral UUID's referenced in the billable-records endpoint are not currently available.

How do we add Text notes?

Through the API you can add a text notes to the clinical history without needing to use the entire Clinical Note protocol schema; To do this you have 3 options:

1. Uploading a document
2. Text Entry
3. Single text Entry with URL Link

Uploading a Document

To add a document to the clinical history first upload the document(s) to the /documents/upload endpoint in the communication domain.

Afterwards you use the document-folder-uuid returned in the /clinical-documents endpoint to link the document to the clinical history of the patient.

More information about document uploads available in the Communication & Document Domain documentation.

Ensure that the clinical-description has something meaningful to the user for quick identification of the document and its source. e.g. Signed Consent Form for Neuter from AmazingVetDocs.

Single Text Entry

If your aim is to just add a single entry to the clinical history of a patient then use the /clinical-integration-notes endpoint.

This endpoint can take up to 7000 characters for the clinical-description field, however for readability and portability consider using a document or breaking up into multiple entries if you are submitting more than a few hundred characters.

Clinical notes are usually displayed in datetime order, consider adding a second of time to each additional note to order through the clinical-date field.

Single Text Entry with URL Link

If you need to submit an entry to the clinical history while also referencing an external document, web app or reference materials then you can use the /clinical-external-url endpoint.

For the clinical-description field ensure you place something meaningful and descriptive for the clinical entry, such as 'Link to Clinical Whiteboard for Neuter' for the practice user that will described what it is, and also where it will take them.

The external-url field is the permanent link you will provide to the information. Note, Only HTTPS is permitted.

The following 2 fields are displayed to the user if your external-url domain is not in the Merlin safelist, so ensure that this information is also supplied. If the domain is not in the safelist a warning prompt with this information is shown.

1. external-url-provider - The name of your business and/or system.
2. external-url-content-description - A quick description of the content the user may be navigating to.

Cross Domain UUID References

Reference	Domain	Resource	Note
location-uuid	location-management	/locations	Location, e.g. work location.
location-space-uuid	location-management	/locations/:uuid/spaces	Space the item was used from, e.g. stock location.
contact-uuid	contact-management	/contacts	Identifies the individual person.
patient-uuid	patient-management	/patients	Identifies the specific patient.
formulary-uuid	formulary-management	/services, /stock	Identifies the formulary configuration used to create the work.
appointment-uuid	calendar-management	/appointments	Identifies the appointment work was recorded with.
practioner-uuid	contact-management	/contacts, /practitioners	Identifies the Practitioner who recorded the work.
legal-entity-uuid	location-management	Not Yet Available	Identifies the practices legal entity.
document-folder-uuid	communications	/documents/upload	Specifies a group of files to be associated on a patient history.

Security Scopes

The following authorisation scopes are required to access different resources within this domain:

• clinical:metrics:read
• clinical:metrics:create
• clinical:metrics:remove
• clinical:history:read
• clinical:history:create
• clinical:history:update
• clinical:history:remove
• clinical:​notes:read
• clinical:​notes:create
• clinical:​notes:update
• clinical:​notes:remove