11 Configuring Links

You can use the Maintain Links form in the RDC Administration application to add customized links to RDC. Any information that can be made available through a URL can be made accessible to RDC users.

In addition, your customized links support passing session details to a URL or database function. Therefore, you can link to pages that are context-sensitive to a user's current RDC environment.

For example, you can configure a URL that RDC displays in the Links section on the Home page. The link adds a parameter string with the session's user role value to the URL. You can write a target page that switches the content according to user role. A site user, data manager, and investigator can then view different content from the same link.

This chapter includes the following topics:

11.1 About Custom Links

In the Maintain Links form, you can customize links that display in the RDC application. You can define links for:

  • The Links section on the Home page

  • The Links section in a Patient Summary Report

  • The CRF Help icon when viewing and updating a CRF in the Data Entry window

When you create these links, you can restrict the audience for the link. You can define who has access to the link and the associated Web page. Access can range from no restriction (for all users) to very restricted access (for users with a certain role only).

Note:

You do not configure other custom links, such as a News link or an Activity link, in the Maintain Links form. For more information on customizing those links, see Chapter 9, "Configuring News" and Chapter 10, "Customizing Activities."

11.1.1 Links on the Home Page

In RDC, the Links section on the Home page displays your customized links to other Web sites or applications. See Figure 11-1. The Home page supports an unlimited number of links. You can also change the title of the Links section.

Figure 11-1 Sample Customized Links on the Home Page

Description of Figure 11-1 follows
Description of ''Figure 11-1 Sample Customized Links on the Home Page''

11.1.2 Links on the Patient Summary Report

RDC lets you display a maximum of three patient links in the Links section of a Patient Summary Report. See Figure 11-2.

In a typical patient link, RDC passes parameters to a custom SQL program and opens a new browser window. The custom program queries the database for patient data and presents a custom report in the new browser window.

Figure 11-2 Links Displayed in the Patient Summary Report

Description of Figure 11-2 follows
Description of ''Figure 11-2 Links Displayed in the Patient Summary Report''

11.1.3 A Link for CRF Help

You can configure one link for the CRF Help icon in the toolbar in the Data Entry window. When the user clicks the icon, RDC opens a new browser window to the link's target location. RDC displays the CRF Help icon only if you define and enable a link in the Maintain Links form.

Figure 11-3 Customizing Help for the CRF

Description of Figure 11-3 follows
Description of ''Figure 11-3 Customizing Help for the CRF''

11.2 Using the Maintain Links Form

To access the Maintain Links form: 

  1. Log in to the RDC Administration application.

  2. Select Maintain, and then select Links.

Figure 11-4 shows the Maintain Links form.

Figure 11-4 Maintain Links Form

Description of Figure 11-4 follows
Description of ''Figure 11-4 Maintain Links Form''

11.2.1 Ordering the Display of Links

Use the Seq# field to specify the order in which a link appears in its section in RDC. The value for each Seq# must be unique for all links that appear in RDC.

11.2.2 Defining the Link Text

Use the Link Text field to specify the text for the link label.

RDC uses this text when listing the links on the Home page and in the Patient Summary Report.

11.2.3 Specifying the URL or Function

Use the URL field to specify either the URL or the function name, depending on whether you are creating a static link or a dynamic link:

  • For a static link, enter the URL of the target Web page. The URL must work when RDC appends the parameters listed in Table 11-2, even if you do not take advantage of the parameters.

  • For a dynamic link, enter the specification for the function. The function must handle the parameters specified in Table 11-3.

11.2.4 Specifying the Type of Link

Use the Type field to specify the type of link you are creating. You can define two type of links for use in the RDC application:

  • Static links

  • Dynamic links

Both types of links support passing parameter values to a URL. Therefore, you can link to pages that are context-sensitive to a user's current RDC environment.

The two types of links differ in the way RDC generates the URLs.

For static links, RDC appends a parameter string of session information to the target URL you specified in the URL field. You must write a target URL page, such as a JavaServer page, that can process the parameters. Note that for a static link with a scope of None, RDC passes a URL without a parameter string.

For dynamic links, RDC derives the URL from the return value of the database function you specified in the URL field. The database function also takes parameters. You must create the target URL page. Dynamic links trigger your own functions to return URLs.

11.2.5 Specifying the Link Scope

