Cancer Trials Support Unit - Welcome to the CTSU …...WESTAT, Cancer Trials Support Unit 1600 Research Boulevard Rockville, Maryland 20850 CTSU Image Portal Rave Custom Function Setup

CTSU Cancer Trials Support Unit

July 12, 2013

CTSU Image Portal Rave Custom Function Setup Guide

Revision 1.5

CTSU Image Portal Rave Custom Function Setup Guide Version 1.5 July 12, 2013 Page ii

Document Information

Revision Information for the CTSU Image Portal Rave Custom Function Setup Guide Version 1.5

Revision History

# Date By Description

00a 03/21/2013 Vikas Gourishetty How to import the custom function to an existing draft

00b 03/25/2013 Vikas Gourishetty Addressed the review comments

00c 03/26/2013 Mark Stauffer Updated styles and added instruction content.

1.0 03/26/2013 Vikas Gourishetty Made changes to document after session with Mark Stauffer

1.1 03/29/2013 Mark Stauffer Updated the document per discussions with Vikas Gourishetty.

1.2 04/04/2013 Vikas Gourishetty Updated the Excel file type to xml spreadsheet.

1.2a 6/26/2013 Phoebe Whitefield Reviewed document and verified the ALS

1.3 6/26/2013 Mark Stauffer Updated the document to include information regarding log lines.

1.3 7/2/2013 Kathi Celii Reviewed the document

1.4 7/3/2013 Mark Stauffer Accepted document changes, updated the document name.

1.5 7/12/2013 Mark Stauffer Accepted Phoebe and Ravi’s changes, addressed their comments.

Last Saved By Phoebe Whitefield on 7/12/2013 3:07:00 PM

File Location: R:\Tasks\8339_14_CDMS\21_FaxSolnRaveImages\Releases\1.0\SDLC\CTSU-CIP-RaveCustomFunctionSetupGuide.docx

This document was prepared by:

WESTAT, Cancer Trials Support Unit 1600 Research Boulevard Rockville, Maryland 20850

CTSU Image Portal Rave Custom Function Setup Guide Version 1.5 July 12, 2013 Page iii

Table of Contents 1. INTRODUCTION .................................................................................................................... 1

1.1 BACKGROUND .................................................................................................................... 1 1.2 AUDIENCE ......................................................................................................................... 1 1.3 ORGANIZATION OF THIS DOCUMENT ........................................................................................ 1

2. HOW TO SETUP A FILE UPLOAD FIELD FOR A RAVE FORM ................................................... 2

2.1 OVERVIEW......................................................................................................................... 2 2.2 IMPORT CUSTOM FUNCTION TO THE EXISTING DRAFT IN A RAVE PROJECT ......................................... 2

2.2.1 Instructions for Importing the Custom Function to Rave: .................................................... 2 2.3 DESIGNATE TWO FIELDS IN THE FORM FOR THE FILE UPLOAD FEATURE ............................................. 4

2.3.1 Configuring Field #1 (the File Upload Field) ......................................................................... 4 2.3.2 Configuring Field #2 (the Date Field) ................................................................................... 5

2.4 CONFIGURE EDIT CHECKS FOR FIELD #2 (DATE FIELD) .................................................................. 8 2.4.1 Add Check for Field #2 (Date Field) ..................................................................................... 8 2.4.2 Add Check Action for Field #2 (Date Field) ........................................................................ 10

2.5 ADD THE DERIVATION AND DERIVATION STEP FOR FIELD #2 (DATE FIELD) ...................................... 11 2.5.1 Adding the Derivation and Derivation Step for Field #2 ..................................................... 11

2.6 PUBLISH AND PUSH THE DRAFT............................................................................................. 12

3. ADDITIONAL INFORMATION .............................................................................................. 14

3.1 USING MORE THAN ONE FILE UPLOAD FIELD FOR A STUDY.......................................................... 14

CTSU Image Portal Rave Custom Function Setup Guide Version 1.5 July 12, 2013 Page iv

