Summary

This article covers form flow that allows for the control of visibility and accessibility of forms. 

Table of Contents

Design | System

Forms participating in form flow will always have a special status assigned to them. These statuses determine the rights available to each Role in regards to read and write permissions.

Before form flow can be used within the system, the Data Architect file must be configured. This file contains worksheets with information related to a study. The worksheets required for form flow and the properties that must be filled out on each worksheet are explained in this section.

Form Flow

In order for a form to participate in a form flow, the Form Flow worksheet must be configured.

Create Flow Configuration Row

For each form type participating in form flow, a Flow Configuration Row must be created.

  1. FormTypeId: Enter the Form Type ID for the form that should have this form flow.
Note: Form flow should be configured per form type, not per container, to ensure the permissions are respected in all Managers and Reports.
  1. Status Id: Enter ‘*’
  2. Attributes: Enter: priority=’100′
Note: Each attribute added to the Attributes column must be separated by a comma.
  1. Attributes: Enter ‘flowLabel=’ followed by the name for the form flow in single quotes.
    In the system, this label will be displayed in the form flow bar.
    Example: To name the flow ‘Submission Status,’ enter: flowLabel=’Submission Status’
  2. Attributes: Enter ‘default=’ followed by the name of the default status in single quotes.
    The default status is the status assigned to the form when it is first created. If no default value is provided, the first configured status is used as the default status.
    Example: To give the flow a default form status of ‘new,’ for all newly created forms, enter: default=’new’
  3. Attributes: If you are configuring form flow for an existing study, enter ‘activation=’ followed by the status label that all existing forms should have when the form flow feature is activated. Otherwise, skip this step.
    Example: For Adverse Event forms already existing in the system, this attribute could be set to the status label, ‘notSubmitted.’
  4. Leave the other properties blank.


Create Status Configuration Row

Status Configuration Rows correspond to the different form statuses participating in the form flow. Each form status must have its own Status Configuration Row.

  1. FormTypeID: Enter the Form Type ID for the form that should have this form flow.
  2. Status ID: Enter an integer value. Each Status ID must be different from all others in the study.
Note: While Status IDs do not need to be used in ascending order, the Status ID must never be changed or reused once it has been assigned.
  1. Status Name: Enter a name for the status.
Note: The name only needs to be unique for form flows with the same Form Type ID.

Example: If there is a form flow status with the Status Name, ‘new,’ for the Adverse Event form flow, there can also be a form flow status with the Status Name, ‘new,’ for the Concomitant Medication form flow.

  1. Status Label: Enter a label for the status that will be displayed by the system.
  2. Attributes: Optional. To define the text color for the status in the form summary and Forms Manager to be a color other than the default value of black, enter ‘color=’ followed by the color’s name or six-digit code name in single quotes.
    Example: color=’white’ and color=’#FFFFFF’ will both set the text color to white.
  3. Attributes: Optional. To define the background color for the status in the form summary and Forms Manager to be a color other than white, enter ‘bgColor=’ followed by the color’s name or six-digit code name in single quotes.
    Example: The following attributes are defined for a status of ‘Not Submitted’ in the Forms Manager: color=’white’,bgColor=’#FFA500'
  4. Attributes: Optional. To display status transitions vertically, enter: tileVertically=’1′
    By default, status transitions are displayed horizontally in the flow bar.
  5. Attributes: Optional. To prevent form status changes from rolling down to children forms and up to parent forms, enter ‘encapsulate=’ followed by a comma separated list of status names in single quotes.
    Basic Rule for Encapsulation: When a Role can change a metadata status and certain forms are hidden for the Role, the metadata status should be encapsulated for the form flow status.
    Example: If the Adverse Event form had a form flow status called ‘New’ with the attribute, encapsulate=’Violation’ the encapsulation would make it so that the violation alert would not roll up to its parent forms.
  6. Flow Dependencies: Specify the dependencies for the form flow separated by a comma.


Add Filters