The scope of a link determines two factors: where RDC displays the link and which parameter values RDC passes to either the URL or the function.

  • Links of scope None, User, Study, and Site display in the Links section on the Home page. The Home page supports an unlimited number of links.

  • Links of scope Patient display in the Links section of a Patient Summary Report. You can define a maximum of three links to display in a Patient Summary Report. In the Maintain Links form, you select the Use Pt/CRF Link in Onsite check box to mark up to three links to display in the Patient Summary Report.

  • A link of scope CRF configures a link for the CRF Help icon in a Data Entry window. In the Maintain Links form, you select the Pt/CRF Link in Onsite check box for one link.

11.2.6 Enabling Patient Summary and CRF Help Links

The Use Pt/CRF Link in Onsite check box applies only to links of scope CRF or Patient.

RDC lets you display a maximum of three patient links in a Patient Summary Report. It lets you define one link for the CRF Help icon in a Data Entry window.

To specify which patient and CRF links appear in RDC, select the Use Pt/CRF Link in Onsite check box for the appropriate links.

11.3 Link Parameters

Table 11-1 describes all the possible parameters for static links and dynamic links. The scope of a link defines the subset of these parameters that RDC appends to your specified URL or passes to your specified function.

Table 11-1 Parameter Descriptions

Static Links Parameter Name Dynamic Links Parameter Name Database Object Description

userid

pUserId

USERID

Sends the login user ID of the RDC session.

user_role

pUserRole

USER_ROLE

Sends the RDC login user's assigned role value.

test_prod

pTestProd

TEST_PROD

Sends the session's study mode: T for Test mode or P for Production mode.

study_id

pStudyId

CLINICAL_STUDY_ID

Sends the internal Oracle Clinical identifier that corresponds to the STUDY value.

study

pStudy

STUDY

Sends the session's Oracle Clinical Study name.

site_id

pSiteId

SITE_ID

Sends the internal Oracle Clinical identifier that corresponds to the SITE value.

site

pSite

SITE

Sends the session's SITE value.

patient_id

pPatientId

PATIENT_POSITION_ID

Sends the internal Oracle Clinical identifier that corresponds to the PATIENT value.

patient

pPatient

PATIENT

Sends the name of the PATIENT the user is currently viewing.

book_id

pBookId

DCI_BOOK_ID

Sends the internal identifier that corresponds to DCI_BOOKS.NAME.

book

pBook

DCI_BOOKS.NAME

Sends the name of the DCI book the user is currently viewing.

dci_id

pDciId

DCI_ID

Sends the internal Oracle Clinical identifier that corresponds to the user's currently viewed DCI.

cpe_id

pCpeId

CLIN_PLAN_EVE_ID

Sends the internal Oracle Clinical identifier that corresponds to the user's currently viewed Clinical Planned Event.

subno

pSubNo

SUBEVENT_NUMBER

Sends the subevent number.

page_display_sn

PPageDisplaySn

DISPLAY_SN

Sends the DCI's sequence number, its viewing order in the currently viewed DCI Book. DISPLAY_SN is in the DCI_BOOK_PAGES table.

page_no

pPageNo

Sends the derived page number in the currently viewed Data Entry window of a multiple-page DCI.

pHeader

Sends the value of the URL field. This value is used in earlier RDC releases. It is available in dynamic links but not in static links.

pScope

Sends the scope type to a dynamic link function. It is available in dynamic links but not in static links.


11.3.1 Parameters for Static Links Based on Scope

Static links generate a URL from the target HTTP address defined in the Maintain Links form. Based on the scope of the link, RDC appends a subset of parameter values from the user's current session to your specified URL when the user clicks the link.

You create a target Web page that can resolve the parameter values that RDC appends to the URL. You do not have to use all of the parameters, but the target page must be able to open the URL.

Table 11-2 lists the parameter strings that RDC appends to static links, according to the scope of the link.

Table 11-2 Parameter Strings for Static Links

Scope Parameter String Appended to the URL Value

None

RDC appends no parameters to the URL value.

User

?user_role=user_role

Study

?userid=userid&user_role=user_role&test_prod=test_prod
&study_id=study_id&study=study

Site

?userid=userid&user_role=user_role&test_prod=test_prod
&study_id=study_id&study=study&site_id=site_id&site=site