List of Figures FIGURE 1: VALUES THAT NEED TO BE ENTERED IN THE ALS FILE ................................................................... 3 FIGURE 2: EXAMPLE VALUES ............................................................................................................... 3 FIGURE 3: UPLOAD THE ALS FILE TO AN EXISTING DRAFT ........................................................................... 3 FIGURE 4: CONFIRM THAT THE SET_COVER_SHEET_URL CUSTOM FUNCTION IS VISIBLE IN THE DRAFT ................. 4 FIGURE 5: TWO FIELDS THAT WERE USED IN THIS EXAMPLE FOR CONFIGURING THE FILE UPLOAD FEATURE ............ 4 FIGURE 6: VARIABLE AND FIELD SETTINGS FOR FIELD #1 ............................................................................ 5 FIGURE 7: CONFIGURE FIELD #1 AS A REQUIRED ...................................................................................... 5 FIGURE 8: THE PROPER FORMAT VALUE MUST BE USED ........................................................................... 6 FIGURE 9: DATETIME NEEDS TO BE SELECTED FOR THE CONTROL TYPE .......................................................... 6 FIGURE 10: CONFIGURE FIELD #2 AS A REQUIRED .................................................................................... 7 FIGURE 11: VIEWING OF THE FORM DATE FIELD IS RESTRICTED TO POWER USERS ........................................... 7 FIGURE 12: ENTRY OF THE FORM DATE FIELD IS RESTRICTED TO POWER USERS .............................................. 7 FIGURE 13: CLICK THE ADD CHECK BUTTON ........................................................................................... 8 FIGURE 14: SET THE NAME TO COVER_SHEET_URL .................................................................................. 8 FIGURE 15: CLICK THE CHECK STEPS BUTTON ......................................................................................... 8 FIGURE 16: CLICK THE ADD CHECK STEP BUTTON .................................................................................... 9 FIGURE 17: VALUES SELECTED FOR THE TYPE, FOLDER, AND FORM FIELDS FOR THE “CHECK STEPS” SECTION ......... 9 FIGURE 18: VALUES SELECTED FOR THE FIELD, REC. POS., AND DATA VALUE FIELDS FOR THE "CHECK STEPS"

SECTION .................................................................................................................................. 9 FIGURE 19: VALUES SELECTED FOR THE TYPE AND STEP FIELDS FOR THE SECOND CHECK STEP .......................... 10 FIGURE 20: CLICK THE "ADD CHECK ACTION" BUTTON ........................................................................... 10 FIGURE 21: VALUES SELECTED FOR THE FOLDER AND FORM FIELDS FOR THE "CHECK ACTIONS" ........................ 10 FIGURE 22: VALUES SELECTED FOR THE FIELD AND REC. POS. FIELDS FOR THE "CHECK ACTIONS" ...................... 10 FIGURE 23: VALUES SELECTED FOR THE ACTION TYPE AND CUSTOM FUNCTION FIELDS FOR THE "CHECK ACTIONS"11 FIGURE 24: CLICK THE ADD DERIVATION BUTTON .................................................................................. 11 FIGURE 25: VALUES FOR THE NAME, FOLDER, AND FORM FIELDS FOR THE DERIVATION CONFIGURATION ............ 11 FIGURE 26: VALUES FOR THE FIELD AND REC. POS. FIELDS ON FOR THE DERIVATION CONFIGURATION ................ 12 FIGURE 27: CLICK THE DERIVATION STEPS BUTTON ................................................................................ 12 FIGURE 28: CLICK THE ADD DERIVATION STEP LINK ................................................................................ 12 FIGURE 29: SELECT THE TYPE AND STEP FOR THE “ADD DERIVATION STEP” CONFIGURATION ........................... 12 FIGURE 30: ENTERING A CRF VERSION NAME AND PUBLISHING THE CRF VERSION ....................................... 13 FIGURE 31: THE CRF VERSION APPEARS IN THE EXISTING VERSIONS SECTION AFTER BEING PUBLISHED .............. 13 FIGURE 32: SELECT THE STUDY TAB .................................................................................................... 13 FIGURE 33: PUSH THE CRF VERSION .................................................................................................. 13 FIGURE 34: CRF VERSION SUCCESSFULLY PUSHED ................................................................................. 14

Introduction

CTSU Image Portal Rave Custom Function Setup Guide Version 1.5 July 12, 2013 Page 1 of 14

