1 Custom Workflows, Menus, and Image Handling

The Oracle Clinical data entry process can be integrated with external workflow and imaging systems. Oracle Clinical communicates with the external system through a library of functions (RXCLBCLI.PLL) shipped with the product (in the admin directory on the CD-ROM) that you can customize. Also shipped with the functions is a set of menu options that you can enhance or supersede to modify the standard Oracle Clinical menus.

The Oracle Clinical functions that support integration with an external system—demonstrated here by an imaging workflow system—are on the product CD-ROM in the admin directory as a library. RXCLBCLI.PLL is the basis of the API. These integrating functions can be programmed in the library, using OLE, C, PL/SQL, or DDE. The PLL shipped with Oracle Clinical contains code that can be activated to see the simple workflow system used to test the functionality.

Also provided are five menu stubs—Custom Program Units— that can be customized for use with the external system. This is done by naming and displaying the menu items, and to writing the code to fully implement them.

Note:

The existing Oracle Clinical function Get Image, which can be invoked from Data Entry, Discrepancy Database, and from the DCF, has been moved to the PL/SQL library. This enables the integration of the external flow with Oracle Clinical's Data Entry System. This external flow need not necessarily be an imaging system.

Usage Overview

Specific functionality is determined by the customizations that are made, so the following description provides a generic view of how Oracle Clinical and the external system might interact.

Entering Data for the Workflow Option

When the workflow option is enabled (see "Enabling External Systems"), the Data Entry menu shows the workflow task; otherwise, this task is hidden. All top menu items in the Data Entry tree are considered tasks. Before the task sequence is described, two basic terms, workitem and document, need to be defined.

A workitem is a collection of DCIs, also referred to as documents. All DCIs in the workitem are for the same task and the same study, but they may be for different patients. Some examples of tasks are Initial Log-In, and Second Pass Entry.

A document is a single DCI within a workitem, and can be composed of one or more physical Case Report Forms (CRF) pages.

To begin data entry, select Get Next Workitem from the Workflow menu; queries are not permitted. Oracle Clinical presents the DCIs according to the workitem sequence definition. When you commit a document, the next document in that workitem is immediately presented. If a problem prevents you from committing that document, you must select Get Next Document from the Workflow menu. When all documents in a workitem are completed, you can start the next workitem or close the workflow.

When you are performing data entry through the workflow system the following standard Oracle Clinical data entry options are unavailable from a data entry form:

  • changing studies

  • changing tasks

  • turning DCI book on

  • entering or executing a query

The key change task is also not available for use in a workflow system.

Working from the Discrepancy Management System

Once you enter the discrepancy database from the Conduct menu options and query discrepancies, you can use the workflow monitor system to invoke the image of the page where the discrepant question appears. You can then use standard Oracle Clinical functionality to handle discrepancies. For example, you can move to data entry to correct data or change review status before creating a Data Clarification Form (DCF).

Working with DCFs

You can use the external systems in managing and resolving discrepancies returned from investigators through the standard DCF. Assuming that the DCF has been scanned and indexes for the document based on DCF-ID, patient, site, investigator, you can use the imaging workflow option for performing the discrepancy resolution. One scenario to do this is:

  1. Log in to Oracle Clinical.

  2. Select the DCF screen.

  3. Query for a DCF with the RECEIVED status.

  4. Invoke the image corresponding to the current DCF.

  5. Use standard Oracle Clinical functionality to move to the Discrepancy Database for the discrepancy entries on the DCF form.

  6. Choose to display a Data Entry form via the Special in-form menu.

  7. Invoke the corresponding CRF's image in a separate window.

Figure 1-1 CRF Entry Workflow diagram

Description of Figure 1-1 follows
Description of ''Figure 1-1 CRF Entry Workflow diagram''

Enabling External Systems

To enable an external workflow system, set the INVOKE_WORKFLOW option to Y in the OCL_STATE reference codelist. To enable an imaging system, you set the INVOKE_IMAGE option to Y in the OCL_STATE reference codelist. To enable these options:

  1. Select Admin, then Reference Codelists, and Local Codelists.

  2. Type OCL_STATE in the Name field, and execute a query.

  3. To enable an external workflow system, scroll through the values to INVOKE_WORKFLOW.

    To use an imaging system, scroll through the values to INVOKE_IMAGE.

  4. Set the value to Y.

  5. Save the data.

Menu Customization

Oracle Clinical provides functions that allow for two levels of customization. These are modifying the menus and implementing API functions.

When Oracle Clinical opens a form, it calls the wnfi procedure from the PL/SQL library. This enables you to set properties for the menu you are customizing. It can be used to update labels for the customizable options, or even to disable them. The procedure itself contains samples.

