Skip to main content

HealthShare Personal Community Patient Entered Data: Patient Task Setup Guide



1. Patient Task Overview

An integral part of an organization's patient engagement strategy is the ability to provide patients with the ability to receive and complete task items prior to appointments and visits, or after they have been discharged. Often times, these are done over the phone, or in person when the patient arrives to check in for their service, often using paper forms to capture assessments and consent.

The Patient Task functionally allows organizations to send digital versions of education, instructions, and forms to patients within Personal Community. Additionally, organizations may request that patients upload documentation as part of these tasks. If a patient has a task to complete, the Home    page will now include a  To Do   box. This box will list any outstanding tasks that have been sent to a patient. 

2. Using the Patient Task API

2.1.  API Documentation

You can use any trusted external system to call the Personal Community Patient Task API with task information and associated task items for a patient to complete.  As part of this workflow, you should first check to see if the patient is enrolled in Personal Community by calling the Personal Community Enrollment Status API.  If a patient is not enrolled, you may use the Personal Community Invitation to Enroll, or the Enrollment API to invite or enroll the patient.  More information about the Invite to Enroll and Enrollment API can be found in the HealthShare Personal Community Onboarding and Account Management Setup Guide.

Swagger documentation for the Personal Community APIs are available here .

2.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.

3. Configuring Patient Task 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. 

3.1. Create your Custom Task Status Update Class

To create a new custom task status update class, follow the steps:

  1. Create a class that extends   HSPortal.Production.Operation.AbstractTaskStatusUpdateOperation
  2. 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
  3. 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

3.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:

  1. Logon to the Management Portal for Personal Community as a user with the   %EnsRole_Administrator   role.
  2. In your Personal Community namespace, go to the  Production Configuration   page. Specifically:
    1. Go to your Personal Community namespace by selecting  Switch   from the title bar and choosing its name in the namespace chooser.
    2. From the Management Portal, select  Interoperability > Configure > Production .
  3. Set up the business operation:
    1. On the  Production Configuration   page, under  Operations , select the   +   icon, to add a new business operation. This displays the  Business Operation Wizard .
    2. Select the  Status Update   class created in step 5.2.1. in the Operation Class drop down menu and set any defined properties as needed.

3.3. Registering your Task Status Update Processor

Register your task status update processor by using the $insert-status-update-operation API.

4. Supported Patient Task Item Types

Refer to the Personal Community Patient Entered Data: Patient Task Item Setup Guide for more information about configuring each task item type.

4.1. Document Task Items

The document task item is intended to be used to send patients education or instructions.  This task item can be used to send links to external references, physcial documents, or on-demand documents.

4.2. Form Task Items

The form task item is intended to be used to send digital forms to patients.  These forms are built within Personal Community and can be used to support a variety of data capture workflows.

4.3. Upload Document Task Items

The upload document task item is intended to be used to request physical documentation or images from patients. This task item can be used to request a variety of documents or images (such as pictures of insurance cards).  Use of this task item in a production system requires the use of the Personal Community virus scanner as this feature allows a patient to upload documentation from their personal devices. Refer to the HealthShare Personal Community Virus Scanner Setup Guide for more information on configuring and enabling a virus scanner.