1. Introduction This document provides instructions for setting up the file upload custom function for Rave forms.

1.1 Background The CTSU Document Image Portal provides Rave users with the ability to fax in supporting documentation for Rave Case Report Forms (CRFs). The integration converts received faxes into PDF format, inserts the PDF files into the appropriate Rave CRFs, and notifies users by email once the upload process completes.

This system was created at the request of the Lead Protocol Organizations (LPOs) to assist Rave users who do not have the ability to scan and upload supporting documents into Rave CRFs.

The integration involves existing systems (such as Rave, CTSU’s Fax Server infrastructure, and CENTER) and a new CTSU Cover Page website.

Despite the complexity of the systems involved, the integration has been seamlessly integrated with Rave to provide an intuitive user experience.

As part of the form setup process, a hidden date field has to be created in each form that will use a file upload field, and a custom function needs to be uploaded and configured for a Rave study CRF version in order for the file upload feature to function properly. Those items will be described in detail within this document.

1.2 Audience This document was created for LPO users.

1.3 Organization of this Document Section 2 provides instructions for setting up the file upload custom function. Section 3 provides additional information regarding the custom function.

How to Setup a File Upload Field for a Rave Form


2. How to Setup a File Upload Field for a Rave Form This section will detail the steps needed to setup the file upload field on a Rave form for a study that already has a published CRF Version for the draft that is being used.

2.1 Overview The process involves these main steps:

1) Importing the custom function to an existing draft in a Rave project. This custom function is triggered when the form is modified. When the custom function is invoked, the Fax Cover page generation URL link is displayed to the Rave Login user. A unique fax tracking number is assigned each time this URL link is invoked within Rave.

2) Designating two fields in the Rave form for the file upload feature. The fields are:

a) Field configured with the Rave File Upload data type, for the document to attach to. The form can have one to many Rave File Upload data type fields. Each of Rave File Upload field has its own fax cover page URL link.

b) A Single hidden date field to trigger the custom function imported in step 1

3) Configuring the edit checks on the hidden date field. When this edit check condition is met, the custom function will be invoked to generate the fax cover page URL link.

4) Adding the derivation and derivation step for the date field. This step is needed to complete the custom function trigger.

5) Publishing and pushing the draft to the site. 6) Perform user acceptance testing to verify the configuration is correct.

The study S0816 was used for these instructions; however this setup can be applied to any study and any form.

2.2 Import Custom Function to the Existing Draft in a Rave Project The first step in setting up a form to use the document upload feature is importing the custom function into the existing draft.

The custom function can be downloaded from the following location:

https://www.ctsu.org/cip/CIP-CustomFunction.xml

Please note that Rave requires the file extension to be XML.

2.2.1 Instructions for Importing the Custom Function to Rave: 1) Open the XML file directly from this document (it will open in Excel). 2) Save the file to your desktop. 3) In the XML file, update the following fields as shown in Figure 1. Example values are provided in

Figure 2.

a) Enter the DraftName. Use the name of the existing draft.

b) Enter the study name under the cell for ProjectName.

https://www.ctsu.org/cip/CIP-CustomFunction.xml



c) Enter the PrimaryFormOID. This value can be located within the draft for the study, inside the Matrices section.

d) Enter the DefaultMatrixOID. This value is always going to be PRIMARY_MATRIX.

Figure 1: Values that need to be entered in the ALS File

Figure 2: Example Values

4) In Rave, navigate to Architect, and then click Upload Draft.

5) Click Browse, select the modified ALS file in the popup window and click Open, and click Upload. Once the upload is complete the message “Save Successful” will appear (Figure 3).

Figure 3: Upload the ALS file to an Existing Draft

6) When you are done uploading the draft:

a) Click on the Architect module.

b) Select the study under the Active Projects section.

c) Click the draft name under the CRFDrafts section.

d) Click Custom Functions under Draft Items.

e) Confirm the custom function set_cover_sheet_url is visible, as shown in Figure 4.



Figure 4: Confirm that the Set_Cover_Sheet_Url Custom Function is Visible in the Draft