Patient

?userid=userid&user_role=user_role&test_prod=test_prod
&study_id=study_id&study=study&site_id=site_id&site=site
&patient_id=patient_id&patient=patient

CRF

?userid=userid&user_role=user_role&test_prod=test_prod
&study_id=study_id&study=study&site_id=site_id&site=site
&patient_id=patient_id&patient=patient&book_id=book_id
&book=book&dci_id=dci_id&cpe_id=cpe_id&subno=subno
&page_display_sn=page_display_sn&page_no=page_no


11.3.2 Parameters for Dynamic Links Based on Scope

Dynamic links derive an HTTP address from a function. You create a function that returns a URL.

Table 11-3 lists the parameters that RDC passes to a SQL function, according to the scope of the link. All parameters are VARCHAR2 except for the pStudyId and pSiteId parameters, which are NUMBER.

Table 11-3 Dynamic Link Parameters

Scope Parameters Passed to the SQL Function

None

pHeader, pScope

User

pHeader, pScope, pUserRole

Study

pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy

Site

pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy, pSiteId, pSite

Patient

pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy, pSiteId, pSite, pPatientId, pPatient

CRF

pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy, pSiteId, pSite, pPatientId, pPatient, pBookId, pBook, pDciId, pCpeId, pSubNo, PPageDisplaySn, pPageNo


Note:

The Maintain Links form does not verify the existence of, validity of, or access privileges to functions or data.

11.3.2.1 Sample Function Available

Oracle provides the following sample function that you can use when defining links:

dmo_links.geturl

This function is in the rxcpbdmolinks.sql file, which is located in the INSTALL directory.

11.3.2.2 Function Specification for Dynamic Links

The following specification outlines the requirements of the function that is accessed by dynamic links with a scope of CRF.

Note:

A dynamic link with a scope of CRF processes all available session parameters. You can specify functions for dynamic links of other scopes with fewer parameters, but if you use DEFAULT NULL then you can include the extra parameters.
Create or replace FUNCTION sub-program name here(
    , pHeader        IN VARCHAR2 DEFAULT NULL
    , pScope         IN VARCHAR2 DEFAULT NULL
    , pUserId        IN VARCHAR2 DEFAULT NULL
    , pUserRole      IN VARCHAR2 DEFAULT NULL
    , pTestProd      IN VARCHAR2 DEFAULT NULL
    , pStudyId       IN VARCHAR2 DEFAULT NULL
    , pStudy         IN VARCHAR2 DEFAULT NULL
    , pSiteId        IN VARCHAR2 DEFAULT NULL
    , pSite          IN VARCHAR2 DEFAULT NULL
    , pPatientId     IN VARCHAR2 DEFAULT NULL
    , pPatient       IN VARCHAR2 DEFAULT NULL
    , pBookId        IN VARCHAR2 DEFAULT NULL
    , pBook          IN VARCHAR2 DEFAULT NULL
    , pDciId         IN VARCHAR2 DEFAULT NULL
    , pCpeId         IN VARCHAR2 DEFAULT NULL
    , pSubNo         IN VARCHAR2 DEFAULT NULL
    , PPageDisplaySn IN VARCHAR2 DEFAULT NULL
    , pPageNo        IN VARCHAR2 DEFAULT NULL
)RETURN VARCHAR2 IS
BEGIN sub-program logic here
END;

11.4 Creating Links for the Home Page

Links of scope None, User, Study, and Site display in the Links section of the RDC Home page.

The Home page in RDC displays your customized links in the Links section. The Home page supports an unlimited number of links. You can also change the name of the Links section.

Links on the Home page can have one of the following scopes:

  • None — Use this scope to create a link with no parameter information from the user's session. For example, you can create a link to your company's home page.

  • User — Use this scope to generate links targeted to user roles.

  • Study — Use this scope to generate links to study-specific content.

  • Site — Use this scope to generate links to site-specific content.

Table 11-1 describes all the possible parameters for static links and dynamic links. For static links, see Table 11-2 for a list of parameter values that RDC appends to your specified URL based on the scope of the link. For dynamic links, see Table 11-3 for a list of parameter values that RDC passes to your specified function based on the scope of the link.

11.4.1 Defining a Link for the Home Page