Other functions customize the Get Next and Get Previous Image options, which are workflow tasks. They allow you to proceed to the next or previous page of a multi-page document from within Oracle Clinical, when you are viewing an image of the document in conjunction with using data entry.

In rxclbcli.pll, there are five functions that are defined to allow you to add your own menu options and functionality to the Data Entry menu. The functions, are named CustomPgmUnit1 through CustomPgmUnit5.

The CustomPgmUnit# functions are provided for each custom menu option as a shell. You can add functionality into the data entry system. The return value from these functions is either a null or an error message. If the function returns an error message the value of the error_type is checked, a value of 1 causes a warning message to be displayed. If the error_type's value is 2, an error message is displayed and an error is raised from the calling form.

These functions have arguments that are used to pass data into the function or return data from the function. In the tables describing the arguments the In or Out column has an I for input argument and an O for an output argument.

In the tables the Data types column shows the defined type of data for the variable. Sometimes the data type is defined to be the same as a particular column in a database table. The format that shows this is the database table name, period, column name, followed by % type. For example received_dcis.document_number%type means the data type is defined as the same type used to define the column document_number in the received_dcis table.

CustomPgmUnit1

CustomPgmUnit1(document_number,                       nreceived_dci_id,    nError_type)
Argument In or Out Data type
document_number I received_dcis.document_number%type
received_dci_id I received_dcis.received_dci_id%type
nError_type O number

CustomPgmUnit2

CustomPgmUnit2(ndcf_id nError_type)
Argument In or Out Data type
ndcf_id I data_clarification_forms.dcf_id%type
nError_type O number

CustomPgmUnit3

CustomPgmUnit3(nError_type)
nError_type       out number
Argument In or Out Data type
nError_type O number

CustomPgmUnit4

CustomPgmUnit4(nError_type)
Argument In or Out Data type
nError_type O number

CustomPgmUnit5

CustomPgmUnit5(nError_type)
Argument In or Out Data type
nError_type O number

Some Possible Ways to Work with the API

The target file is opened depending on the application associated with it. The system prompts for an application name if one is not given.

  • Create a text file with the TEXT_IO command on a file server accessible to the client, and then use web.show_document ('file://...') to access the file. The file is opened with the application associated with the extension of the file on the client PC. When no associated application is named, the system prompts for one. An example of this file protocol method is in the Get Image procedure.

  • Create a text file on a Web server with the TEXT_IO command and access the file with web.show_document ('http://...'). The file is opened with the application associated with the extension of the MIME type that is associated with the file on the Web server. When no associated application is named, the system prompts you. The Get Image procedure has an example of this method.

    For Oracle WebDB listener, you can view, and add, MIME type extensions through the MIME TYPE option under the Listener mode.

  • Follow a similar method to the preceding one, but create the text file in the same directory as the file opabasejini.htm, specifying the name of the Web server. The file opabasejini.htm is stored in oracle_home/html. The value of oracle_home can be derived by using tool_env.getvar('oracle_home',...). Then, use web.show_document ('http://...'). The advantage of this method is that you do not have to create another virtual directory, and you do not have to specify the virtual directory in web.show_document.

  • Call a form that starts up a Java bean.

Workflow API Functions

Plan the functions you need from the following sections. Oracle Clinical calls the functions at specific execution points. Functions created by customers will be included in the forms library dedicated to user-defined program units (PL/SQL functions or procedures).

These functions execute at the client level so that communication mechanisms between Oracle Clinical and the workflow monitor are customizable. When the workflow system is invoked, on return, there is a workitem opened for the specified userid.

Arguments are used to pass data into the functions and/or return data from the functions. In the tables describing the arguments the In or Out column has an I for input argument, O for an output argument, and I/O for both an input and output argument.

In the tables the Data types column shows the defined type of data for the variable. Sometimes the data type is defined to be the same as a particular column in a database table. The format that shows this is the database table name, period, column name, followed by % type. For example oracle_accounts.oracle_account_name%type means the data type is defined as the same type used to define the column oracle_account_name in the oracle_accounts table.

The API function that you write generally return a string. A NULL string value indicates successful execution. If your function returns a string that is not NULL the Oracle code treats this as an error; the workflow stops processing, the string value is an error message and is displayed.

get_next_CRF_work_item

get_next_CRF_work_item (userid, clinical_study_id, task, work_item_id, status)
Argument In or Out Data type
userid I oracle_accounts.oracle_account_name%type
clinical_study_id I/O clinical_studies.clinical_study_id%type
task I/O varchar2
work_item_id O number
status O varchar2

