Skip to main content

HealthShare Personal Community Patient Entered Data: Patient Task Item Setup Guide



1. Patient Task Items Overview

The Personal Community Patient Task API supports two types of task items:

  • Documents - used to send educational links or physical content to a patient
  • Forms - used to send Personal Community digital forms to patients

Each task item has specific configuration that needs to be completed before it can be used.

2. Document Task Item

The document task item is intended to be used to send patients education or instructions. 

This task item supports three types of documents:

  1. Link - links to fully qualified URL to external content, such as educational materials, websites, or videos.
  2. OnDemand - documents and reports that can be generated on-demand.
  3. Stream - physical documentation, such as pdfs.

You must use the taskItem "type"="Document"

  1. To use the Link task type, you must use the taskItem "documentType"="Link". Please note:
    1. a documentLink is required.
  2. To use the OnDemand task type, you must use the taskItem "documentType"="Stream". Please note
    1. a documentLink is required
  3. To use the Stream document type, you must use taskItem "documentType" = "Stream". Please note
    1. documentFileType is required
    2. documentStream is required, base64 encoded, and `maxLength` is constrained by maximum length of IRIS string (3161144 bytes) and 33% expansion from base64 conversion.

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

2.1.1. Create your Custom Document Retrieval Class

To create a new document retrieval class, follow the steps:

  1. Create a new class that extends HS.Portal.EHR.AbstractDocumentURLRetriever
  2. 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.
  3. Compile the class

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

2.1.3. Registering your On-Demand Document Class

Register your on-demand document processor by using the $insert-document-processor API.

3.  Form Task Item

Personal Community uses a single processing mechanism for handling all form task items that patients submit. When a patient submits a form task item, Personal Community processes it and performs the following actions:

  1. It uses the form key associated with the form to identify:

    • The transform associated with the form (if one is specified)

    • The recipient of the form, known as its   target

  2. It then delivers the submitted form to a target (usually a business operation in your Personal Community production).

  3. The target that receives the form then delivers the form to its ultimate recipient, which may be the Workbench or an external destination.

Personal Community supports two submission routes: to the Workbench as a Task, or a custom submission route.


3.1. Workbench Task Submission Route

With this option, the submitted response is returned to the Workbench as a task. These tasks are routed to particular workflow group where the assigned Workbench Agent can claim and complete the task.

To use this mode you must:

  • Create at least one workflow group.
  • Assign Workbench Agents to this workflow group.

Form more information on workflow groups and workflow group agents, refer to the HealthShare Personal Community Workflow, Agents, and Tasks User Guide.


3.2.  Custom Submission Route

With this option, the submitted response is routed to a custom submission route.  This allows sites to send the submitted form to a trusted external system. Using this route requires a site to create a transform and a business operation to create the appropriate format for the submitted form, and deliver to the external system.

3.2.1.  Form Submission Transform

The transform is responsibe for taking the incoming HSPortal.Production.Message.TemplateFormSubmissionRequest  and transforming it into the correct format for the final destination.  The  HSPortal.Production.Message.TemplateFormSubmissionRequest contains the following properties:

  • FormData - An instance of  HSPortal.Templaes.DataMart.Form.Form.
  • FormCompletedbyUserMRN  - The Personal Community MRN for the user that completed the form. Note that this will differ from the FormAssignedToUserMRN if the form was completed by the patient's proxy.
  • FormAssignedToUserMRN  - The Personal Community MRN for the patient who was assigned the form.
  • SubmissionTime  - The time the form was submitted.

HSPortal.Templates.DataMart.Form.Form  contains the following properties:

  • Template - An instance of  HSPortal.Templates.Datamart.Template.   This class provides all the information about the form that the patient completed.
  • Answers - An array of  HSPortal.Templates.DataMart.Form.Answer .  This is the list of answers that a patient provided.
  • FDNBlob - An array of  HSPortal.Templates.DataMart.Form.JSON .  This is a JSON blob that contains the answers with a reference to their question identifier.

To create a new submission transform, follow the following steps:

  1. Create a new class that extends Ens.DataTransform
  2. Select  HSPortal.Production.Message.TemplateFormSubmissionRequest  as your source.
  3. Select your desired target format. Note that this  is likely a custom format you've defined.
  4. Map the appropriate Template FormSubmissionRequest properties to the appropriate location in the target message.
  5. Compile the class

Personal Community provides a helper method that can generate an HTML document of the completed for.  This can then be passed to a PDF generator to create a PDF version of the completed document. The code samples below illustrate how to create the HTML and PDF versions of the form.

HTML Document 
Set tHTML = ##class(%Stream.GlobalCharacter).%New()
Do ##class(HSPortal.Templates.Utils).WriteFormContainerHTML(.tHTML,pSubmittedForm.FormData.Answers,pSubmittedForm.FormData.Language,pSubmittedForm.FormData.Template)
Do tHTML.Rewind()
PDF Document 
Set tHTMLRequest = ##class(HSMOD.HTMLtoPDF.API.Auxil.HTMLRequest).%New()
Do tHTMLRequest.AddHTMLFileFromStream(tHTML, "temp.html")
Do $classmethod("HSPortal.Forms.Transform.PDF","GetHTMLToPDFOptions",.tOptions,pSubmittedForm.FormAssignedToUserMRN,pSubmittedForm.FormCompletedbyUserMRN,pSubmittedForm.FormData.Template.Name,pSubmittedForm.FormData.Template.TemplateVersion)
Set tStatus = ##class(HSMOD.HTMLtoPDF.API).CreatePDFFile(tHTMLRequest,,.tOptions,,.tPDFStream)
$$$ThrowOnError(tStatus)

3.2.2.  Form Submission Target

To support your custom submission route, you may need to create a business operation to interact with your external system.  This operation must be added to the Personal Community production prior to configuing the form settings in the form builder.

Sites that wish to deliver form responses to the Unified Care Record via SDA should use the HSPortal_EdgeGatewayOperation.

3.3. Create and Configure Personal Community Forms

Refer to the Personal Community Form Builder User Guide for information about creating and managing digital forms in Personal Community.