To define a link for the Links section on the Home page: 

  1. Log in to the RDC Administration application.

  2. Select Maintain, and then select Links.

  3. Insert or modify a row in the Maintain Links form to have these settings:

    • Seq# — Sequence the rows so they have the same sequence that you prefer in the Links section on the Home page.

    • Link Text — Enter the link label. RDC uses your specified text when listing the links in the Links section on the Home page.

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

    • URL — Enter the URL if you are defining a static link; enter the name of the function if you are defining a dynamic link.

    • Type — Select either Static or Dynamic. (See Section 11.2.4, "Specifying the Type of Link" for more information.)

    • Scope — Select None, User, Study, or Site. The scope determines which parameter values RDC passes to either the URL or the function.

    • Use PT/CRF Link in Onsite — Do not enable this setting. This setting applies only to links of scope CRF or Patient.

  4. Save your changes.

  5. Create a target Web page that can resolve the parameters RDC passes when the user invokes the link.

11.4.2 Parameters for Links with a Scope of None

Use scope type None to create a link with no parameter information from the user's session.

  • For a static link of scope None, RDC does not append a parameter string to the URL.

  • For a dynamic link of scope None, RDC passes the following parameter values to the function:

    pHeader, pScope

11.4.3 Parameters for Links with a Scope of User

Use scope type User to generate links targeted to user roles.

  • For a static link of scope User, RDC appends the following parameter values from the user's session to the URL:

    ?user_role=user_role

  • For a dynamic link of scope User, RDC passes the following parameter values from the user's session to the function:

    pHeader, pScope, pUserRole

See Table 11-1 for a description of each parameter.

Example 11-1 Creating a Dynamic User Link

Sample steps to create a dynamic user link:

  1. Insert a row into the Maintain Links form.

  2. Specify the following values:

    • URL: dynamicUrl.getUsersUrl

    • Type: Dynamic

    • Scope: User

  3. Create a SQL function named getUsers in package dynamicUrl with the following specification:

    function getUsers (pHeader varchar2, pScope varchar2, pUserRole varchar2)
    return varchar2

  4. Write the return clause of the function to return a URL.

11.4.4 Parameters for Links with a Scope of Study

Use scope type Study to generate links to study-specific content.

  • For a static link of scope Study, RDC appends the following parameter values from the user's session to the URL:

    ?userid=userid&user_role=user_role&test_prod=test_prod
    &study_id=study_id&study=study

  • For a dynamic link of scope Study, RDC passes the following parameter values from the user's session to the function:

    pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy

See Table 11-1 for a description of each parameter.

Example 11-2 Static Study Link

Configure a static link of scope Study for the following URL:

https://mycompany.com/study.jsp

If the data manager PRASPADM is viewing the PILOT study, which is in production, RDC generates the following URL:

https://mycompany.com/study.jsp?userid=PRASPADM&user_role=DM&test_prod=P&study_id=28601&study=PILOT

11.4.5 Parameters for Links with a Scope of Site

Use scope type Site to generate links to site-specific content.

  • For a static link of scope Site, RDC appends the following parameter parameter values from the user's session to the URL:

    ?userid=userid&user_role=user_role&test_prod=test_prod
    &study_id=study_id&study=study&site_id=site_id&site=site

  • For a dynamic link of scope Site, RDC passes the following parameter values from the user's session to the function:

    pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy, pSiteId, pSite

See Table 11-1 for a description of each parameter.

Example 11-3 Static Site Link

Configure a static link of scope Site for the following URL:

https://mycompany.com/site.jsp

If the data manager JSMITH at site 001 is running a session in the PDFREPORT study, which is in production, RDC generates the following URL:

https://mycompany.com/site.jsp?userid=jsmith
&user_role=dm&test_prod=P&study_id=55202&study=pdfreport
&site_id=4501&site=001

11.4.6 Customizing the Label for the Links Section

The Label for the Links Tab configuration setting lets you customize the title of the Links section on the Home page. For example, you may want to change the title to More Study Information or Helpful Web Sites.

For more information on customizing the label, see Section 3.3, "Configuration Settings for RDC."

11.5 Defining Links for the Patient Summary Reports

You can define a maximum of three links for the Links section of a Patient Summary Report. These links have a scope of Patient.

