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.

For more information, see:

• get_next_CRF_work_item
  
• get_next_document
  
• get_next_image
  
• get_previous_image
  
• get_next_dcf_image
  
• get_previous_dcf_image
  
• mark_workflow
  
• close_workflow
  
• getimage
  
• getImageDCF
  
• wnfi
  
• webpasskeys
  
• is_web2
  

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.