Normally a user can filter on statuses that he is allowed to view in the Forms Manager and Subjects Manager. In addition it is possible to add additional filters having a time restriction. Filters related to time restrictions can be used in the Forms Manager and Subjects Manager when specified in the Attributes column. To enable these filters, a time restriction and filter label must be specified for each filter attribute.

  1. In the attributes column, enter:
    • ‘addFilters=’ if the filter should be available to all roles with permission to view form flow statuses.
    • ‘addFilters.RoleName=’ where RoleName is the name of a specific role if the filter should only be available to certain roles.
  2. Enter a time restriction followed by the separation marker, ‘||’
  3. Enter a filter label to be displayed in the system when using this filter.
  4. If adding more than one filter, enter the separation marker, ‘::’
    Example: For the status, Submitted, the attribute could be: addFilters=‘<1H||Submitted less than one hour ago::<3d||Submitted less than three days ago::>7d||Submitted, older than one week’
  5. Repeat steps 2 through 4 for each additional filter in a configuration row.
    In the following example, two filters are used for the submitted status of the Adverse Event forms. The first filter applies to all roles while the second filter applies only to coordinators.


Roles

To see the forms that participate in form flow, the role must be granted permission on the Roles worksheet. If a role is not granted permission to view a form participating in form flow, the form will not be included in the export for that specific role.

Configure Flow Permissions

By configuring Flow Status Permissions, you can change the level of access that a role has to flow statuses. When defining these permissions, the flow statuses must be written in the form, fflw#[formTypeId].[Status Name], where you specify the formTypeId and Status Name.

  1. Flow Status: Enter the Flow Status using the form, fflw#[formTypeId].[Status Name]
    Example: To add permissions for the Adverse Event form when its status is ‘new,’ enter: fflw#ae.new
  2. Flow Status Permission: Enter the Flow Status Permission allowed for this form.
    Example: To allow roles to edit the form, enter: form.write
  3. Status Permission Attributes: If additional permissions for a role are needed, enter ‘includes=’ followed by a comma separated list of the additional Flow Status Permissions in single quotes.
    In the following example, the roles selected will only be able to view the flowbar and know that the form exists.
  4. Select the Roles that should have this permission by placing an ‘X’ in the appropriate columns.
  5. Repeat this process for each Flow Status Permission.


Configure Flow Transitions

In order for a form to change from one flow status to the next, Flow Transitions must be defined. When defining these transitions, the Flow Transitions must be written in the form, fflw#[formTypeId].[Status Name]>>[formTypeId].[new Status Name] where the parts in brackets are specified by you.

  1. Flow Transition: Enter the flow transition using the form, fflw#[formTypeId].[Status Name]>>[formTypeId].[new Status Name]
    Example: To specify the transition from a new adverse event to an unset adverse event, enter: fflw#ae.new>>ae.unsent
  2. Transition Label: Enter the label for the new transition.
    Example: If the Adverse Event form is changing from ‘new’ to ‘unsent,’ enter ‘Unsent’ for the transition label.
  3. Transition Attributes: Enter the Flow Transition Attributes required for this Flow Transition.
    Example: To require a signature and display a tip for a flow transition, enter: requireSignature=’true’,tip1=’Submit this only when you have answered all questions.’
  4. Select the Roles that are permitted to use this transition by placing an ‘X’ in the appropriate columns.
  5. Repeat this process for each Flow Transition.


Add Required Actions

Two Actions must be included on the Roles worksheet for Form Flow to function.

  1. Actions: Enter ‘View Form Flow Column.’
  2. Actions Required: Leave this column blank.
  3. Screens Required: ‘viewFormFlowColumn.’
  4. Select the Roles that are permitted to view Form Flow information by placing an ‘X’ in the appropriate columns.
    If a Role does not have the viewFormFlowColumn permission, the column is hidden in the Forms Manager.
  5. Actions: Enter ‘Form Flow Transitions.’
  6. Actions Required: Enter ‘formFlowTransition.’
  7. Screens Required: Enter ‘formFlowTransition.’
  8. Select the Roles that are permitted to perform status transitions by placing an ‘X’ in the appropriate columns.


Add Activation Actions for Existing Studies

