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.

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.

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.

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

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()

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)	

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.

The upload document task item is used to request physical documentation or images from patients. Organizations enabling this feature will configure a set of system defaults that include what file types are accepted and how the documents will be processed and routed on submission.  These settings may be overwritten in the API request to allow for more granular control of this feature on a upload document task item type basis.

4.1. Default Accepted File Types

Personal Community can accept files of the following types:

Accepted file types may be further restricted on an individual upload document task item using the supportedFileTypes array in the patient task API request.

4.2. Default Patient Task Upload Mode

Personal Community requires that default upload mode is set to support the upload document task items.  This setting is used to route the uploaded document.

Options include:

• TrakSDA - This will send the uploaded document to TrakCare where it will become available in the Scanned Patient Documents chart.
• UCRSDA - This will send the uploaded document to an Edge Gateway in the Unified Care Record.  This document is then available as part of the patient's aggregrated record in the Unified Care Record.
• Custom - This mode allows a site to define a custom workflow to deliver the uploaded documents to an external system

4.3.1. Setup Edge Gateway in Unified Care Record

As Personal Community will now be submitted data to the Unified Care Record, it is recommended that it has a dedicated Edge Gateway.

4.3.2. Setting Up a Facility for the Personal Community Edge Gateway in the Unified Care Record

The Personal Community Edge Gateway should have a dedicated facility defined in the Unified Care Record.  Personal Community will use this facility when submitting clinical information to the Unified Care Record.

To establish a facility:

1. Log in to the Management Portal on the Unified Care Record associated with Personal Community.

2. On the Management Portal home page, select   HealthShare .

3. Select the namespace for the Registry (for example,   HSRegistry ).

4. Select   Registry Management   >   Facility Registry . This displays the   Facility Registry   page.

5. On the   Facility Registry   page, specify values for the following fields — and only the following fields:

   • Facility Code   — An identifier for the facility.

   • OID   — A unique identifier for the Personal Community Edge Gateway, which is based on an OID obtained from   HL7.org .

   • Create Assigning Authority   — When selected, specifies that HealthShare should also create an assigning authority with the same code as the facility. Select this.

   • Gateway Name   — Select the Edge Gateway you created for Personal Community.

6. Select   Save   to save the facility.

4.3.3. Configuring the Personal Community Production for UCRSDA Submission

To configure your Personal Community production to send uploaded documents to Unified Care Record:

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. Configure the business process:
   
   1. Select the   HSPortal_UploadDocumentSubmissionProcess   component under Processes:

   2. Under   Basic Settings :

      • SendingFacilityCode - Enter the facility code for the facility you created in the previous step.

      • DocumentTypeCode - Enter the document type code or string to represent this type of document in the Unified Care Record. This value is defaulted to "Patient Uploaded Document".
   3. Select  OK  to save the business process.
4. Configure the business operation:
   1. Select the  HSPortal_EdgeGatewayOperation component under Operations:
   2. Under Additional Settings:
      1. ServiceName - Set this to the Service Registry Name as defined in the Unified Care Record for your Personal Community Edge Gateway.
   3. Select  OK to save the business operation.

The upload document task item is designed to be flexible so that uploaded documents can be sent into any desired workflow for your organization.

4.4.1. Create your Custom Document Upload Processor

The document processor is responsible for taking the incoming HSPortal.Production.Message.UploadDocumentSubmissionRequest and transforming it into the correct format for the final destination.  The  HSPortal.Production.Message.UploadDocumentSubmissionRequest contains information about the task and task item the documents are associated with as well as information about the submitted document.

Task and task item properties include:

• ExternalTaskID  - The task ID for this task in the external system.
• EpisodeID - The episode ID that this task is associated with.
• TaskID -  The internal task ID.
• TaskItemID - The internal task item ID.
• CompletedbyUserMRN - The Personal Community MRN for the user that completed the task. Note that this will differ from the AssignedToUserMRN if the task was completed by the patient's proxy.
• AssignedToUserMRN - The Personal Community MRN for the patient who was assigned the task.
• SubmissionTime - The time that the documents were submitted.

Document properties include:

• UploadProcessorType - The selected upload processor mode for this document.
• ProcessorName - Used to route this request message to the appropriate processor.
• DocumentIDs - The list of document IDs for all documents uploaded as part of this task item.

Uploaded documents are stored as HSPortal.Session.UploadDocument objects for the duration of the user session.  Your custom processor should use the DocumentIDs  to open the corresponding  HSPortal.Session.UploadDocument  object to access infromation about the uploaded document, including the  Filename , ContentType,  and  Content of the document.

Your document upload processor can be defined as either a business process or business operation. 

4.4.2. Configuring the Personal Community Production for Document Uploads

To configure your Personal Community production for custom document uploads:

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 processor and / or business operation created in the above step.

Note the name of your production component as that will be needed to complete configuration.

To configure the upload document task item in the Workbench:

1. Log into the Workbench as a user with the  Configuration Manager  role.
2. Go to the  Configuration Application   page ( Setup  >  Configuration Application ) and select the  Feature Control  tab. 
3. Select  Edit Mode  to make edits to the fields described in the following steps.
4. In the Patient Document Uploads box, configure the following settings:
   • Enable Virus Scanner - this must be enabled on a production system.
   • Default Accepted File Types - this is the list of supported file types that can be accepted.  This list can be further restricted by including supported file types in the patient task API.
   • Default Patient Task Upload Mode - this is the upload mechanism that will be used if none is provided in the patient task API.
   • Default Patient Task Upload Processor - required if Upload Mode is custom.  This is the name of the production component to be called to process the uploaded document.
5. After you have finished, select  Submit  at the bottom of the page to save your changes.