On-Demand Forms ​

On-demand forms revolutionize patient data collection, empowering healthcare providers at point-of-care to effortlessly select and present essential forms such as consents, patient histories and PROMs directly to the patient. By simplifying the administrative process and ensuring secure data collection, providers can focus on delivering exceptional care while patients conveniently complete necessary forms.

Feature overview ​

• Select forms to present to patient
• Create FastTrack URL
• Load forms in Visiontree Framework
• Save patient responses

Before getting started ​

Before you get started you may like to reference Initial API Setup

On-demand form workflow overview ​

1. Select forms to assign to patient
2. Request FastTrack URL
3. Redirect to Visiontree Framework AutoRender
4. Retrieve FastTrack information
5. Load selected forms
6. Patient completes forms
7. Save forms with pre-signed URLs

Next we will demonstrate how to generate a FastTrack URL to present on-demand forms to patients. You will need your Access Token and Tenant ID for the following requests.

Select forms to assign to patient ​

If the forms to assign to a patient are not known ahead of time a list of avaialable forms can be requested from the Forms API.

Request ​

import axios from 'axios'

const FORMS_API_BASE_URL = 'https://api.visiontree.com/v1'
const TENANT_ID = '1'
const AUTH_TOKEN = 'Your_Auth_Token'
const options = {
  headers: {
    Authorization: `Bearer ${AUTH_TOKEN}`,
  },
}

axios.get(`${FORMS_API_BASE_URL}/tenants/${TENANT_ID}/forms`, options)
	.then(res => console.log(res.data))

Response ​

[
  {
    formId: 'bf484e43-bdc0-4cdd-859b-a9505f025adc',
    tenantId: '2',
    revisionId: '2eceef09-e867-4111-81a8-543841fac543',
    revision: '1',
    visibility: 'Private',
    content: {
      resourceType: 'Questionnaire',
      text: 'Example questionnaire 1'
    },
    createdOn: '2024-03-21T21:12:58.462Z',
    updatedOn: '2024-03-21T21:12:58.582Z'
  },
  {
    formId: 'd3ff03ea-9376-412b-b47a-38441d08b4de',
    tenantId: '2',
    revisionId: '2be231fe-2fd3-483e-99b6-fc2b0c408b2b',
    revision: '1',
    visibility: 'Public',
    content: {
      resourceType: 'Questionnaire',
      text: 'Example questionnaire 2'
      },
    createdOn: '2024-03-22T16:02:38.321Z',
    updatedOn: '2024-03-22T16:02:38.441Z'
  }
]

Explanations ​

Request ​

Let's look at the request and go over it line by line. First, we made use of the axios library to simplify promise-based HTTP requests. You may use any HTTP library of your choosing. The following three lines set our base Forms API URL, our Tenant ID as well as our Auth Token previously retrieved. The Tenant ID here will be used to retrieve all available forms for this tenant.

The final line is the HTTP request itself where we introduce the full API endpoint, body and headers.

Response ​

The response shows a list of available forms this tenant can access. In each form object, there are two fields to take not of: formId and revisionId. The formId represents a form saved in the forms registry, whereas the revisionId represents a specific version of that form. Importantly, the revisionId is used to select the forms to present to the patient via the generated FastTrack URL, which will be discussed in the next step.

Request FastTrack URL ​

A FastTrack URL is created to redirect a patient to a Visiontree Framework Autorenderer to view the selected forms as well as to allow the patient to fill them out and save them to the Forms API.

Request ​

import axios from 'axios'

const FORMS_API_BASE_URL = 'https://api.visiontree.com/v1'
const TENANT_ID = '1'
const AUTH_TOKEN = 'Your_Auth_Token'
const options = {
  headers: {
    Authorization: `Bearer ${AUTH_TOKEN}`,
  },
}

const body = {
	revisionIds: [
		'2eceef09-e867-4111-81a8-543841fac543',
		'2be231fe-2fd3-483e-99b6-fc2b0c408b2b'
	],
	correlationTag: 'DEIDENTIFIED-ID-0001',
	expiresIn: 604800
}

axios.post(`${FORMS_API_BASE_URL}/tenants/${TENANT_ID}/fasttrack`, body, options)
	.then(res => console.log(res.data))

Response ​

{
  fastTrackId: '0798b3a7-776f-41b2-84f4-1b0c96e5d2b6',
  fastTrackUrl: 'https://your-forms-renderer.com/0798b3a7-776f-41b2-84f4-1b0c96e5d2b6'
}

Explanations ​

Request ​

Let's look at the request and go over it line by line. First, we made use of the axios library to simplify promise-based HTTP requests. You may use any HTTP library of your choosing. The following three lines set our base Forms API URL, our Tenant ID as well as our Auth Token previously retrieved.

Next we have the request body where we can see the property revisionIds. This list tells the FastTrack URL generator that these two forms are selected to be presented to the patient and these 2 forms alone will be administered for the patient to respond to.

The property correlationTag is used as an identifier for whom the forms will be filled out by. This should be a deidentified ID if referring to a patient.

Lastly, there is the property expiresIn, which sets the expiration time by which a patient can respond and successfully save their response to the Forms API. This time is in seconds and the maximum value allowed is 604800 seconds, which represents 7 days.

The final line is the HTTP request itself where we introduce the full API endpoint, body and headers.

Response ​

In the response body there are two properties: the fastTrackId and fastTrackUrl. The fastTrackId is simply the path on the fastTrackUrl and acts as a session ID to retrieve the selected forms as well as the pre-signed URLs to save the patient responses with. The fastTrackUrl is used to redirect the patient to a Visiontree Framework Autorenderer to view and complete the selected forms.

Redirect to Visiontree Framework AutoRenderer ​

