The functionality was originally implemented in :task:`26014`. Definitions ------------ .. seealso:: FHIR `terminology module `_ .. glossary:: :sorted: LFPSE Learn from patient safety events FHIR Fast Healthcare Interoperability Resources (FHIR®) is a draft standard from Health Level 7 International (HL7) designed to allow the exchange of electronic health records. It is built upon previous standards such as HL7 version 2 and HL7 version 3, and uses XML and JSON for data representation. .. seealso:: `FHIR Summary `_ EHR Electronic Health Record LRMS Local Risk Management System OIR Online Incident Recording ODS Organisation code An ODS code (also called an Organisation code) is a unique code created by the Organisation Data Service within NHS Digital, and used to identify organisations across health and social care. ODS codes are required in order to gain access to national systems like NHSmail and the Data Security and Protection Toolkit. Profile The base FHIR specification creates a common foundation on which various different solutions are implemented. In order to document the specific requirements for a given system, a profile is created which specifies: * Rules about which resource elements are used or not used * What elements may be included that aren’t part of the base resource (extensions) * Rules about which terminologies are used for particular elements For example, the "LFPSE Adverse Event" profile will specify that an Adverse Event may include a "Never" Event type (an extension), and values for this field must come from a specific :term:`Value Set`. .. seealso:: For more information about profiles, refer to the FHIR documentation: https://www.hl7.org/fhir/profiling.html Snapshot defines :term:`Profile` structure as a self-contained list of all element definitions, including those inherited from the base resource. Differential Lists element definition components that are modified or added to the :term:`Profile` compared to its base resource or parent profile. It does not repeat unchanged elements. To get full picture (:term:`snapshot`), the differential items are added to the base resource's structure. Extension Extensions in FHIR allow you to create additional elements that do not exist in the base resource definition. A profile specifies which extensions are used by a system for a specific resource. If an extension relates to a terminology, it will usually specify a Value Set to use. For more information about extensions, refer to the FHIR documentation: https://www.hl7.org/fhir/extensibility.html Value Set Value Sets select a set of codes from one or more :term:`code systems ` to specify which codes can be used in a particular context. For more information about Value Sets, refer to the FHIR documentation: https://www.hl7.org/fhir/terminologies.html Code System A Code System is a master catalogue of a particular set of codes and their meanings. A code system consists of :term:`concepts `. For more information about Code Systems, refer to the FHIR documentation: https://www.hl7.org/fhir/terminologies.html Code System Concept An individual item, or value from :term:`Code System` Element type type of an element, defines its structure. This could be a primitive (string, boolean, date), or a complex data type (Codeable :term:`concept `, ``HumanName``, etc), or a reference to another :term:`FHIR` resource (Patient). Taxonomy The :term:`LFPSE` data model (schema), or “Taxonomy”, comprises a set of :term:`FHIR` resources which define all possible properties, or question responses, that are accepted in LFPSE. Binding Element's binding links a data element to a specific :term:`Value Set`. The binding can also specify strength: required only codes from specified :term:`Value Set` are allowed extensible codes from :term:`Value Set` preferred, but others are allowed. Resource .. epigraph:: From a clinical perspective, the most important parts of the :term:`FHIR` specification to understand are the Resources. Think of Resources as paper "forms" reflecting different types of clinical and administrative information that can be captured and shared. The FHIR specification defines a generic "form template" for each type of clinical information - so one for allergies, one for prescriptions, one for referrals, etc. FHIR data consists of repositories containing completed "forms" (resource instances). The resource instances describe patient-related information (such as demographics, health conditions and procedures) as well as administrative information (such as practitioners, organizations and locations). Some resources are infrastructure components used to support the technical exchange of information by describing what systems are able to do, defining allowed sets of codes, etc. FHIR repositories might be electronic health record (:term:`EHR`) systems, pharmacy systems, hospital information systems (HIS), etc. Some systems, such as clinical decision support engines, may expose FHIR interfaces even though they don't actually store any patient or administrative information themselves. Each Resource defines a small amount of highly-focused data. A single resource doesn't say very much, but a collection of Resources taken together creates a useful clinical record. Information systems map the actions that a user takes (look up patient records, make a note in their history, etc.) to operations on the relevant resources. -- `FHIR documentation `_ .. seealso:: `JSON Representation of Resources `_ Property A field in a :term:`resource`. Can contain a value of one of the supported `data types `_. Cardinality Minimum and maximum number of times the element (i.e :term:`property`) can appear in the instance (i.e. :term:`resource`). Submit Endpoint The API endpoint which is used to create, read and update LFPSE submissions. Taxonomy Endpoint The API endpoint used to read the :term:`taxonomy` of LFPSE forms. Model diagram --------------- Open the diagram in a new tab or window to expand .. uml:: ../../../lfpse.puml :caption: Hierarchy of LFPSE/FHIR components Further documentation ---------------------- Documentation :task:`26747` `LFPSE Service `_ `Developer documentation `_ Event / Form types ------------------ There are 4 form types, which correspond to types of patient safety events. * Incident (subforms: Incident details, patients) * Outcome (flat form) * Good Care (flat form) * Risk (flat form) Each of these form types has their own question set predefined by the ``question_flow.py`` file. Usage Guide ----------- Creating an LFPSE Backend ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :class:`~lfpse.models.LFPSEBackend` links an institution to either the development or production APIs. It also allows you to select the organisations which are relevant to an :term:`LFPSE` implementation. 1. Create the backend http://localhost:8000/meg-admin/lfpse/lfpsebackend/add/ .. note:: If creating a demo LFPSE environment (or one that isn't yet ready to go live), use the development endpoint for both the :term:`submit endpoint` and :term:`taxonomy endpoint`: https://psims-uat.azure-api.net/ .. list-table:: If going live, use the following :widths: 50 50 :header-rows: 1 * - submit endpoint - taxonomy endpoint * - https://beta-data.patientsafety.nhs.uk/ - https://developer.learn-from-patient-safety-events.nhs.uk/ 2. Use the "select organizations" feature to limit the number of NHS organizations that can apply to all forms linked to your backend. http://localhost:8000/meg-admin/lfpse/lfpsebackend/1/select_organizations/ 3. Add an organization to the backend: this is used to add "set_value" conditional logic in one of the organization fields of the incident form. Creating A New Form ^^^^^^^^^^^^^^^^^^^^^ 1. Create an audit form 2. Create a form link http://localhost:8000/meg-admin/lfpse/lfpseformlink/add/ 3. Use the django action ``Build LFPSE field links and questions`` to create the form fields. http://localhost:8000/meg-admin/lfpse/lfpseformlink/ This can also be used to update fields with new changes from the API. Updating questions ^^^^^^^^^^^^^^^^^^^^^^ 1. To update field links based on changes in the API, and update the associated custom fields use the following django action: "Build LFPSE field links and questions". This is a long running action as it pulls data from the taxonomy API. http://localhost:8000/meg-admin/lfpse/lfpseformlink/ 2. To update field links based on changes in the API, use the following django action: "Build LFPSE field links". This also pulls data from the taxonomy API. http://localhost:8000/meg-admin/lfpse/lfpseformlink/ 3. To update custom fields based on changes in the ``question_flow.py`` file or taxonomy use the following django action: ``Build LFPSE questions``. This doesn't communicate with the taxonomy API. http://localhost:8000/meg-admin/lfpse/lfpseformlink/ Data sources ------------------- Taxonomy API ^^^^^^^^^^^^ * url: ``/taxonomy/fhir`` * read only API * Describes the properties of a patient safety event. See the attached postman collection for some common requests used to interact with the API. * Each property can be a form field in MEG (if defined in the question flow). * In version 5, this API is somewhat lacking. It doesn't contain help text, labels or required. This information must be imported from two separate spreadsheets located in :file:`/meg_forms/audit_builder/lfpse/data`. There is also a lot of useless irrelevant information in the API which must be ignored. * ``LFPSEFieldBuilder`` creates a ``LFPSEFieldLink`` for each property in the API. .. figure:: img/lfpse-sequence.png The diagram illustrates the order in which requests must be made in order to build a full picture of the LFPSE FHIR conformance resources. A client must be able to access all of the conformance resources in order to build a compliant Adverse Event resource. Taxonomy spreadsheets ^^^^^^^^^^^^^^^^^^^^^ * Two separate spreadsheets provide data on help text, labels, show in app and required. * These are located in :file:`/meg_forms/audit_builder/lfpse/data` * When building questions, this data is imported via pandas. Question flow chart ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * This defines the questions available in the Taxonomy API which should be shown to users, and in what order. * It's a pdf document with series of separate flow charts. * This is translated into python in ``audit_builder.lfpse.question_flow.py``. * Any changes to the question flow in subsequent version should be mirrored in ``question_flow.py`` LFPSE Go Live Procedure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This describes the process of migrating an LFPSE environment from the development API to the production APIs. Once complete the customer will be able to submit LFPSE data to the production API. 1. Confirm that the :term:`ODS` code of the institution used in the :class:`~lfpse.models.LFPSEBackend` is correct. This can be confirmed by the client. If incorrect submissions may be rejected automatically by the submit API. 2. Instruct the client to update their :class:`~lfpse.models.LFPSEBackend` token in the user facing dashboard settings page. This can be found here: http://localhost:8000/test-institution/dashboard/settings/lfpse-backends .. note:: This link is different for every institution. .. note:: According to the LFPSE team, the token is private and can not be shared with the integration software provider (MEG). For this reason the client must insert it themselves. 3. On django admin, change the :term:`submit endpoint` to: https://beta-data.patientsafety.nhs.uk/ 4. And change the :term:`taxonomy endpoint` to: https://developer.learn-from-patient-safety-events.nhs.uk/ 5. For each form link, run the following django admin action: ``Build LFPSE field links and questions``. This can be found at this page: http://localhost:8000/meg-admin/lfpse/lfpseformlink/ 6. Inform the client that the LFPSE environment is live and that they can start submitting data.