To define a link for the Patient Summary Report: 

  1. Log in to the RDC Administration application.

  2. Select Maintain, and then select Links.

  3. Insert or modify a row in the Maintain Links form to have these settings:

    • Seq# — You can define up to three links for the Patient Summary Report. Sequence the Patient-scope rows so they have the same sequence that you prefer in the report's Links section.

    • Link Text — Enter the link label.

    • URL — Enter the URL if you are defining a static link; enter the name of the function if you are defining a dynamic link.

    • Type — Select either Static or Dynamic. (See Section 11.2.4, "Specifying the Type of Link" for more information.)

    • Scope — Select Patient.

    • Use PT/CRF Link in Onsite — Enable this check box. You can select up to three rows with a scope of Patient.

  4. Save your changes.

  5. Create a target Web page or JavaServer page referred to by the static URL, or the dynamic return value of the function you specified.

11.5.1 Parameters for a Patient Link

Use scope type Patient to create links for the Patient Summary Report.

  • For a static link of scope Patient, RDC appends the following parameter values from the user's session to the URL:

    ?userid=userid&user_role=user_role&test_prod=test_prod
    &study_id=study_id&study=study&site_id=site_id&site=site
    &patient_id=patient_id&patient=patient

  • For a dynamic link of scope Patient, RDC passes the following parameter values from the user's session to the function:

    pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy, pSiteId, pSite, pPatientId, pPatient

See Table 11-1 for a description of each parameter.

Example 11-4 Static Patient Link

Configure a static link of scope Patient for the following URL:

https://mycompany.com/patient.jsp

When data manager JSMITH, who is viewing patient 101 of in-production study PDFREPORT at site 001, clicks on the link in the Patient Summary Report, RDC invokes the following URL:

https://mycompany.com/patient.jsp?userid=jsmith
&user_role=dm&test_prod=p&study_id=28601&study=pdfreport
&site_id=4501&site=001&patient_id=100001&patient=101

11.6 Defining a Link for CRF Help

You can configure one link for CRF Help. If you configure this link, RDC automatically adds the CRF Help icon to the toolbar in the Data Entry window.

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

Clicking the icon opens a new browser window to the link's target location and displays sponsor-defined help for the current CRF.

The link for CRF Help has a scope of CRF. The link can be static or dynamic.

To configure a link for CRF Help: 

  1. Log in to the RDC Administration application.

  2. Select Maintain, and then select Links.

  3. Insert or modify a row in the Maintain Links form to have these settings:

    • Seq# — Not relevant because you can define only one link for CRF Help.

    • Link Text — Not relevant because RDC adds the CRF Help icon to the toolbar.

    • URL — Enter the URL if you are defining a static link; enter the name of the function if you are defining a dynamic link.

    • Type — Select either Static or Dynamic. (See Section 11.2.4, "Specifying the Type of Link" for more information.)

    • Scope — Select CRF.

    • Use PT/CRF Link in Onsite — Enable this check box. You can select only one row for a CRF link.

  4. Save your changes.

  5. Create a target Web page or JavaServer page referred to by the static URL, or the dynamic return value of the function you specified.

11.6.1 Parameters for a CRF Help Link

Use scope type CRF to create a link to the CRF Help.

  • For a static link of scope CRF, RDC appends the following parameter values from the user's session to the URL:

    ?userid=userid&user_role=user_role&test_prod=test_prod
    &study_id=study_id&study=study&site_id=site_id&site=site
    &patient_id=patient_id&patient=patient&book_id=book_id
    &book=book&dci_id=dci_id&cpe_id=cpe_id&subno=subno
    &page_display_sn=
    page_display_sn&page_no=page_no

  • For a dynamic link of scope CRF, RDC passes the following parameter values from the user's session to the function:

    pHeader, pScope, pUserId, pUserRole, pTestProd, pStudyId, pStudy, pSiteId, pSite, pPatientId, pPatient, pBookId, pBook, pDciId, pCpeId, pSubNo, pPageDisplaySn, pPageNo

See Table 11-1 for a description of each parameter.

11.7 Querying Link Definitions

In the RDC Administration application, you can also navigate to Query and then select Links to access the Maintain Links form in query mode. This option lets you access and view — but not add or modify — the links that are defined for RDC.

11.8 About Storing Your Customized Web Pages

See Section 7.11, "Storing Custom Web Pages" for more information on where to place your Web pages.