This routine is called from the Special menu item of the Log-In form. The function returns a null value to indicate successful completion. Otherwise, it returns an error message.

The task returned by the function should be one of the following values:

INITIAL LOG-IN
INITIAL LOG-IN AND FIRST-PASS ENTRY
FIRST-PASS ENTRY
SECOND-PASS ENTRY
RECONCILIATION
UPDATE
BROWSE

The status code returned by the function should be SUCCESS or EOF. When the status code is EOF it indicates that there are no work items to process. A message indicating this is displayed.

Execution of this routine enables the following:

  • The workflow monitor starts if this module is not yet started. (The workflow monitor starts the image viewer, if necessary.)

  • The workflow monitor retrieves the next workitem from the workflow system for the specified user.

  • The Data Entry task (for example, PASS 1 ENTRY), the clinical_study_id, and the work_item_id are returned to Oracle Clinical. The work_item_id is stored for use by other client API routines.

  • Oracle Clinical initializes the task and sets study context, then calls the get_next_document function.

get_next_document

get_next_document (source, task, work_item_id, CRFpage, document_number, patient_number, clinical_planned_event, DCI_short_name, RDCI_date, RDCI_time, subevent_number, status)
Argument In or Out Data type
source I varchar2
task I varchar2
work_item_id I number
CRFpage O dci_book_pages.start_page_number%type
document_number O received_dcis.document_number%type
patient_number O patient_positions.patient%type
clinical_planned_event O received_dcis.clin_plan_eve_name%type
DCI_short_name O dcis.short_name
RDCI_date O received_dcis.dci_date%type
RDCI_time O received_dcis.dci_time%type
subevent_number O received_dcis.subevent_number%type
status O varchar2

The purpose of this function is to retrieve information about the next workflow work item. The function returns a null value if it succeeds and an error message if it fails.

This routine is called either automatically—after get_next_workitem or when it has completed and is going to retrieve the next document in the current workitem—or manually. It is called in the following circumstances:

  • whenever INITIAL LOG-IN, INITIAL LOG-IN AND ENTRY, PASS 1 ENTRY, PASS 2 ENTRY, UPDATE, BROWSE or COMPARISON RECONCILIATION is first invoked and a new workitem is being initialized (SOURCE=AUTO)

  • whenever the next document in the current workitem is required (SOURCE=AUTO)— that is, when a new received DCI is to be created or an existing received DCI is to be retrieved

  • whenever the get_next_document function is called from the Workflow menu (SOURCE=MANUAL)

The arguments for this function are:

  • CRF_page_number: Number of the first page in the document.

  • document_number: The unique number assigned by the workflow system for the document. The Log-In tasks fills the Oracle Clinical Document Number field with the contents of this variable. (On data entry or Browse tasks, this field is used to set the Oracle Clinical document field to retrieve the received DCI record for entry.)

  • patient_number: The Oracle Clinical patient number, entered into the workflow system as part of the indexing operation. The Log-In tasks fills the Patient field in the Oracle Clinical DCI header with the contents of this variable. It is ignored in data entry or Browse operations.

  • clinical_planned_event: The Oracle Clinical visit name, entered into the imaging system as part of the indexing operation. The Log-In tasks fills the Clinical Planned Event field in the Oracle Clinical DCI header with the contents of this variable.

  • DCI_short_name: The DCI Name. The Log-In tasks fills the DCI Name in the Oracle Clinical DCI header with the contents of this variable. It is ignored in data entry or Browse operations. If the DCI Book Name field is null on entry, the value returned is taken from the imaging record. If DCI Book Name is not null, the value is retrieved from the DCI book.

  • status: SUCCESS or EOF.

    • SUCCESS causes processing of the returned document.

    • EOF indicates there are no more documents in this workitem. Oracle Clinical function displays a message indicating that there are no more documents to process. The user then can select the menu item to get a new workitem.

When this function returns and the current task is Initial Log-in (or Initial Log-in and Entry) Oracle Clinical populates the DCI header with the returned data and waits for the operator to create the received DCI (and move to data entry if in Initial Log-In and Entry).

If this function is called from the First Pass Data Entry, Second Pass Data Entry, Update, Browse, or Comparison Reconciliation task, Oracle Clinical uses the returned document_number to query the received DCI record while waiting for the operator to move to data entry.

It is possible that the document has already been logged into Oracle Clinical in error, so that it is not possible to log in the duplicate RDCI. In such a case, the function returns an error. The operator is expected to correct the error for example, by creating a new subevent or by moving the document to a workflow error queue.

