Communications and Document Management

This domain is an entity which holds the history of external communications, including all documents that are generated by the system such as consent forms, medical history, emails, etc.

Communications in Merlin?

Communications logs exist within the reception screen of Merlin, these are any communications sent that are related to a contact.

Documents in Merlin?

Documents exist throughout the system from administration (templates), to documents stored on the client (reception) and patient history (treatment).

Entities within Communications and Documents

1. Communication Channels
2. Communication Types
3. Templates
4. Documents
5. Communication Logs

Relationships

Documents and templates will be referenced to from across the domains for configuration and for historical records.

Communication Channels and Types will be referenced to by contacts for preferences and used for sending communications.

Related Limitations

1. Historical records will reference a document-folder not the document directly. Therefore it is possible that a historical record will return multiple files.
2. Templates are referenced directly if they are linked to a specific entity such as Formulary records.

---

Communications and Documents Schema

Please take note of the following points for this schema:

1. Template type ENUM Templates have an ENUM type for their intended purpose and should not be used for cross purposes due to mail merge field validation.
2. Template locations Templates that are assigned to the main location are available for all locations, and any assigned to other locations are only available at these locations.

Document Uploads

To upload a document to the Merlin PMS the use of the documents/upload endpoint will store the document and create a record for it within the management system. Documents are uploaded as a stream through the API with other meta data in the payload body.

If you have multiple files to be kept together (grouped) for a single entry on a clinical history for example, then use the returned document-folder-uuid from the first upload in the payload for subsequent files.

The response from the endpoint must be used with other endpoints to associate the document with those entities, currently (as of May 2023) this is only possible with patients clinical history, and communication logs. This will be used with clinical-documents to append the document-folder to clinical history.

info

Only certain files types will be accepted by the system; typically images, pdf's and other office document formats are accepted.

Upload Steps

1. Submit entry with document stream to communications service: documents/upload
2. Take document-folder-uuid from response. Upload related documents with document-folder-uuid.
3. Take document-folder-uuid and associate with an (one) entity:
   1. Clinical domain: POST clinical-documents; Provide UUID in the payload with other required data.
   2. Communication domain: POST communication-logs; Provide UUID in the payload with other required data.

data object for file upload

When uploading the file to the API the data object schema requires a combination of the following fields:

EITHER add to an existing folder:

1. document-folder-uuid
2. document-filename

{
    "document-filename":"TestFilePDF.pdf",
    "document-folder-uuid": "48579f69-aa82-447a-b4f5-1358e1064102"
}

OR to add a new folder:

1. document-folder-description
2. document-filename

{
    "document-filename":"TestFilePDF.pdf",
    "document-folder-description": "New Folder"
}

The document-folder-location-uuid is not required in any situation, but will correctly identify the owning location of the documents. This can only be set when creating a new folder.

Template ENUMs

The tables below give a quick explanation of each enum on the template entity and how they should be applied.

Status ENUM	Note
TEMPLATE_AVAILABLE	This template is currently issued and is available for general use (generation).
TEMPLATE_EDITING	This template is not available for use, the document administrator has withdrawn or is currently waiting to publish.

Type ENUM	Note
ACCOUNT	This template is only be used in context of the Account and the associations of Contact, Location and Patient. This is recorded against the account.
DEBT-CHASE	This template is only to be used for chasing outstanding billing balances.
FORMULARY	This template is to be used when a formulary item is being used during clinical work.
CLINICAL	This template is available to be used by a user on a ad-hoc basis and recorded against the clinical history.
PRESCRIPTION	This template is used to create a written prescription, this is recorded against the clinical history.
CONSENT	This template is used to generate consent forms, this is recorded against the clinical history.
MARKETING	This template is used for marketing/awareness purposes, such as targetted campaigns.
REMINDER-PATIENT	This template is used for patient reminders such as annual vaccinations.
REMINDER-TREATMENT	This template is used for treatment (compliance) reminders, such as monthly flea application.
REMINDER-APPOINTMENT	This template is used for appointment reminders.

Communication Log Searching ENUMs

The communication logs allow you to use different search operations and search upon different fields, but only 1 of each at a time.

example

search-operation = contains , search-field = content-recipent , search-term = @mwiah.co.uk

The following search operations are available:

• EQUALS (default)
• CONTAINS
• ENDSWITH
• STARTSWITH

The following fields are available to be searched

• CONTENT-RECIPIENT
• CONTENT-DESCRIPTION
• CONTENT-MESSAGE (default)
• LOG-ENTRY

Cross Domain UUID References

Reference	Domain	Resource	Note
location-uuid	location-management	/locations	Location, e.g. work location.
contact-uuid	contact-management	/contacts	Identifies who was messages where sent to.
patient-uuid	patient-management	/patients	Identifies the specific patient.

Security Scopes

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

• comms:read
• comms:create
• comms:update
• comms:delete
• comms:logs:read
• comms:logs:create
• document-mgt:templates:read
• document-mgt:templates:create
• document-mgt:templates:update
• document-mgt:templates:remove
• document-mgt:templates:download
• document-mgt:templates:upload
• document-mgt:docs:read
• document-mgt:docs:create
• document-mgt:docs:update
• document-mgt:docs:remove
• document-mgt:docs:download
• document-mgt:docs:upload