If adding the Form Flow feature to an existing study, one action related to activation of the feature must be included on the Roles worksheet. Additionally, trials using record level form flow transitions must include another action related to activation. Including these actions will enable those with the proper roles to activate the features within the system.

  1. Actions: Leave this column blank.
  2. Actions Required: Enter ‘activateFormFlow’
  3. Screens Required: Leave this column blank.
  4. If not using record level form flow transitions, go to step 8.
  5. Actions: Leave this column blank.
  6. Actions Required: Enter ‘activateRecordLevelFormFlowTransitions’
  7. Screens Required: Leave this column blank.
  8. Select the Roles that are permitted to activate the features by placing an ‘X’ in the appropriate columns.


App Properties

Configure Export Details

One property must be included on the App Properties worksheet for Form Flow to function. The property will affect whether or not the Form Flow type and Form Flow value are exported when the Forms Manager is exported.

  1. Name: Enter ‘viewFormFlowStatus.’
  2. Value: Enter ‘false’ to prevent the Form Flow type and Form Flow value from being exported. Enter ‘true’ otherwise.


Enable Record Level Form Flow Transitions

Record level form flow transitions are not enabled by default. These transitions allow you to chose to filter within the Subjects Manager and trigger transitions on all matching forms from the Subjects Manager If you want to use such transitions, another property must be included on the App Properties worksheet.

  1. Name: Enter ‘recordLevelFormFlowTransitions’
  2. Value: Enter ‘true’
Note: 'RecordLevelFormFlowTransitions' can only be added pre-deployment. If you want to use this functionality as a mid-study change, use the property 'activateRecordLevelFormFlowTransitions' instead.



Definitions

Refer to this section when you are unsure about a specific term or system variable.

Status Names

The following is a list of possible status names that can be used with the encapsulate property:

  • Query
  • Violation
  • Validation
  • Signed
  • Lock
  • Freeze
  • Answer
  • DataReview

Flow Dependencies

Flow Dependencies are used while creating Status Configuration Rows. They allow for different form actions to occur when the form holds a specific status. The basic syntax is change=’action;’ meaning that when a change is made to a form, a specific action occurs. A new line should be added for each new flow dependency change. Actions can be placed on a single line, comma separated.

Changes

form.queryStatus.clean.openQuery

The form has changed its query status from “clean” to “openQuery.” This change occurs only when the first query on a form is created. This change does not occur for the creation of additional queries on the same form.

form.queryStatus.openQuery.clean

The form has changed its query status from “openQuery” to “clean.” This change occurs when the last open query on the form is cleaned.

question.queryStatus.clean.openQuery

A query on a previously clean question has been opened. This change only occurs when the first query on a clean question is opened. This change does not occur when an additional query is opened on the same question.

question.queryStatus.openQuery.clean

The last query on a question is cleaned.

question.data.x.y

This change occurs when the value of any question on the form is changed.

Note: Neither x nor y can be replaced with literal strings. If this property is used, it will apply any time any question value on the form is changed. This property cannot be altered based on what change was made.


Actions

question.unfreeze

The question is unfrozen. This requires a question change key like question.queryStatus.clean.openQuery.

status.newStatus

The status of the form changes to the new status that is specified by replacing the term, newStatus. These statuses are defined in the Form Flow worksheet.

Examples

question.data.x.y=’status.notSubmitted’

With this configuration when the value of a question is changed, the form’s status is changed to the ‘notSubmitted’ status. This notSubmitted status is defined by the trial designer on the Form Flow worksheet.

question.queryStatus.clean.openQuery=’question.unfreeze,status.openWithQuery’

With this configuration when a query is opened on a previously clean question, the question is unfrozen and the status of the form is changed to the ‘openWithQuery’ status.

Flow Status Permissions

When configuring flow status permissions for different roles, the following permissions can be used separately or together.

Basic Permissions

form.write

The form can be viewed and edited

form.read

The form can be viewed but not edited

form.note

The form is listed in the Form Links table but cannot be viewed

note.header

The form header (title) can be viewed

note.demog

The pinned questions for a form can be viewed


Note: If the note.demog permission is assigned, any files attached to a form will be viewable. You should not assign this permission if you wish to prevent users from viewing a file attachment.


view.flowbar

The flow bar for the form can be viewed

Metadata Permission Attributes

The following permissions are restrictions to the overall permissions. If nothing is configured within the ‘Status Permission Attributes’, the role permissions for each Metadata status will be applied.

