DFengage Release 2.3
All rights reserved. No part of this publication may be re-transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of DF/Net Research, Inc. Permission is granted for internal re-distribution of this publication by the license holder and their employees for internal use only, provided that the copyright notices and this permission notice appear in all copies.
The information in this document is furnished for informational use only and is subject to change without notice. DF/Net Research, Inc. assumes no responsibility or liability for any errors or inaccuracies in this document or for any omissions from it.
All products or services mentioned in this document are covered by the trademarks, service marks, or product names as designated by the companies who market those products.
Google Play and the Google Play logo are trademarks of Google LLC. Android is a trademark of Google LLC.
Nov 04 2024
DFengage is a mobile application for the collection of electronic patient-reported outcomes (ePRO) that allows research participants to complete study activities (such as questionnaires, surveys, and diaries) assigned by the research team.
DFengage is fully integrated with DFdiscover, using the setup definition defined in DFsetup and the role permissions and user accounts defined in DFadmin. This guide describes instructions and considerations for DFengage setup, administration, and management.
DFengage is installed from the Google Play Store (for Android) or Apple App Store (for iOS and iPadOS) on smartphones and tablets. Study participants login to DFengage with their unique user account and complete assigned activities based on the study schedule. DFengage sends notifications when new activities become available. Refer to the DFengage User Guide for details about the use of the DFengage app by study participants. DFengage is compatible with DFdiscover version 5.4 and later, however some features are only compatible with newer DFdiscover versions.
Use a quick installation link to simplify the installation and login process for DFengage users. An example link is: https://dfengage.dfdiscover.com/open?server=explore.dfdiscover.com&api=explore.dfdiscover.com:4433.
Clicking the link first checks whether DFengage is already installed on the device, and if not, goes to the DFengage page on the app store. Once DFengage is installed, clicking the link will pre-fill the server and API fields on the login page with the values specified in the URL, for example, server = explore.dfdiscover.com and API = explore.dfdiscover.com:4433 in the link above. Clicking the link on a device where DFengage cannot be installed will redirect you to https://www.dfnetresearch.com/dfengage-epro/.
Adapt the URL to include the server and API values for your study before sharing it with DFengage participants.
How to use the quick installation link: 1. Click the link to open DFengage in the app store. 2. Install DFengage on your device from the app store. 3. Click the link again to open DFengage with the server and API pre-filled. 4. Enter your username and password to login.
DFengage uses the plate definition, visit map, conditional maps, page map, and translations defined in DFsetup. The below sections outline how DFdiscover setup and configuration apply to DFengage and considerations for ePRO form design. See the Study Setup User Guide for general details on using DFsetup.
Refer to Study Setup User Guide, Defining Data Fields for complete details on creating plates and defining fields in DFsetup.
A plate defined in DFsetup is presented as an activity in DFengage. Forms to be completed in DFengage may be set up as plates with or without CRF backgrounds, but will always be displayed in DFengage with one field or group per screen.
Fields in DFengage are displayed in field order. The visit number (field 6) and subject ID (field 7) are not displayed in DFengage, so field 8 is the first question displayed for an activity in DFengage.
For each field or field group, the Prompt text is displayed in DFengage as the question text above the data field. If no Prompt is defined, the Description will be shown in DFengage. In DFengage version 2.0 and later, fields of any data type may be grouped to display them on a single screen with one prompt in DFengage. Screens and tables are not supported in DFengage.
Field and Plate Property Considerations
Legal ranges: Legal ranges are supported in DFengage version 2.0 and later. When an illegal value is entered in DFengage, a warning message will appear: “The response you entered might be incorrect. Please double-check it before continuing.” The user will be able to proceed to the next question after the warning is displayed.
Required and essential fields: Fields defined as required or essential must be completed by the DFengage user to continue or complete an activity. The “Next” button in DFengage is disabled and the user cannot proceed to the next question until they provide a response. Subjects may click “Next” for fields that are defined as optional without providing a response.
Baseline visit date fields: Visit dates are defined by the Use field property of “Visit Date” and selected as the visit date field for the B visit type in the visit map. In DFdiscover version 5.8 or later, visit dates may use any date format that includes day, month, and year.
In DFdiscover version 5.7 or earlier, baseline visit dates, used by DFengage to determine the schedule of ePRO activities, must use the DD/MM/YYYY format. If the visit date at the baseline visit is captured using a different date format (e.g., DD-MMM-YYYY), use a separate hidden field and edit check to convert the visit date at the baseline visit to the correct date format required for DFengage. Only baseline visit dates require the DD/MM/YYYY format in version 5.7 or earlier; all other dates may be in any format.
Formats: DFengage version 2.0 and later displays the defined format in the input field as a guide and warns the user if a response is entered that does not match the defined format. Only values matching the defined format will be accepted by the DFdiscover server when the activity is saved. Provide additional instructions for users if a complicated data format is required, to avoid data entry errors and lost data.
Skip patterns: Skips defined in the field properties are followed when the user clicks the “Next” or “Finish” button, to skip the number of fields defined based on the value selected or entered. Note that a group of fields were considered 1 field for DFengage in version 1.0, but in version 2.0 and later fields within a group are counted individually, as they are in other DFdiscover applications.
Instructions: The Instruction field property is supported in DFengage version 2.0 and later. Instructions can be displayed in DFengage above the prompt, above the field, or below the field. The field right, below field, and below prompt positions defined in DFsetup all display below the field in DFengage.
Plate and field help: Both plate help and field help are supported in DFengage 2.0 and later. Defined plate help is available in DFengage via the “?” icon next to the activity name. Defined field help will be available in DFengage via the “i” icon next to the field prompt within an activity.
Edit checks: Edit checks are not currently supported in DFengage.
Hidden fields: Hidden fields are supported in DFengage. Hidden fields are not displayed when the ‘Show hidden fields’ permission is disabled in the ePRO role definition.
Text-only screens: To display text only with no data field (for example, a questionnaire title and instructions), use a special custom property to hide the field input area. First, add the ePRO_HideField custom property tag to Custom Properties in the DFVAR section. Then, in the field properties, add Yes as the value for that property under the Custom tab. DFengage will display the prompt and instructions defined for the field, but not the field input area. Note that the field input area will not be hidden on the plate shown in DFsetup, but in the DFengage interface only.
Plate footnotes: Some surveys or questionnaires may require a footnote on each page, for example a copyright statement. If using the Instructions field property in the Below Prompt position on each field on the plate isn’t an option, there is a special custom plate property to support this. First, add the ePRO_Footnote custom property tag to Custom Properties in the DFPLATE section. Then, in the plate properties, add the footnote as the value for that property under the Custom tab. Use HTML to apply any required formatting. DFengage will display the footnote at the bottom of each screen in the activity, above the Previous and Next buttons. Plate footnotes are not represented on the plate shown in DFsetup, but applied to the DFengage interface only.
Data Type Considerations
Date and time fields: When capturing dates or times in DFengage, a calendar widget or 24-hour clock widget are provided showing the current date or time. The DFengage user can change the date/time if appropriate for the question. Date fields support all defined date formats but does not support partial dates. Time fields support hh:mm 24-hour clock time only.
Choice and check fields: Both choice and check field option buttons are displayed as circles, whether it’s “select one response” or “select all that apply”. Add instructions to the prompt to clarify this as needed. Up to 98 choices can be defined in a choice field, and choices may be represented in a list or in a dropdown menu according to the Show As field property. The longer the text or the higher the number of choices, the more scrolling needed.
Number fields: DFengage limits the number of characters that can be entered in numeric fields (including decimal places) according to the Store field property. If a format is defined, DFengage displays it in the input field as a guide and warns the user if the response entered does not match the defined format. Only values matching the defined format will be accepted by the DFdiscover server when the activity is saved. For complex number formats, provide instructions for the user to avoid confusion or data loss.
VAS fields: Use the VAS data type to collect numeric responses on a scale (e.g., pain scale of 0-10) and numbers within specific limits (e.g., temperature) to restrict data to allowable values only. Use in place of number fields where feasible or practical. You can set up VAS fields with as much precision as needed, in the field properties.
VAS displays as a horizontal scale by default, but vertical scales may be implemented using a special custom field property. First, add the ePRO_VAS_Layout custom property tag to Custom Properties in the DFVAR section. Then, in the VAS field properties, add Vertical as the value for that property under the Custom tab. DFengage will display the scale vertically, with the left value on the bottom of the scale and the right value at the top of the scale.
Where possible, the vertical scale is sized to display on the screen without scrolling. Scrolling may be required if there are more than a few lines of text above the scale, or if the scale includes too many values for the user to be able to select with precision on the given screen size. Be sure to test your scale on expected device sizes.
Additional VAS customizations are available with special custom properties as follows:
ePRO_VAS_ShowEveryXValues: The scale always shows the left and right values. Use this property to display additional values in specified increments. For example, if your scale is 0-100 and you want to display 10, 20, 30, etc., the value of this property is 10. If your scale is 1-10 and you want to display all whole numbers, the value is 1. Where possible all specified values are displayed on the scale (whether horizontal or vertical), however if space does not allow, only the middle value is displayed. Be sure to test your scale on expected device sizes.
ePRO_VAS_LeftText: Show a label for the left value on the scale. For horizontal scales, this is displayed on the right side above the scale. For vertical scales, this is displayed below the scale. By default, text is left-aligned and line breaks are added automatically. Use HTML to apply any required formatting. For vertical scales, we recommend centering the text and adding line breaks where needed (e.g.,<span style="text-align:center">Left Label<br>Second Line</span>).
<span style="text-align:center">Left Label<br>Second Line</span>
ePRO_VAS_RightText: Show a label for the right value on the scale. For horizontal scales, this is displayed on the right side above the scale. For vertical scales, this is displayed above the scale. By default, text is left-aligned and line breaks are added automatically. Use HTML to apply any required formatting. For vertical scales, we recommend centering the text and adding line breaks where needed (e.g.,<span style="text-align:center">Right Label<br>Second Line</span>). For horizontal scales, we recommend right-aligning the text.
<span style="text-align:center">Right Label<br>Second Line</span>
ePRO_VAS_LeftRightTextPosition: For horizontal scales, set the value of this property to Below to show the left and right value labels below the scale instead of above it. This property is ignored for vertical scales.
ePRO_VAS_CurrentText: Show a label for the current selected value. This is displayed above the current value inside the box. Note that the space available for this label is restricted by the size of the box. By default, the text is left-aligned and no line break is added. Use HTML to apply any required formatting, including line breaks.
Note that VAS customizations using custom properties are not represented on the plate shown in DFsetup, but applied to the DFengage interface only.
String fields: Use the string data type to collect text. The store length field property defines how many characters may be entered in that field. In DFengage, the total number of characters allowed is displayed below the input field, along with the count of the characters entered so far.
By default, the plate label is used as the activity name in DFengage. To change the activity name per visit, use the Page Map. Refer to Study Setup User Guide, Page Map.
Activities in DFengage become available based on the visit schedule defined in DFsetup. With DFdiscover version 5.8 and later, DFengage supports enhanced visit scheduling including conditional scheduling, termination visit dates, early termination plates, and missed visit plates. In DFdiscover version 5.7 and earlier, only specific visit types are supported.
The timing of activities in DFengage refers to the time when a new activity becomes available in the app, when a notification is sent for a new activity, and when a notification is sent for an overdue activity. Timing uses the time zone of the device on which DFengage is installed.
The default timing is 8:00am. Timing can be customized for all activities in a study and/or for individual visits in a study if the 8:00am timing does not align with study requirements. Customizing the timing for individual visits allows for multiple activities at different times per day.
To change the default 8:00am study timing for all visits, use a special custom study property. First, add the ePROStudyNotification custom study property tag in Custom Properties under the DFSTUDY section. Then, in Global Settings under the Custom section define the value for that property as the 24-hour clock time (e.g., “18:00”) to be used for this study.
To change the timing for a specific visit, add “T-XX:XX” to the end of the visit label in the visit map, where XX:XX is the 24-hour clock time to be used for this visit. The timing notation must be added to the end of the visit label or DFengage will not be able to read it.
If no timing is defined for a visit, the custom study timing is used for the visit. If no custom study timing is defined, the default 8:00am time is used.
The visit map and conditional maps define the schedule for when activities become available in DFengage. The Visit Map is described in Study Setup User Guide, Visit Map, with further detail about visit scheduling in Study Setup User Guide, Subject Visit Scheduling.
In DFdiscover 5.7 and earlier, only S (Scheduled) and T (Termination) visit types and required plates are supported in DFengage. Termination visit dates, optional visits, missed plates and visits, early termination plates, and conditional plates, visits, cycles, and terminations are not supported. Visits to be completed in DFengage must be scheduled from a baseline visit date entered on a non-ePRO plate using the DD/MM/YYYY date format.
In DFdiscover 5.8 and later, all visit and plate types are supported in DFengage as long as the visit is required with a schedule date and the plate is required at one of those visits. All conditional maps as well as missed visit plates, early termination plates, and termination visit dates are now supported. DFengage uses the Cycle Visits report to determine which visits are required and when they are due.
Notifications for new activities are sent on the day the visit becomes due according to the “Due” property in the Visit Map (in DFdiscover version 5.8 and later, see the Schedule Date in the Cycle Visits report), at the time defined as described above. If an activity is not completed and becomes overdue according to the “Overdue” property in the Visit Map, an overdue notification is sent on that day at the same time as the initial notification. All plates within a visit become due and overdue at the same time.
If custom timing is required for a specific activity, include the “T-XX:XX” notation at the end of the visit label in the Visit Map where needed, as described above. This also allows for scheduling of multiple activities in a day.
By default, if a subject does not complete an activity in DFengage, the activity remains available for completion in the app until the record is completed in DFengage or another application (e.g., DFweb, DFcollect, or DFexplore). Records set as missed are excluded from DFengage in DFdiscover 5.6 and later.
To automate the removal of activities that have not been completed in DFengage within a specific time window, consider including a hidden field on each ePRO plate to function as the “expiry” indicator. Using edit checks run in batch, identify which records have expired based on the study schedule and mark the hidden field. This will remove the activity from DFengage, once the app syncs with the DFdiscover server. If the participant completed the activity offline and later syncs the data with the server after the records has “expired”, the data will still be received.
Use the Translations configuration in DFsetup to define study languages and provide translations of the page labels, field prompt, instructions, choice and check field labels, units, and help. Note that ePRO custom properties such as plate footnotes and additional VAS text are not supported at this time. Refer to Study Setup User Guide, Translations for details.
The DFengage app interface is available in English, Spanish, and French. DFengage updates the app interface language based on the user’s device language setting. Where possible, during app setup after login, DFengage will automatically select the study language that matches the device language, when the study language is defined in DFsetup as “English”, “Spanish”, or “French”. If no match is found, the DFengage user is prompted to select a language from the list defined for the study.
If the user’s device language changes after login, the DFengage interface language is updated, but the study language remains the same. To change the study language, the user must log out of DFengage and log back in. The study language selected during app setup (automatically or manually by the user) is shown on the Settings page in DFengage.
If any setup changes are made after data collection begins, those changes are available to DFengage users the next time they open the app while online.
Changes to the study setup such as typo corrections in the prompt, description, instruction, or code labels; field or plate help updates; visit, plate, or plate label changes; store length increases; field grouping changes; or changes to legal range, need, units, and skip do not impact the data structure and can be implemented without risk of data loss.
However, structural changes to the database must be taken with care since these may lead to data loss. These include changing data type, changing data format, reducing store length, changing code numbers, and adding, removing, or reordering fields. If study participants are completing activities in DFengage using an older database structure, data may be lost when it is synced with the DFdiscover server where the database structure has been changed.
If database structure changes are required for your study after data collection begins, consider creating a new plate (and visit, if appropriate) for this data and decommissioning the old plate (by changing role permissions) once all data has been received.
Refer to Study Setup User Guide, Modifying Plates that Contain Data for more details on making mid-study changes.
DFengage relies on the role permissions and user accounts defined in DFadmin. This section describes the configuration required in DFadmin to support DFengage use.
The definition of the role assigned to DFengage users has specific requirements outlined below.
Role Name
Tools & Reports
Under DFexplore, check Data.
Under API Clients, check DFengage.
Permissions
View only access is required to the visit and plate where the baseline visit date is captured. In DFdiscover 5.8 or later, view only access is also required to any visits and plates that determine ePRO visit and plate requirements, such as data referenced in conditional maps, cycle scheduling, termination visits and plates, and missed visit plates.
For view only access, leave Modify, Write, Data, Queries, and Reasons permissions blank. View only records are not displayed in DFengage.
Write access is required for scheduled ePRO visits and plates. For details about which visit and plate types are supported in DFengage, see Visit Scheduling.
Under Modify Levels, include all workflow levels in use to allow DFengage to overwrite any existing data (for example, if an activity is completed offline in DFengage and only synced after the same record was completed in DFweb). Write Level must be 1. Data – C (Create) and M (Modify) and Reasons – M (Modify) permissions are required.
Example database permissions for the ePROdata role are shown below:
Refer to System Administrator User Guide, Roles for complete details about defining and managing roles.
Each DFengage user requires a DFdiscover user account with access to one study, one site, one subject ID, and the ePROdata role defined as described above. DFengage will not work if the user has permissions for more than one study or subject ID. An example DFengage user account is shown below.
Since DFengage users are study participants, personal details such as name and email address must not be recorded in DFadmin. DFengage does not support forgot password or two-factor authentication functionality for this reason.
Refer to System Administration User Guide, Users for complete details about managing users and assigning study permissions. DFengage users may be added in bulk (up to 100 user accounts at one time) using the Add Bulk Users feature in DFadmin.
The DFdiscover server and API used by DFengage may be different versions. For example, your DFdiscover server version may be 5.5 but the DFws API version is 5.7. In this scenario, your study configuration Version Strict setting must be set to “All minor versions supported”. This will enable the different API and server versions to connect to each other.
Refer to System Administrator User Guide, Software Version for complete details about the Version Strict setting.
The following sections outline a few basic troubleshooting scenarios. Knowing the error code and message displayed to the user in DFengage will help resolve issues more quickly. Ask DFengage users to report error codes and share screenshots where possible to help with diagnosing any issues. For technical support, contact the DFnet software support team at help@dfnetresearch.com.
Ensure the user has the correct username, password, server, and API. Contact the DFdiscover system administrator to check for any problems with the DFdiscover server or API, including the server configuration to allow the DFengage app to connect to your DFdiscover server.
In DFadmin, double-check the user account, user permissions, and role definition. The user may have access to only one subject ID in one study with the ePROdata role. Check that the study configuration setting “Version Strict” is set to “All minor versions supported” if your server and API are not the same version.
In DFadmin, double-check the user permissions, role definition, and database permissions. In DFsetup, double-check the visit map definition and the baseline visit date format. In DFexplore, double-check the baseline visit date.
The user must not uninstall or delete DFengage or delete its app data, since this will delete all data stored locally, including partially completed activities and completed activities not yet synced with DFdiscover.
Check that the subject is not locked in DFexplore and that the data record is not locked in DFweb or DFcollect. With the DFengage user, check that they are connected to the internet. Navigate to the History screen in DFengage and check the sync status. If the activity is Pending, click the cloud icon at the top right to send data to the DFdiscover server.
If the user does not open DFengage on their device, their device may stop sending notifications for new or overdue activities. DFengage schedules notifications on the device for the next 72 hours or at least 32 notifications after the app was last accessed. After 72 hours of notifications or 32 total notifications without the user opening the app, the background processes that schedule new notifications on the device may stop working and the user may stop receiving notifications.
We recommend study teams make a plan to follow up with participants if ePRO activities are not received, to avoid missing data and ensure participants are accessing DFengage as expected.
Most error messages in DFengage will include an error code that can be used to help diagnose and resolve the issue. The table below lists all error codes, the error message, the issue, and instructions to resolve the issue.