HealthShare Personal Community Patient Entered Data Setup Guide
1. Introduction
This guide is intended to be a resource for understanding the setup of Patient Entered Data features of Personal Community in HealthShare
2. Overview
If there is information that an organization wants to collect from the patient prior to service, patients can receive a notification that they have a task to complete, and then complete it within Personal Community.
Patients with tasks to complete will see these tasks in their To Do box on the Home page. This box will list any pre-service tasks items such as documents, and any outstanding HealthShare Care Community care plans. Patients can access their pre-service tasks, or care plans as requested, and submit them back to their care team.
3. Patient Contributions to HealthShare Care Community
3.1. Configuring HealthShare Care Community for Patient Contributions
Please use the following link for detailed guidelines: Configuring HealthShare Care Community for Patient Contributions
3.2. Configuring Personal Community for Patient Contributions
Note
Use of this feature requires that viewing care plans are enabled
3.2.1. Creating the Service Registry on Unified Care Record for Care Community Care Plan
- Logon to the Management Portal as a user with the %HS_Administrator role.
- Select HealthShare from the main menu.
- Select the Unified Care Record Registry.
- Navigate to Registry Management > Service Registry .
- Restrict the available services to HTTP endpoints by select HTTP from the Service Type drop down menu.
-
Enter the following values for the fields:
- Name - Enter the name - has to be "CareCommunity"
- Service Type - Select HTTP.
- Host - Enter the host name for the Care Community web service. Should be secure (ie. "<vm-name>. iscinternal.com ")
- Port - Enter the HTTPs port for the Care Community web service.
- SSL Configuration - Enter your SSL configuration for secure communications
- URL - Enter the full path to the Care Community web service, which should be "/api/healthshare-rest/<Care Community namespace>
- HTTPCredentialsConfig - Enter the name of the credentials object you created for this entry.
- Select Save .
3.2.2. Enabling Care Plans in the Workbench
-
Log into the Workbench as a user with the
Configuration Manager
role. - Go to the Configuration Application page ( Setup > Configuration Application ) and select the Feature Control tab.
- Select Edit Mode to make edits to the fields described in the following steps.
- In the Records box, select the Enable checkbox.
-
Select the following tabs:
-
- Enable Care Team
-
Enable Care Plan Tab
-
Select this checkbox and proceed to fill out the two following required fields:
- Care Community Assigning Authority - the Assigning Authority name defined for Care Community in the Unified Care Record
- Care Community Service Registry Name - t he name of the service registry entry created in the Unified Care Record.
-
- After you have finished, select Submit at the bottom of the page to save your changes.
4. Event Based Tasks
Personal Community supports tasks which can contain multiple task items. Documents sent as task items are intended to be used to send patients educational materials to be read prior to upcoming events, and will appear in a patient's To Do box within Personal Community. Systems can register to receive updates about tasks and task items that have been sent to Personal Community.
4.1. Using the Task API
4.1.1. API Documentation
You can use an external system to call the Personal Community API with task information and associated task items to be returned. Swagger documentation for the task API is available here .
4.1.2. Creating an Intersystems IRIS User Account for API Access
In order for a system to use the Task API, they must have a corresponding IRIS User Account with the
HSPortal_Role_API_Services
role.
4.2. Task Item Types
Document task items are supported in Personal Community.
4.2.1. Document Task Items
Personal Community supports three types of documents:
- Link - links to fully qualified URL to external content, such as educational materials, websites, or videos
- OnDemand - documents and reports that can be generated on demand
- Stream - physical documentation
You must use the taskItem "type"="Document"
-
To use the
Link
task type, you must use the taskItem "documentType"="Link". Please note:
- a documentLink is required.
-
To use the
OnDemand
task type, you must use the taskItem "documentType"="Stream". Please note
- a documentLink is required
-
To use the
Stream
document type, you must use taskItem "documentType" = "Stream". Please note
- documentFileType is required
- documentStream is required, base64 encoded, and `maxLength` is constrained by maximum length of IRIS string (3161144 bytes) and 33% expansion from base64 conversion.
4.2.1.1. Configuring On-Demand Document Retrieval
To use the OnDemand document type, it is required to have a document retrieval class defined and registered. A document retrieval class is required for every external system that wishes to leverage the OnDemand document type. Document retrieval classes are stored against each external user's IRIS user account.
4.2.1.2. Retrieving Documents from an External System
4.2.1.2.1. Creating your Custom Document Retrieval Class
To create a new document retrieval class, follow the steps:
- Create a new class that extends HS.Portal.EHR.AbstractDocumentURLRetriever
-
Override the following methods:
- %GetFilename - Given the document URL, return the file name. This is applied to the Content-Disposition header of the HTTP response.
- %GetContentType - Given the document URL, return the MIME type. This impacts how the browser displays the data.
- %OutputDocumentToDevice - Within this method, implement the logic to write the data to the device.
- Compile the class
4.2.1.2.2. Create and Add Supporting Production Components [Optional]
To support your custom document retrieval processor, you may need to create an additional business service and business operation to interact with your external document provider
4.2.1.3. Registering your On-Demand Document Class
Register your on-demand document processor by using the $insert-document-processor API.
4.3. Receiving Status Updates
Personal Community can be configured to send updates as patients or their representatives complete tasks. To use the feature, the external system must expose an API that can receive these updates. Sites will need to create and register a task status update processor. A task status update processor is required for every external system that wishes to receive task status updates. The task status update processor is stored against each user's IRIS user account.
4.3.1. Creating your Custom Task Status Update Processor
4.3.1.1. Create your Custom Task Status Update Class
To create a new custom task status update class, follow the steps:
- Create a class that extends HSPortal.Production.Operation.AbstractTaskStatusUpdateOperation
- To determine which triggers and information to send to the external system, override the method %OnStatusUpdateRequest . This takes an instance of HSPortal.Production.Message.TaskStatusUpdateRequest as the first method parameter. This method should return a %Status
-
To access additional properties not in
HSPortal.Production.Message.TaskStatusUpdateRequest
, you can take advantage of two helper methods:
- %GetTaskFromID – Given a TaskID as the first method parameter, return an instance of HSPortal.Tasks.Task as the second method parameter
- %GetTaskItemFromID – Given a TaskItemID as the first method parameter, return an instance of HSPortal.Tasks.TaskItem as the second method parameter
4.3.1.2. Configuring the Personal Community Production for Task Status Updates
You must add the business operation associated with the task status update integration.
To configure your Personal Community production:
- Logon to the Management Portal for Personal Community as a user with the %EnsRole_Administrator role.
-
In your Personal Community namespace, go to the
Production Configuration
page. Specifically:
- Go to your Personal Community namespace by selecting Switch from the title bar and choosing its name in the namespace chooser.
- From the Management Portal, select Interoperability > Configure > Production .
-
Set up the business operation:
- On the Production Configuration page, under Operations , select the + icon, to add a new business operation. This displays the Business Operation Wizard .
- Select the Status Update class created in step 2 in the Operation Class drop down menu and set any defined properties as needed.
4.3.2. Registering your Task Status Update Processor
Register your task status update processor by using the $insert-status-update-operation API.