It is possible that an attempt is made to enter data (Pass 1 or Pass 2) into a document not logged into Oracle Clinical. While this should be an extremely rare occurrence, if it happens, the operator should move the document to a workflow error queue. This action is accomplished, as above, by selecting Get New Document from the Workflow menu.

get_next_image

get_next_image (document_number)
Argument In or Out Data type
document_number I received_dcis.document_number%type

This user-written routine calls the workflow monitor and displays the image of the next page of the document. It is called when the submenu item Get Next Image is selected from the Workflow menu. The function returns a null value if it succeeds and an error message if it fails.

get_previous_image

get_previous_image (document_number)
Argument In or Out Data type
document_number I received_dcis.document_number%type

This user-written routine is called when the submenu item Get Previous Image is selected from the Workflow menu. It displays the image of the previous page of the document. The function returns a null value if it succeeds and an error message if it fails.

get_next_dcf_image

get_next_dcf_image (dcf_id)
Argument In or Out Data type
dcf_id I data_clarification_forms.dcf_id%type

This routine calls the workflow monitor and displays the image of the next page of the DCF. It is called when the submenu item Get Next Image is selected from the menu in the DCF form. The function returns a null value if it succeeds and an error message if it fails.

get_previous_dcf_image

get_previous_dcf_image (dcf_id)
Argument In or Out Data type
dcf_id I data_clarification_forms.dcf_id%type

This routine is called when the submenu item Get Previous Image is selected from the menu in the DCF form. It displays the image of the previous page of the DCF. The function returns a null value if it succeeds and an error message if it fails.

mark_workflow

mark_workflow (document_number, received_dci_id, received_dci_status_code)
Argument In or Out Data type
document_number I received_dcis.document_number%type
received_dci_id I received_dcis.received_dci_id%type
received_dci_status_code I received_dcis.received_dci_status_code%type

This routine is called at the end of the commit process, which occurs whenever changes are committed to the database. The workflow monitor updates its tables with the information it receives and moves the document along in the workflow process. Information received includes visit date, status, and other information from the Oracle Clinical received DCI record.

The execution point in Oracle Clinical where this routine is called is whenever a new received DCI has been committed to the database (Initial Log-In) or when Pass 1 or Pass 2 data has actually been saved to the database after data entry.

The function returns a null value if it succeeds and an error message if it fails. In the latter case the returned error message is displayed by the calling form as a warning.

close_workflow

close_work_flow ()

This routine is called to shut down the workflow monitor and imaging systems. This function is called when Oracle Clinical is closed, or on command from the Special submenu menu item. The function returns a null value if it succeeds and an error message if it fails.

getimage

getimage (Document_number, Study_id, Study, Received_dci_id, Received_dci_id_entry_ts, Dci_id, Dci_name, Dci_clin_plan_eve_id, Dci_visit_number, Dci_clin_plan_eve_name, Dci_subevent_number, Received_dcm_id, Received_dcm_id_entry_ts, Dcm_id, Dcm_name , Dcm_clin_plan_eve_id, Dcm_visit_number, Dcm_clin_plan_eve_name, Dcm_subevent_number, Patient_position_id, Patient, Site_id , Site, Investigator_id, Investigator, User_id, User_password , Owning_location, Current_location, Env_type, CrfPageNo)
Argument In or Out Data type
Document_number I received_dcis.document_number%type
Study_id I received_dcis.clinical_study_id%type
Study I clinical_studies.study%type
Received_dci_id I received_dcis.received_dci_id%type
Received_dci_id_entry_ts I received_dcis.received_dci_entry_ts%type
Dci_id I dcis.dci_id%type
Dci_name I dcis.name%type
Dci_clin_plan_eve_id I received_dcis.clin_plan_eve_id%type
Dci_visit_number I received_dcis.visit_number%type
Dci_clin_plan_eve_name I received_dcis.clin_plan_eve_name%type
Dci_subevent_number I received_dcis.subevent_number%type
Received_dcm_id I received_dcms.received_dcm_id%type
Received_dcm_id_entry_ts I received_dcms.received_dcm_entry_ts%type
Dcm_id I received_dcms.dcm_id%type
Dcm_name I dcms.name%type
Dcm_clin_plan_eve_id I received_dcms.clin_plan_eve_id%type
Dcm_visit_number I received_dcms.visit_number%type
Dcm_clin_plan_eve_name I received_dcms.clin_plan_eve_name%type
Dcm_subevent_number I received_dcms.subevent_number%type
Patient_position_id I received_dcis.patient_position_id%type
Patient I received_dcis.patient%type
Site_id I received_dcis.site_id%type
Site I received_dcis.site%type
Investigator_id I received_dcis.investigator_id%type
Investigator I received_dcis.investigator%type
User_id I oracle_accounts.oracle_account_name%type
User_password I encrypted_passwords.password%type
Owning_location I clinical_studies.owning_location%type
Current_location I clinical_studies.owning_location%type
Env_type I varchar2
CrfPageNo I dci_book_pages.start_page_number%type