2.3 Designate two Fields in the Form for the File Upload Feature This section will describe how to designate two fields (a file upload field, and a date field) that are necessary for using the file upload feature. There are no standard field names for these two fields, however it is recommended to use the naming in the examples for the hidden date field since it matches the edit check setup that is illustrated in this document (Figure 5 shows the two fields that were used for the purpose of this example).

Figure 5: Two Fields that were Used in this Example for Configuring the File Upload Feature

2.3.1 Configuring Field #1 (the File Upload Field) This section will describe how to designate the form and field that will receive an uploaded document.

7) While in the draft for the study, click the Forms tab under Draft Items.

8) Click the Fields icon for the form that will contain the file upload field (the “PET Course” form is used in this example).

9) Click the Edit icon for the field you want to use as the file upload field: In our example, we chose Field #1 (as shown in Figure 5). If a field is not present, one can manually be created in Rave by clicking the “Add New” link (selecting “Bottom” in the drop-down menu), and using the settings shown below.

a) Make sure that ‘File Upload’ is selected from the Control Type for Field #1 (as shown in Figure 6).



Figure 6: Variable and Field Settings for Field #1

b) Make the field required by selecting Auto-Query for required data entry under the “Field Edit Checks” section (as shown in Figure 7).

Figure 7: Configure Field #1 as a Required

c) Click Save.

2.3.2 Configuring Field #2 (the Date Field) This section will describe how to designate a date field that will trigger the custom function.

10) While in the file upload form for the study, select the Edit icon for the date field that you want to use to trigger the custom function: In our example, we chose Field #2 (as shown in Figure 5). This field will be configured to remain hidden to most users, and to automatically update once the user



saves the form. If a field is not present, one can manually be created in Rave by clicking the “Add New” link (selecting “Bottom” in the drop-down menu), and using the settings shown below.

11) Within the Variable section, set the VarOID and Format (as shown in Figure 8):

a) Set the VarOID for Field #2 to FORM_DT_INV

b) Set the Format of Field #2 to dd MMM yyyy HH:nn:ss

Figure 8: The Proper Format Value Must be Used

c) Set the Control Type drop down to DateTime (as shown in Figure 9).

Figure 9: DateTime needs to be Selected for the Control Type

d) Make the field required by selecting Auto-Query for required data entry under the “Field Edit Checks” section (as shown in Figure 10).



Figure 10: Configure Field #2 as a Required

e) Make the field invisible and not editable for all users except those with the Power User role: i) Restrict view privileges to users with the Power User role, by checking all of the checkboxes

in the View Restrictions section, except for the Power User (see Figure 11).

Figure 11: Viewing of the Form Date Field is Restricted to Power Users

ii) Restrict data entry privileges to users with the Power User role, by checking all of the checkboxes in the Entry Restrictions section, except for the Power User (see Figure 12).

Figure 12: Entry of the Form Date Field is Restricted to Power Users



f) Click Save.

2.4 Configure Edit Checks for Field #2 (Date Field) This section will describe how to create an edit check (using the date field) that will trigger the custom function when the value of Field #2 changes, which will occur when a Rave user saves their form.

2.4.1 Add Check for Field #2 (Date Field) 12) Click Edit Checks under Draft Items, and click the Add Check link (see Figure 13).

Figure 13: Click the Add Check Button

13) Provide ‘cover_sheet_url’ as the Name for the edit check and click Update (see Figure 14).

Figure 14: Set the Name to cover_sheet_url

14) Click on the Check Steps button (see Figure 15).

Figure 15: Click the Check Steps Button

15) Add the edit check:

a) Click Add Check Step under the Check Steps section (see Figure 16).



Figure 16: Click the Add Check Step Button

b) Select ‘Data Value’ as the Type, and select the Folder and Form where you have created the Field #1 and Field #2, as mentioned in the sections 2.3.1 & 2.3.2 of this document (see Figure 17).

Figure 17: Values Selected for the Type, Folder, and Form Fields for the “Check Steps” Section

c) Select the date field (Field #2) as the field, enter 0 for the Rec. Pos., and select Data Point as the Data Value (see Figure 18).

Figure 18: Values Selected for the Field, Rec. Pos., and Data Value Fields for the "Check Steps" Section

d) Click the Update button.

16) Create a second Check Step:

