12 Customizing Online Help

You can customize the help that users can display when using the RDC application. You can create help text for each field in a CRF, modify the existing online help topics installed with RDC, and create help information for CRFs displayed in the Data Entry window.

This chapter includes the following topics:

12.1 Defining Help for the Fields in a CRF

When using RDC to enter and update data in a CRF, users can right-click a field and select Field Help to get more information about the field.

RDC opens the Oracle Clinical Data Collection Help window, which displays the help text for the field's DCM Question Group, the help text for the selected field, and other details. See Figure 12-1.

To define this field-level help, you add text to the Oracle Clinical data collection definitions.

Figure 12-1 Custom Help Text for Fields in a CRF

Description of Figure 12-1 follows
Description of ''Figure 12-1 Custom Help Text for Fields in a CRF''

You can enter CRF field help text in Oracle Clinical at the study level for:

  • DCM question groups

  • Individual DCM questions within a group

Note:

You can define help text for active or provisional DCMs only.

To enter help text for a DCM question group and its DCM questions: 

  1. Open Oracle Clinical.

  2. Navigate to Definition, DCMs, and then select DCMs.

  3. Select the study where you are defining help text. The Maintain Study DCMs form opens.

  4. Select a DCM and then click DCM Question Groups. The DCM Question Groups form opens, listing the question groups that are part of the study's DCM.

    To define help text for a DCM question group:

    1. Select a question group.

    2. Scroll to the right until you view the Help Text field.

    3. Enter up to 200 characters of text.

    To define help text for an individual question in a DCM question group:

    1. Select a question group.

    2. Click DCM Questions. The DCM Questions form opens, displaying the individual questions that comprise the question group.

    3. Scroll to the right until you view the Help Text field.

    4. Enter up to 200 characters of text.

  5. Save your changes and regenerate the CRF.

12.2 Customizing Online Help

RDC includes context-sensitive online help files that describe using the application's features. Users invoke the online help by clicking the Help link or button displayed on the application pages, in the Data Entry window, or in a dialog box.

The online help includes several navigation frames and a large content frame that displays the contextual topics. The topic files are in HTML format and are generated from the Oracle Clinical Remote Data Capture User's Guide content. You can customize a copy of the online help files and redirect RDC to display your copy.

Note:

The online help is dynamically generated and changes may not be consistent between generations. Oracle does not document changes to the structure or content of the online help between upgrades. If you customize the online help, you may have to reconcile your changes after installing a patch or an upgrade. Release notes indicate if the patch or upgrade affects the online help.

The tasks required to customize the RDC online help are as follows:

12.2.1 Copying the RDC Help Files

The online help files for RDC are bundled within the olsardc.ear and are extracted on deployment in a location like:

middleware_home\user_projects\domains\OPADomain\servers\AdminServer\upload\olsardc\5.x-b2\app\olsardc.ear\RdcSurroundAdfWebUIWebApp.war\xhelp\rdc\footprint\

Above, the x in 5.x represents the minor release version of the application that is currently installed.

To edit the contents of the archive, you need to open it and add files to the package, as sown in the following steps.

  1. Log in to the administrator server console for the OPA domain and locate the olsardc.ear file. See "Locating the olsardc.ear File" for more information.

  2. Open the olsardc.ear file using any utility to unzip.

    Note:

    Also see "Manually Extracting and Repacking the olsardc.ear File" for an alternative method to unzip and rebuild the EAR file.

  3. Edit the web.xml file to divert the call to the new location of the help files. See "Diverting the Help Call to a Custom Location" for instructions.

    The context-sensitive help calls from RDC require the directory structure for your customized online help to match the help directory structure provided within RDC.

    You can locate your custom help directory on the shared drive of another application server, but the new location must be accessible by URL.

  4. Navigate to the following path:

    middleware_home\user_ projects\domains\OPADomain\servers\AdminServer\upload\olsardc\5.x-b2\app\olsardc.ear

  5. Add or edit help files as required.

  6. Save your changes.

  7. Redeploy olsardc.ear.

    See "Redeploying RDC with Customizations" for more information.

  8. Restart the OPA server.

    See "Restarting the OPA Server" for more information.