GetImage invokes the external imaging system. Oracle Clinical passes the context information for the current RDCI. It is invoked by Special Menu Item, F3 key or the getimage icon on Log-In and Discrepancy forms.

getImageDCF

GetImageDCF(dcf_id, user_id, user_password)
Argument In or Out Data type
dcf_id I data_clarification_forms.dcf_id%type
user_id I oracle_accounts.oracle_account_name%type
user_password I encrypted_passwords.password%type

GetImageDCF invokes the external imaging system from the DCF screen. Oracle Clinical passes in dcf_id, user_id and password. It is invoked by Special Menu Item, F3 key or the get_image icon on Log-In and Discrepancy forms.

wnfi

wnfi (error_type)
Argument In or Out Data type
error_type O number

This routine is used to customize menu item labels. It also can be used to enable or disable the display of menu items. This routine is called when either the Log-In form (RXCDEMLI), the Data Entry form (RXCDECDE), the Discrepancy Management form (RXCDMMDD), or the DCF form is opened. The wnfi function returns a string.

The function returns a null value if it succeeds and an error message if it fails. In the latter case the error_type is checked. If the error_type is 1, a warning message, corresponding to the returned value is displayed. If the error_type is 2, the error message is displayed and an error would be raised from the calling form.

webpasskeys

webpasskeys(URL, Document_number, Study_id, Study, Received_dci_id, Received_dci_id_entry_ts, Dci_id, Dci_name, Dci_clin_plan_eve_id, Dci_visit_number, Dci_clin_plan_eve_name, Dci_subevent_number, Received_dcm_id, Received_dcm_id_entry_ts, Dcm_id, Dcm_name ,  Dcm_clin_plan_eve_id, Dcm_visit_number, Dcm_clin_plan_eve_name, Dcm_subevent_number, Patient_position_id, Patient, Site_id , Site, Investigator_id, Investigator, User_id, User_password , Owning_location, Current_location, Env_type, CrfPageNo)
Argument In or Out Data type
URL I varchar2
Document_number I received_dcis.document_number%type
Study_id I received_dcis.clinical_study_id%type
Study I clinical_studies.study%type
Received_dci_id I received_dcis.received_dci_id%type
Received_dci_id_entry_ts I received_dcis.received_dci_entry_ts%type
Dci_id I dcis.dci_id%type
Dci_name I dcis.name%type
Dci_clin_plan_eve_id I received_dcis.clin_plan_eve_id%type
Dci_visit_number I received_dcis.visit_number%type
Dci_clin_plan_eve_name I received_dcis.clin_plan_eve_name%type
Dci_subevent_number I received_dcis.subevent_number%type
Received_dcm_id I received_dcms.received_dcm_id%type
Received_dcm_id_entry_ts I received_dcms.received_dcm_entry_ts%type
Dcm_id I received_dcms.dcm_id%type
Dcm_name I dcms.name%type
Dcm_clin_plan_eve_id I received_dcms.clin_plan_eve_id%type
Dcm_visit_number I received_dcms.visit_number%type
Dcm_clin_plan_eve_name I received_dcms.clin_plan_eve_name%type
Dcm_subevent_number I received_dcms.subevent_number%type
Patient_position_id I received_dcis.patient_position_id%type
Patient I received_dcis.patient%type
Site_id I received_dcis.site_id%type
Site I received_dcis.site%type
Investigator_id I received_dcis.investigator_id%type
Investigator I received_dcis.investigator%type
User_id I oracle_accounts.oracle_account_name%type
User_password I encrypted_passwords.password%type
Owning_location I clinical_studies.owning_location%type
Current_location I clinical_studies.owning_location%type
Env_type I varchar2
CrfPageNo I dci_book_pages.start_page_number%type

This routine is used to specify the location of the image to be displayed. Oracle Clinical passes the keys to allow the function to determine the appropriate image. The returned value is the specification string to access the image to be displayed.

An example of the use of this function is if getimage calls it to obtain the location of the image to be displayed and then displays the image.

is_web2

is_web2 ()

This function is no longer necessary. It was used to determine whether this was a Web environment or a client/server environment. It should always return TRUE.