Using the returned fastTrackUrl, the application that requested the FastTrack URL for the selected forms can now redirect the patient to view and complete those forms at a Visiontree Framework Autorenderer instance.

Retrieve FastTrack information ​

Once the redirect has occurred the Visiontree Framework Autorenderer can make a request to the Forms API using the fastTrackId to retrieve the previously selected forms as well as pre-signed URLs, which will be used to save the patient's responses.

Request ​

import axios from 'axios'

const FORMS_API_BASE_URL = 'https://api.visiontree.com/v1'
const TENANT_ID = '1'
const AUTH_TOKEN = 'Your_Auth_Token'
const FAST_TRACK_ID = '0798b3a7-776f-41b2-84f4-1b0c96e5d2b6'
const options = {
  headers: {
    Authorization: `Bearer ${AUTH_TOKEN}`,
  },
}

axios.get(`${FORMS_API_BASE_URL}/tenants/${TENANT_ID}/fasttrack/${FAST_TRACK_ID}`, options)
	.then(res => console.log(res.data))

Response ​

{
  tenantId: '1',
  signedUrls: [
    'https://presigned-url-1',
    'https://presigned-url-2'
  ],
  revisionIds: [
    '2eceef09-e867-4111-81a8-543841fac543',
    '2be231fe-2fd3-483e-99b6-fc2b0c408b2b'
  ],
  correlationTag: 'DEIDENTIFIED-ID-0001',
  expiresIn: 604800,
  createdOn: '2024-03-22T16:48:41.002Z'
}

Explanations ​

Request ​

Let's look at the request and go over it line by line. First, we made use of the axios library to simplify promise-based HTTP requests. You may use any HTTP library of your choosing. The following three lines set our base Forms API URL, our Tenant ID as well as our Auth Token previously retrieved.

In addition to above there is the FAST_TRACK_ID path parameter which is used by the Visiontree Framework Autorenderer to request from the Forms API the previously selected forms so they can be shown to the patient to complete.

The final line is the HTTP request itself where we introduce the full API endpoint, body and headers.

Response ​

The response body contains important information for retrieving the patient forms for them to fill out. The most important properties here are: tenantId, signedUrls, revisionIds and correlationTag. These properties are all needed to successfully save the patient's responses to the Forms API.

The tenantId identifies the tenant the application belongs to as well as the owner of the patients' responses.

The signedUrls are used to send the patient's responses back to the Forms API and will be explained in detail in the following sections.

Next, the revisionIds are used to make calls to the Forms API to retrieve the actual questionnaire form the present to the patient to fill out. Retrieving the questionnaires will be discussed in the next section

Lastly, the property correlationTag is used to bind the response to the actual patient in the Forms API.

Load selected forms ​

After retrieving the FastTrack information in the previous section, the revisionIds can now be used to retrieve the questionnaires from the Forms API.

Request ​

import axios from 'axios'

const FORMS_API_BASE_URL = 'https://api.visiontree.com/v1'
const TENANT_ID = '1'
const AUTH_TOKEN = 'Your_Auth_Token'
const REVISION_ID = '2eceef09-e867-4111-81a8-543841fac543'
const options = {
  headers: {
    Authorization: `Bearer ${AUTH_TOKEN}`,
  },
}

axios.get(`${FORMS_API_BASE_URL}/tenants/${TENANT_ID}/forms/revisions/${REVISION_ID}/contents`, options)
	.then(res => console.log(res.data))

Response ​

{ 
  resourceType: 'Questionnaire',
  text: 'Example questionnaire 1'
}

Explanations ​

Request ​

Let's look at the request and go over it line by line. First, we made use of the axios library to simplify promise-based HTTP requests. You may use any HTTP library of your choosing. The following three lines set our base Forms API URL, our Tenant ID as well as our Auth Token previously retrieved.

In addition to above there is the REVISION_ID path parameter which is used by the Visiontree Framework Autorenderer to request from the Forms API the actual questionnaire form to present to the patient to complete.

The final line is the HTTP request itself where we introduce the full API endpoint, body and headers.

Response ​

The response simply returns the questionnaire form to present to the patient for completion.

Patient completes forms ​

Next, the patient will complete the forms in the Vistiontree Framework Autorenderer. The next section will dicuss saving their responses to the Forms API

Save forms with pre-signed URL ​

Once the patient has completed the selected questionnaires it is time to save them to the Forms API. Earlier when the FastTrack information was retrieved from the Forms API there were pre-signed URLs returned in the response from the Forms API, in step Retrieve FastTrack information

The pre-signed URLs are used to make a PUT request against to save the patient's responses to the Forms API.

Request ​

import axios from 'axios'

const PRESIGNED_URL = 'https://presigned-url-1'
const body = {
  tenantId: '2',
  correlationTag: 'DEIDENTIFIED-ID-0001',
  revisionId: '2eceef09-e867-4111-81a8-543841fac543',
  content: {
  	type: 'QuestionnaireResponse',
  	text: 'Example Patient QuestionnaireResponse'
  }
}

// Successfully saved if returns 200
axios.put(PRESIGNED_URL, body).then(res => console.log(res.status))

Response ​

Response: 200 OK

Explanations ​

Request ​

The request requires two components a valid pre-signed URL to send the form submission to as well as the patient's responses and some additional metadata to bind the responses to a patient for a given form in the Forms API

To use the pre-signed URL simply make a PUT request to it. In the request body provide the following properties: tenantId, correlationTag, revisionId and content.

The tenantId is the the client's tenant ID. The correlationTag is used to denote which patient the response belongs to. Remember to keep this deidentified. The revisionId is the identifier of the form's version the patient is completing and is used to keep track of their response to the approriate form. Lastly, the content property is the actual patient's responses to the particular form as identified by the revisionId.

Response ​

A successful form submission will return an HTTP response 200.