Note: These permissions must be set per flow status and per flow status permission programmed for each defined form. Additionally, roles configured with these attributes will have the ability to apply the specified metadata status to the configured form as well as any hidden sub-forms not visible to the role, unless form flows with encapsulation are defined for those sub-forms.


write.Complete

Allows the user the ability to perform the ‘Complete’ and/or ‘Clear Complete’ metadata actions for the defined form.

write.SDV

Allows the user the ability to perform the ‘SDV’ and/or ‘Clear SDV’ metadata actions for the defined form.

write.DataReview

Allows the user the ability to perform the ‘Data Review’ and ‘Clear Data Review’ metadata actions for the defined form.

write.Freeze

Allows the user the ability to perform the ‘Freeze’ and ‘Unfreeze’ metadata actions for the defined form.

write.Lock

Allows the user the ability to perform the ‘Lock’ and ‘Unlock’ metadata actions for the defined form.

write.Sign

Allows the user the ability to perform the ‘Sign’ and/or ‘Clear Signature’ metadata actions for the defined form.

write.metadata

Encompasses all metadata related permission attributes (write.Complete, write.SDV, write.DataReview, write.Freeze, write.Lock, and write.Sign)

Example Configuration:


Permission Inclusions

To avoid having to list every permission, the following permissions include several different permissions.

  • form.write includes the form.read, form.note, note.header, note.demog and view.flowbar permissions.
  • form.read includes the form.note, note.header, note.demog and view.flowbar permissions.

Flow Transition Attributes

Transition Attributes are the attributes required and displayed when the flow transition occurs. The following attributes can be used when configuring flow transitions.

True/False Attributes

allowComment

Specifies that a comment for a status transition is allowed. The comment is written to the audit history. This attribute is allowed by default, so it doesn’t need to be included unless it is being set to false.

allowSignature

Specifies whether a signature can be used when the transition occurs. Set this attribute to ‘true’ to allow for a signature on the the form during the transition.

requireComment

Specifies that a comment for the status transition is required. Set this attribute to ‘true’ to require a comment.

requireSignature

Specifies that a signature for the status transition is required. Set this attribute to ‘true’ to require a signature.

Additional Attributes

before

Specifies the comma-separated list of actions that are applied before the transition is done. Currently two actions are available:

  • freeze – the form is automatically frozen during the transition
  • complete – the form is automatically completed during the transition

hint

Specifies the text that is displayed as a hint in the flow bar and as a tip on the transition confirmation screen.

notification

Specifies that a notification can be sent when the form flow transition occurs. Set this string to any unique string value. Before notifications will be sent, the notification must also be configured with the Email Notifications feature.

By default, the name displayed in the Type section of the Email Notifications form is the name of the Flow Transition Label. This name can be specified using the following format: notification=’[unique string value]||[notification label]'


tip<counter>

Specifies text that is displayed as a tip on the transition confirmation screen. Any number of tips can be specified beginning with ‘tip1.'

Note: Do not skip numbers in the counter. Add the tips in sequential order.


barVisible

Enables form flow bar visibility. Set this attribute to ‘yes’ to make the form flow bar visible. The default value is no.


Record Level Form Flow Transitions

These transitions allow for form flow at the subject level. They can be useful when subjects must transition through multiple phases, cycles or extensions in a study.

Time Restrictions

Time restrictions are used to filter subjects and forms based on the time that the form received a new status label. Time restrictions consist of three parts which all must be specified for the time restriction to work.

Comparator

Acceptable comparators are the “<” (less than sign) and “>” (greater than sign).

Integer Number

Any integer number is acceptable for time restrictions. This number is used to quantify the date field as shown in the examples.

Date Field Code

The following is a list of acceptable date field codes and their definitions. The date field codes must be entered exactly as shown here.

  • s – seconds
  • m – minutes
  • H – hours
  • d – days
  • M – months (30 days)
  • y – year (365 days)

Examples

<2d

Filter only displays forms that have entered their form flow status within the past two days

>8H

Filter only displays forms that entered their form flow status more than eight hours ago

>10d

Filter only displays forms that entered their form flow status more than ten days ago

Need more help?

Please visit the Fountayn Contact Information page.