Solution description –
General Notes Service
in Cosmic
For RSD
This document describes solution for the general notes service
20-1-2014
Contents
1.
Introduction ............................................................................................................................................... 2
1.1
Identification of need ........................................................................................................................ 2
1.2
Overview ............................................................................................................................................ 4
1.3
Out of scope ...................................................................................................................................... 5
1.4
Assumptions ...................................................................................................................................... 6
1.5
Business Advantages ......................................................................................................................... 6
2. Supporting documentation ....................................................................................................................... 6
2.1
Abbreviations, definitions and terms ................................................................................................ 6
2.2
References ......................................................................................................................................... 6
2.3
Revision History ................................................................................................................................. 6
3. Requirements ............................................................................................................................................ 7
3.1
Requirement matrix .......................................................................................................................... 7
3.2
Architectural and technical consideration ........................................................................................ 7
4. Solution description and design ................................................................................................................ 8
4.1
Integration description ...................................................................................................................... 8
4.2
Service methods .............................................................................................................................. 10
4.3
Mappings and other information .................................................................................................... 15
4.3.1
Note templates (for RSD use) .................................................................................................. 15
4.3.2
Supported Nøgleord, værdiset (for RSD use) ......................................................................... 15
4.3.3
XML .......................................................................................................................................... 15
4.4
Pre-conditions for the solution........................................................................................................ 15
4.4.1
To find note templates in Cosmic corresponding to the third-party systems......................... 15
4.4.2
To find nøgleord corresponding to the nøgleord used in the thirdparty system.................... 15
4.4.3
To identify contact or forløb.................................................................................................... 15
4.4.4
To connect to enhed ................................................................................................................ 15
4.5
Maintenance requirement .............................................................................................................. 16
4.6
Flow diagrams.................................................................................................................................. 16
5. Acceptance criteria .................................................................................................................................. 17
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 1 af 17
1. Introduction
1.1 Identification of need
There is a need to make a notes service in Cosmic which can give possibility to transfer notes to Cosmic
from different external systems. The service should be generic enough to cater to the needs of various
systems like SharedCare, Endobase etc with minor changes. The below picture shows an example how is
the workflow today with respect to Endobase.
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 2 af 17
Current workflow example
Henvisende og modtagende afdelinger
(COSMIC PAS)
Kirurgisk afdeling (Endobase)
Start
Patient henvist registreres i
COSMIC PAS
Patient opprettes manuelt
Patient bookes
Sygeplejedokumentation inkl.
Medicin og blodtryk udfyldes
Læge udfører undersøgelse og
udarbejder lægenotat
Læge og sygeplejenotat indsættes i
Cosmic journal
Sekretær kopiere læge- og
sygeplejenotat
Læge og sygeplejenotat indsættes i
Cosmic journal
End
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 3 af 17
Figure 1 – Flow diagram – current workflow example
1.2 Overview
There are notes written and saved in various external systems. The purpose of this service would be to
transfer them to Cosmic automatically as soon as they are signed in the external system. However, it is the
external systems who decide when the notes should be sent to Cosmic. So, they can choose to transfer the
note when it is in draft status as well. The important part of this service is to identify which kontakt or
forløb a note should be attached to. It should be also validated in Cosmic whether a note should at all be
attached to a kontakt or forløb in Cosmic. The general idea is to make this general note service and adjust it
for specific third-parties as and when needed. General note service is developed as a webservice.
Others..
CIS
Endobase
SharedCare
General Notes Service
Figure 2: Development model for the notes service
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 4 af 17
Figure 3 – proposed workflow with General Notes Service
1.3 Out of scope
This document does not describe how the notes which are transferred to Cosmic from external systems are
shown on screen. One proposal could be to create specific filter for each thirdparty system and display the
notes sent from that external system within that filter. For example, filters like ‘All endobase notes’, ‘all
SharedCare notes’ etc can be created on the screen. These notes should also display normally in folders
where they should display if they were manually created – f.x. in folder - all notes etc. However, these
requirements will be detailed in thirdparty-specific integration documents.
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 5 af 17
1.4 Assumptions
The external systems will decide which notes should be transferred to Cosmic.
Once the note is transferred, all operations will be applicable to it as they are in notes created manually in
Cosmic.
1.5 Business Advantages
Functionality
Automatic transfer of notes from a
third-party system
Advantage to the customer
Avoids double entry of data (copy paste) to save time and effort
Avoids errors related to forgotten or incorrect copy paste
2. Supporting documentation
2.1
Abbreviations, definitions and terms
Word
SHS
Endobase
SharedCare
CIS
Commitment
2.2
‘Commitment’ is same as Forløb in Cosmic
References
Document name
Løsningsforslag til
integration med
Endobase
Detailed
documentation about
web services
2.3
Description
Sygehus Sønderjylland
Endobase is a system where description and pictures from an endoscopic
examination can be uploaded
SharedCare is a system which acts as a common platform for Hospital,
Kommune and GP to co-operate in cases of chronicle diseases
Location
A410.825
A410-00242-23_Webservice documentation
Revision History
Changed date
05-04-2013
19-04-2013
15-07-2013
09-09-2013
20.01.2014 A405-00445-12
Change description
First draft created
Added review comments
and added new text
marked with yellow
Small corrections based
on customer input
Several minor corrections
based on final
implementation:
Error! Unknown document property name.
Changed by
Khushboo Verma
Vivi Petersen
Status
Draft
Draft
Khushboo Verma
Approved
Nicolai Buch-Andersen
Draft
Side 6 af 17
Page 10: Patient type
codes are returned as
integer codes, as defined
in Fællesindhold.
Page 11: Updated the
description of the return
type for the
getCosmicCommitments
method to include all the
fields in the returned data
structure.
Described the behavior of
the deleteNote service in
more detail.
Reviewed and updated
references to contain
web service document
Updated
createNonExistentCPR to
include a condition about
‘-‘
Updated scenarios for
createNonExistentCPR in
chapter 4.2.3
13-11-2013
28-11-2013
20-01-2014
Khushboo Verma
Approved
Khushboo Verma
Approved
Khushboo Verma
Approved
3. Requirements
3.1
Requirement matrix
Requirement
reference
Meeting 20-032013
3.2
Description
Comments
Meeting with
customer
Requirement clarification and understanding
Architectural and technical consideration
The note service has to be as generic as possible in order to cater to many third-party systems with minor
adjustments. A general note service will be implemented with some limitations and some requirements to
the external systems. All external systems which fulfill the requirements and can do with the limitations can
use this service. If not, it will be possible to enhance the solution in future. Examples of possible
enhancements could be - A new configuration tool as mentioned in the Endobase baseline document
- Support for other keyword tool types
- Other ways to search for existing contacts and commitments in Cosmic when creating the journal note
- Possibility to create new contacts and commitments when creating the journal note in Cosmic
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 7 af 17
4. Solution description and design
4.1
Integration description
External system sends note for a
patient to Regis in form of HL7 or any
format when the note is ready to be
transferred to Cosmic
Regis transforms it to a message that
Cosmic understands in order to create
notes
Note is validated and created in
Cosmic and attached to the patient
with identified Unit and (Forløb or
Kontakt or none).
Figure 4: Integration overview - External systems to Cosmic
The message that is sent to Cosmic from Regis must contain the following information
-
-
The patient’s CPR number
The content of the note
Information needed to create the note in Cosmic: Journal note unit, status of the note in Cosmic,
display date time in Cosmic
If the journal note should be connected to a contact and/or a commitment in Cosmic, then the XML
should contain information that enables Cosmic to find the contact and commitment. The contact
can be specified by a Cosmic contact id. The commitment can be specified either by a Cosmic
commitment id or by a responsible unit and a date. If possible then the external system should use
the Cosmic ids. The Cosmic ids can be obtained in the following ways:
o By using the web services getCosmicContacts and getCosmicCommitments as mentioned in
Figure 3. These web services returns a list of contacts or commitments and the external
system or the user of the external system must then choose the right contact or
commitment.
o By listening for commitments and contacts published by Cosmic. Cosmic publishes the
contacts and commitments on message queues whenever they are changed in Cosmic.”
The id of the journal note in the external system. Cosmic uses this id to identify updates and
deletes of journal notes. It is important that this id is accompanied by an Id for external system as
well to maintain uniqueness.
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 8 af 17
The information about who created and signed the note in the external system can be saved in Cosmic as a
keyword on the journal note. This requires that the note template in Cosmic contains a keyword for this,
and that the information about the user is sent to Cosmic in the same way as all other keywords.
All unit identifier should be SOR codes and if the third-party system is not able to send SOR codes but only
e.g. SKS codes, then Regis should map the SKS code to the corresponding SOR code. Similarly Regis should
map other information. For example Regis should map the journal note keywords from the external system
to the keywords in Cosmic.
The XML also contains the note id from the external system and Cosmic will generate its own note id after
the note is created in Cosmic. The two identifiers should be mapped in a table in Cosmic for book keeping.
When a note is sent with a note id, it should be looked up in the table and if the note id exists in the table,
it means that the note has to be updated in Cosmic. If the noteId is not found in the table, it means that it is
a new note and should be created in Cosmic. The thirdparty systems can also chose to delete a note which
is already transferred to Cosmic by providing the note id and calling the ‘Delete’ method.
It is a push integration where the third-party systems will call Cosmic general notes service when they are
ready to transfer the notes (for example, when the notes are signed). The steps for integration at Cosmic
side in the general notes service are as below–
Validate
Identify
Create/
Delete/Update
•Validate if there is a matching tempalte for the incoming note
•Validate if all nøgleord, nøgleordsværktøj and værdiset are compatible
•The enhed to which note should be attached exists in Cosmic
•Validity of data is verified
•Identify whether the note should be connected to a kontakt, forløb or only to enhed from the message.
•Identify which kontakt or forløb to connect to based on contactId or ForløbId provided in the message.
•If forløbId is not prvided, the forløb should be identified by information like ansvarligenhed and date and if
Cosmic finds one forløb the note is attached to it, else an error is sent
•Create, Delete or Update the note corresponding to the patient with identified contact, forløb or unit in
Cosmic
•In case of Create, map the external identifier to the Cosmic note identifier in the mapping table. In case of
delete, remove the mapping from th e table.
Figure 5 – General notes service in Cosmic
The external system should decide what should be the status of note after it is created in Cosmic. It could
be either draft or signed. In both cases, there should be a keyword in Cosmic note template to store
username who created or signed the note in external system. We send positive receipt back when the
operation (create, delete or update) is successful. An error (negative receipt) is sent if it fails.
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 9 af 17
4.2
Service methods
4.2.1 getCosmicContacts
Method to identify kontakts based on parameters given in the message by external systems.
Input parameters:
Parameter
Cosmic user and
password
CPR number
SOR code for
responsible unit
startDate
Mandatory
(M) or
optional (O)
M
M
O
Description
The user name and password are
set as authentication when
calling the web service.
Requirements (if not
fulfilled then we return an
error)
The user must exist in
Cosmic with the given
password.
If specified only contacts with
this responsible unit are returned
If specified only contacts starting
after the specified date is
returned
O
The method returns all (non-invalidated) contacts which satisfy the search criteria given by the input
parameters.
Other possible candidates for input parameters are “status” for limiting the results to contacts with a
particular status, or set of statuses and “type” for limiting the results to a particular type of contacts. These
extra parameters will not be part of version 1, but can be added later, if requested.
Output parameters:
Parameter
CPR number
Cosmic contact id
Patient type
Mandatory (M)
or optional (O)
M
M
M
Responsible unit (SOR code)
Start date
End date
CommitmentId
M
M
O
M
CommitmentName
M
Description
The patient type as an integer code, as defined in
Fællesindhold:
Indlagt: 0, Ambulant: 2, Skadestue: 3
The Id of the Cosmic commitment associated with
this contact
The name of the Cosmic commitment associated
with this contact
Other possible candidates for output fields are “performing unit (SOR code),” “Cosmic status” and “Cosmic
contact type.” These extra attributes will not be part of version 1, but can be added later, if requested.
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 10 af 17
4.2.2 getCosmicCommitments
Method to identify forløb based on parameters given in the message by external systems. The parameters
could be date, henvisningsmåde, forløbsansvarlig enhed etc.
Input parameters:
Parameter
Cosmic user and
password
Mandatory
(M) or
optional (O)
M
CPR number
SOR code for
responsible unit
M
O
Date
O
Status
O
Description
The user name and password are
set as authentication when calling
the web service.
Requirements (if not
fulfilled then we return an
error)
The user must exist in
Cosmic with the given
password.
If specified only commitments
with this responsible unit are
returned
If specified only commitments
starting after the specified date is
returned
If specified, it should be possible
to fetch commitments with a
particular status
The method returns all (non-invalidated) commitments which satisfy the search criteria given by the input
parameters.
Other possible candidates for input parameters are “status” for limiting the results to commitments with a
particular status, or set of statuses and “commitmentName” for limiting the results to particular types of
commitments, for example “Audiologisk forløb.” These extra parameters will not be part of version 1, but
can be added later, if requested.
If more parameters are added to the service, it is recommended to introduce a separate class to hold all the
parameters, called CommitmentFilter (for example). This class could then be re-used as a parameter in the
createOrUpdateNote method, which will give the createOrUpdateNote method the full search flexibility of
getCosmicCommitments, but without polluting the method with many extra search-related parameters.
Output parameters:
Parameter
Cosmic commitment id
Cosmic Commitment name
CPR number
Responsible unit (SOR code)
Patient Family Name
Patient Given Name
Begin date
20.01.2014 A405-00445-12
Mandatory (M)
or optional (O)
M
M
M
M
M
M
M
Error! Unknown document property name.
Description
Side 11 af 17
End date
Reason for termination
Referral Id
Referral Date
Referral Way
Referral Diagnosis
Referral Diagnosis Description
Referral Physician Name
Referral Unit
O
O
M
M
M
O
O
O
O
4.2.3 CreateOrUpdateNote
If the note id is unknown to Cosmic, a new note is created. If note id is known, the note has to be edited.
Input parameters:
Parameter
Cosmic user and
password
Mandatory
(M) or
optional (O)
M
Description
The user name and password are
set as authentication when calling
the web service.
External system
External id of the
journal note
CPR number
M
M
Cosmic contact id
O
If given then we couple the
journal note to the contact
Cosmic commitment id
O
If given then we couple the
journal note to the commitment
Responsible unit and
date for commitment
O
If given then we search for
Commitments belonging to the
patient, which has the required
responsible unit, and are open on
the required date. If we find
exactly one commitment then we
couple the journal note to this
commitment, else we return an
error
20.01.2014 A405-00445-12
M
Error! Unknown document property name.
Requirements (if not
fulfilled then we return an
error)
The user must exist in
Cosmic with the given
password.
If the journal note should
be coupled to a contact or a
commitment, then the
patient must exist in
Cosmic.
The contact must exist in
Cosmic, it must not be
invalidated, and the it must
belong to the patient given
by the CPR number
The commitment must exist
in Cosmic and it must
belong to the patient given
by the CPR number
The search criteria must
result in exactly one
commitment
Side 12 af 17
Template name
M
Journal unit (SOR code)
M
Journal date time
Status (signed/draft)
M
M
List of Keywords with
name and value
M
CreatenonexistentCPR
O
Cosmic name of the journal
template
Should the journal note be signed
or saved as draft?
Cosmic names of the keywords
The note should have to be
attached to CPR
The template must exist in
Cosmic
The unit must exist in
Cosmic
The keywords must exist in
Cosmic and belong to the
template. The value must
be of the same type as the
type of the keyword tool.
The keyword tool must be
one of the supported tools.
To indicate if a patient
needs to be created if it
does not exist in Cosmic
and note is to be attached
with the CPR
Scenarios related to CreateNonExistentCPR
1. Patient does not exist in Cosmic but exists in Regis – The patient is created in COSMIC with data
from REGIS and the note is attached to that patient (CPR)
2. Patient exists neither in Cosmic nor in Regis – An error is logged from the CPR-component and a
warning is logged from GeneralNotesService saying that the patient could not be found in REGIS.
Then the service will attempt to create a ‘minimal’ patient in COSMIC. If successful, then the note is
created and attached to the new minimal patient. If the service fails to create a patient in COSMIC
then the service returns the error message ‘Kunne ikke oprette patient med CPR-nummeret XXX’
and the note is not created.
3. Patient exists in Cosmic – Just ignore the request for creating the patient and attach the note to the
existing COSMIC patient
4. Regis is not available – Same as scenario 2
The CPR number should not contain ‘-‘ in this request specially when createNonExistentCPR = true because
the CPR component accepts only 10 characters in CPR number field.
Create or Update?
If we have previously successfully received a message with the same external system and external id, then
we update the journal note instead of creating a new one. Else we create a new note. In updates we update
the keywords on the journal note, status and journal date time.
Output parameters:
Parameter
Status
Error message
20.01.2014 A405-00445-12
Mandatory (M)
or optional (O)
M
O
Error! Unknown document property name.
Description
Success/Error
When failing, we return an error message
Side 13 af 17
describing the error
Supported keywords types –
Nøgleordsværktøj
Checkbox
Clinical coding
Dato og tid
Faste værdier
Fritekst
Numerisk
Register
Værktøj til ekstern links
Supported (Yes or No)
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
4.2.4 Delete Note
If the delete method is called with a known note id, the note is identified in Cosmic and deleted. If the note
was unsigned, the note is gone forever and will not appear again in the COSMIC client. If the note was
signed, however, the note is invalidated. It will still appear in the Cosmic client, marked as invalidated, and
the reason for invalidation will state that the note was deleted by the General Note service.
Input parameters:
Parameter
Cosmic user and
password
External system
External id of the
journal note
CPR number
Mandatory
(M) or
optional (O)
M
Description
The user name and password are
set as authentication when calling
the web service.
Requirements (if not
fulfilled then we return an
error)
The user must exist in
Cosmic with the given
password.
M
M
M
The journal note must
belong to this patient
If we cannot find a journal note with the given external system and external id in Cosmic we return an
error.
Output parameters:
Parameter
Status
Error message
Mandatory (M)
or optional (O)
M
O
Description
Success/Error
When failing, we return an error message
describing the error
Other?
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 14 af 17
4.3
Mappings and other information
4.3.1 Note templates (for RSD use)
Third-party system
Note templates to be supported
4.3.2 Supported Nøgleord, værdiset (for RSD use)
Nøgleord i notat skabelon
Nøgleordsværktøj
4.3.3 XML
XML field from thirdparty system
4.4
Field type/ document
attribute
Værdiset
Description and validation
Pre-conditions for the solution
4.4.1 To find note templates in Cosmic corresponding to the third-party systems
All note templates that are to be transferred to Cosmic should be created in Cosmic else the system will
throw an error saying – ‘ unidentified note template’ and integration will fail
4.4.2 To find nøgleord corresponding to the nøgleord used in the thirdparty system
All keywords that can be sent to Cosmic from external system should be defined in Cosmic templates.
However, Cosmic template can have extra keywords which are not sent from external systems. If the
keywords have different names in the third-party system and in Cosmic, then either the third-party system
or Regis must map the keywords to the keywords in Cosmic. Two free text keywords in the third-party
system can be mapped to one keyword in Cosmic. The value set should be identical and nøgleordsværktøj
should not contain unsupported elements like attached documents, dynamic nøgleord etc.
4.4.3 To identify contact or forløb
A valid contactId or CommitmentId is provided if the note is to be attached to a contact or a forløb for a
given CPR number. It is also possible to find forløb based on responsible unit and date.
4.4.4 To connect to enhed
Cosmic should know SOR code for units which are going to send the notes. Also a dummy user (system
user) should be created for each of these external systems so that the notes can be signed in the name of
these dummy (system) users.
In general, all data requirements mentioned in chapter 4.2 should be met for the integration.
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 15 af 17
4.5
Maintenance requirement
In case of change in notes template in third-party systems – The corresponding notes in Cosmic should be
made if there is a change in template of notes which are used in this integration.
In case of change of templates in Cosmic – It should be advised to the users that note templates which are
used in integration should not be changed. This can be done by making a naming convention to identify
such note templates which should not be changed.
4.6
Flow diagrams
Flow diagram for cases
Start
CreateOrUpdate
Note
NoteID matched
in mapping table
No
Yes
Abort and send
error message
No
Perform
validations
Data validated?
Not
OK
Abort and send
error message
OK
Yes
Identify contact or
forløb
Update note
Contact/ Forløb
status?
Contact Open,
Closed or Forløb
open, closed
Create note
Contact
Makulere
de
Abort and send
error message
Figure 6: flow diagram – CreateOrUpdate
20.01.2014 A405-00445-12
Error! Unknown document property name.
Side 16 af 17
Start
Delete Note
NoteId found in
mapping table
Yes
No
Validate CPR
number and Delete
note
Abort and send
error
Figure 7: Flow diagram - Delete
5. Acceptance criteria
TestScenarioId
1
2
3
4
5
Test scenario description
It should be possible to transfer notes from
external systems provided all configurations are
done correctly
It should be possible to see the notes in Cosmic
client
It should be possible to edit an already transferred
note to Cosmic
It should be possible to delete a transferred note
It should be possible to create a patient based on
input parameters and attach a note to it
20.01.2014 A405-00445-12
Error! Unknown document property name.
Status (to be filled by developer)
Side 17 af 17