a) Click the Add Check Step button under the Check Steps section.

b) Set the Type as ‘Check Function’, and set the Step as ‘IsPresent’ (see Figure 19).



Figure 19: Values Selected for the Type and Step Fields for the Second Check Step

c) Click the Update button.

2.4.2 Add Check Action for Field #2 (Date Field) Once the check steps have been added, the Check Action needs to be created.

17) Configure the Data Point:

a) Click the Add Check Action link under the Check Actions section (see Figure 20).

Figure 20: Click the "Add Check Action" Button

b) Select the Folder and Form where you created Field #2 (see Figure 21).

Figure 21: Values Selected for the Folder and Form Fields for the "Check Actions"

c) Select the field using Field #2, and enter ‘0’ for the Rec. Pos. (see Figure 22).

Figure 22: Values Selected for the Field and Rec. Pos. Fields for the "Check Actions"



d) Set the Action Type to ‘Custom Function’, and set the Custom Function to ‘set_cover_sheet_url’ (see Figure 23).

Figure 23: Values Selected for the Action Type and Custom Function Fields for the "Check Actions"

e) Click the Update button.

2.5 Add the Derivation and Derivation Step for Field #2 (Date Field) The derivation for Field #2 will be setup in this section.

2.5.1 Adding the Derivation and Derivation Step for Field #2 18) Click the Derivations section under Draft Items.

19) Click the Add Derivation link (see Figure 24).

Figure 24: Click the Add Derivation Button

20) Make the following entries:

a) Enter FORM_DT_INV in the Name field (this value can be modified as needed), and select the Folder and Form where Field #2 was created (see Figure 25).

Figure 25: Values for the Name, Folder, and Form Fields for the Derivation Configuration

b) Select Field #2 (the date field) as the field, and set Res. Pos. to 0 (see Figure 26).



Figure 26: Values for the Field and Rec. Pos. Fields on for the Derivation Configuration

c) Click the Update button.

21) Click the Derivation Steps button (see Figure 27).

Figure 27: Click the Derivation Steps Button

22) Click the Add Derivation Step link (see Figure 28).

Figure 28: Click the Add Derivation Step Link

23) Select Step Function for Type, and select Now for the Step (see Figure 29).

Figure 29: Select the Type and Step for the “Add Derivation Step” Configuration

24) Click the Update button.

2.6 Publish and Push the Draft Now that the custom function has been setup, the hidden date field is created, and the edit check is configured to trigger the custom function the draft needs to be published and pushed.

25) Select the study within Architect.

26) Select the draft within the CRFDrafts section.



27) Enter a unique name in the CRF Version field and click Publish to CRF Version (see Figure 30). The published CRF Version will appear under the Existing Versions section of the Publish section (see Figure 31).

Figure 30: Entering a CRF Version Name and Publishing the CRF Version

Figure 31: The CRF Version Appears in the Existing Versions Section after Being Published

28) Click the study tab (see Figure 32).

Figure 32: Select the Study Tab

29) Click the Push button next to the CRF Version that was just published (see Figure 33).

Figure 33: Push the CRF Version

30) Select the appropriate environment in the To Study drop-down menu, leave “All Sites” selected in the To Sites field, and click the Push button.

Additional Information


31) Upon completion of the push, a message will appear that will state the CRF Version was successfully pushed (see Figure 34).

Figure 34: CRF Version Successfully Pushed

32) The document upload feature is now configured for the study’s form. Please view the User Acceptance Testing Guide for instructions on testing the feature, which can be found at https://www.ctsu.org/cip .

3. Additional Information

3.1 Using More than One File Upload Field for a Study The file upload feature can be used for multiple fields within the same Rave form, and on more than one Rave form for the same study. Simply repeat the steps listed in sections 2.3 through 2.6.

If a file upload field is being configured for a form that already has the hidden date field configured (per the instructions in this document), then skip sections 2.2.2, 2.3, and 2.4 when setting up the additional file upload field.

https://www.ctsu.org/cip

Cancer Trials Support Unit - Welcome to the CTSU …...WESTAT, Cancer Trials Support Unit 1600 Research Boulevard Rockville, Maryland 20850 CTSU Image Portal Rave Custom Function Setup

Documents