Note:

Do not place your custom help directory in the same directory where the Oracle-provided online help is installed:

middleware_home\user_projects\domains\OPADomain\servers\AdminServer\upload\olsardc\5.x-b2\app\olsardc.ear\RdcSurroundAdfWebUIWebApp.war\xhelp\rdc\footprint\

The x in 5.x above represents the version of the application installed.

This directory may be overwritten by subsequent upgrades or patches.

12.2.2 Identifying Individual Topic Files

The RDC online help system does not use file names in its context calls. Therefore, the most reliable method for identifying a topic's file name is to invoke the topic from RDC and then open the Properties dialog box.

To identify the file name of a help topic: 

  1. Open RDC to the feature you are documenting.

  2. Click Help to open the help topic in a new browser window.

  3. Right-click the topic area of the window, and then select Properties.

  4. Note the address listed in the Address (URL) field. The file name for the selected topic is located at the end of the URL address as filename.html. See Figure 12-2.

Note:

Be careful to immediately identify the topic file after you open it from RDC. If you use the help system's navigation aids to browse, you might open another topic file instead of the topic file you want to edit.

Figure 12-2 Identifying the File Name of Individual Help Topics

Description of Figure 12-2 follows
Description of ''Figure 12-2 Identifying the File Name of Individual Help Topics''

12.2.3 Modifying the Topic Text

To modify the text for an online help topic: 

  1. Navigate to the directory location of your customized online help files.

  2. Open the file that you identified as the HTML file associated with the topic you want to modify.

  3. Edit the text.

  4. Save your changes.

When modifying a help topic, keep the following issues in mind to ensure that you retain RDC's context-sensitivity:

  • Do not change header content, file names, anchors, or other metadata. The topic files include metadata identifiers for the context calls from RDC and for navigating and searching. Changing this metadata may break the context calls from the application or the system's navigation aids.

  • Save the file with the same name and to the same relative location.

12.2.4 Diverting the Help Call to a Custom Location

When a user clicks Help in RDC, the application constructs a URL based on the current session and the default installation location of the online help system.

To divert the help call to the custom location you created in Section 12.2.1, you edit the OPA_DOC_DIR parameter in the web.xml file.

To divert the help call to a custom location: 

  1. Log into the admin server console for the OPADomain and locate the olsardc.ear file. See Section D.1, "Locating the olsardc.ear File" for more information.

  2. Open olsardc.ear using any utility to unzip.

  3. Navigate to the location of web.xml at the following path:

    middleware_home\user_projects\domains\OPADomain\servers\AdminServer\upload\olsardc.ear\RdcSurroundAdfWebUIWebApp.war\WEB-INF\

  4. Open the web.xml file with a text editor.

  5. Insert the following lines in the file:

    <context-param>
        <param-name>OPA_DOC_DIR</param-name>
        <param-value>%HTTP URL OF THE Custom Location%</param-value>
    </context-param>

    Note:

    If you do not specify a location for the OPA_DOC_DIR parameter, RDC opens the topic files from the default installation location.

  6. Replace %HTTP URL OF THE Custom Location% with the location of your customized online help files. The syntax of the location is as follows:

    https://help-doc-hostname/directory-name/xhelp

    For example, https://appserverurl/opa52/xhelp.

    Note:

    Do not add a slash (/) to the end of the URL. RDC adds a slash and several parameters to the URL to open the file.

  7. Save your changes.

  8. Click OK when prompted to replace the modified files in the .war and .ear. files

  9. Close the unzip utility.

  10. Redeploy the olsardc.ear file and then restart the OPA server for the changes to take effect.

    See Section D.4, "Redeploying RDC with Customizations" for instructions.

12.3 Defining Help for CRFs

To enter and update data in a CRF, users open the CRF in a Data Entry window. By default, the Data Entry window does not display the Help icon in its toolbar.

RDC adds the Help icon to the toolbar only if you create the context-sensitive help that displays when the user clicks the icon.

Description of help_icon.gif follows
Description of the illustration ''help_icon.gif''

To create custom help text for the Help icon, you use the Maintain Links form in the RDC Administration application. For more information, see Section 11.6, "Defining a Link for CRF Help."