10 Customizing Oracle Files

Oracle Files supports several different types of customization. You can change the look and feel of the Oracle Files user interface, and you can define custom workflows to create particular review processes in Oracle Files.

This chapter discusses these different types of customization. Topics include:

• Branding the Oracle Files User Interface

• Using Custom Workflows in Oracle Files

Branding the Oracle Files User Interface

Some organizations have "look and feel" standards (such as the requirement to use a particular company logo or color scheme) within their respective environments. The Web interface for Oracle Files can be customized to match those standards.

System Administrators can make the following customizations to the Oracle Files Web user interface (UI):

• Oracle Files Web UI colors can be changed.

• Oracle Files Web UI fonts can be changed.

• Particular Oracle Files Web UI images (such as the Oracle Files logo) can be modified or replaced.

• The text in the title bar for the Oracle Files Web UI can be changed.

Any changes must be made on each middle-tier deployment of Oracle Files.

Important: You should make copies of edited files, as all changes will be lost when any patches or upgrades are applied to the Oracle Files software.

Colors

You can change the colors in the Oracle Files Web UI by editing an XML style sheet named custom.xss. This file is located in:

$ORACLE_HOME/j2ee/OC4J_iFS_files/applications/files/files/cabo/styles/

The colors of the Oracle Files Web UI are derived from four defined colors. To change the color scheme, replace one or more of these four colors with colors of your own choosing.

Fonts

You can change the fonts in the Oracle Files Web UI by editing an XML style sheet, called custom.xss, similar to changing Web UI colors. As part of this process, you will need to copy text from another XML style sheet named blaf.xss.

Fonts on buttons and images in the Oracle Files Web UI cannot readily be changed.

To change font characteristics in the Oracle Files Web UI:

1. Make a backup copy of custom.xss on each of your middle tiers. The custom.xss file is located in the following directory:

   $ORACLE_HOME\j2ee\OC4J_iFS_files\applications\files\files\cabo\styles
   
   

2. Open blaf.xss, located in the following directory:

   $ORACLE_HOME\j2ee\OC4J_iFS_files\applications\files\files\cabo\styles\
   
   

3. Copy the following entries from blaf.xss:

   <!-- The default font family -->
   <style name="DefaultFontFamily">
   <property name="font-family">Arial,Helvetica,Geneva,sans-serif</property>
   </style>
   
   <!-- The default font -->
   <style name="DefaultFont">
   <includeStyle name="DefaultFontFamily"/>
   <property name="font-size">10pt</property>
   </style>
   
   

   Be careful not to edit this file.

4. Open custom.xss and paste in the text from step 3.

5. Modify the two entries as you choose. For example, you could change the entries to the following:

   <!-- The default font family -->
   <style name="DefaultFontFamily">
   <property name="font-family">
   Times New Roman,Arial,sans-serif
   </property>
   </style>
   
   <!-- The default font -->
   <style name="DefaultFont">
   <includeStyle 
   name="DefaultFontFamily"/>
   <property name="font-size">
   9pt
   </property>
   </style>
   
   

6. Save your changes to custom.xss on each of your middle tiers.

Images

You can change particular images/logos in the Oracle Files Web UI by replacing the source images on all Oracle Files middle-tier computers. Oracle Files images are located in the following directory:

$ORACLE_HOME/j2ee/OC4J_iFS_files/applications/files/files/static/files

Any new image can be used in place of an original image/logo in the Web UI, as long as the new image is the same height and width as the original.

Title Bar

You can customize the text that appears in the title bar of the Oracle Files Web UI. Any new text for the title bar cannot be localized.

To alter the title bar text, follow these steps:

1. Edit the FilespageLayout.uit file, located in the following directory:

   $ORACLE_HOME/j2ee/OC4J_iFS_files/applications/files/files/WEB-INF/uixsrc/files/
   template/pagelayout/
   
   

2. Look for the following lines:

   <boundAttribute name = "htmlTitle">
    <concat>
     <dataObject select = "ORACLE_FILES_ONLINE" source = "files:strings"/>
     <fixed text = " - "/>
     <if>
      <dataObject select="isTrain" source="ui:rootAttr"/>
      <messageFormat data:format="title@ui:rootAttr">
       <dataObject select="stageText">
        <ifsui:dataObjectListIndex data:index="selectedTrainStep@ui:rootAttr"
                                     data:value="trainSteps@ui:rootAttr"/>
       </dataObject>
      </messageFormat>
      <dataObject select = "title" source = "ui:rootAttr"/>
     </if>
    </concat>
   </boundAttribute>
   
   

3. Replace:

   <dataObject select = "ORACLE_FILES_ONLINE" source = "files:strings"/>
   
   

   with the following line:

   <fixed text ="your_company_name"/>
   

Limitations on Oracle Files Customizations

The following areas in Oracle Files cannot be customized in Oracle Collaboration Suite, Release 2:

• With the exception of the branding image (logo) and title bar, all other instances of the Oracle Files brand name in the application cannot be modified.

• There is no customized user sign-up in Oracle Files, since the application depends upon Oracle Internet Directory for user information.

• System Administrators can only edit the content on the following pages within the application:

  • Welcome page

  • Help pages

  • FAQ

Using Custom Workflows in Oracle Files

Oracle Files comes with a default workflow process (also called "review process" in the Oracle Files online help). Although you cannot customize this default process, you can define your own custom workflow process in Oracle Workflow, then register it with Oracle Files.

A workflow designer, a person with the necessary skills to design a workflow process in Oracle Workflow Builder, creates the custom workflow process, then the Site Administrator registers the custom workflow process with Oracle Files.

Refer to Chapter 3, "Defining a Workflow Process" in the Oracle Workflow Guide for detailed information about creating a custom workflow process definition. You can access the Oracle Workflow Guide at the following URL:

http://otn.oracle.com/pls/db92/db92.docindex?remark=homepage#index-WOR

Oracle Files must be configured for Oracle Workflow before you can use workflow processes in Oracle Files. For more information, see the Oracle Collaboration Suite Installation and Configuration Guide.

About Custom Workflows

Creating and registering a custom workflow involves the following four steps:

1. Creating the Workflow Process Definition. The workflow designer creates a workflow process definition (.wft file) using Oracle Workflow Builder. The workflow designer can use the default Oracle Files workflow process (the Review Documents .wft) as an example of a correct, Oracle Files-compliant workflow process definition.

   The workflow process definition must handle the following events:

   • Launch Event

   • Cancel Event

   • Response Event

   These are the three events that are sent from Oracle Files to Oracle Workflow. Once the workflow designer has created the workflow process definition, he or she uploads the .wft to the workflow schema.

2. Creating the Launch, Response, and Cancel Events. The workflow designer creates the launch, cancel and response events.

   
   

   Note: Event names cannot be more than 30 characters in length.

   
   

3. Creating Event Subscriptions for the Launch, Response, and Cancel Events. The workflow designer creates event subscriptions for each event.

4. Registering a Custom Workflow with Oracle Files. The workflow designer asks the Site Administrator to register the custom workflow process with Oracle Files. The Start Event, Response Event, and Cancel Event must be included in the request.

Creating the Workflow Process Definition

Oracle Files and Oracle Workflow communicate with one another by sending a series of messages over Advanced Queueing (AQ). First, Oracle Files sends a Launch Event to Oracle Workflow to start the workflow process. Next, Oracle Workflow responds by sending the URL that Oracle Files needs to access the workflow process status page. After voting is complete (in other words, after the required approvers have responded), Oracle Workflow sends a status message to Oracle Files, indicating whether the status is Approved or Rejected. Finally, Oracle Files sends a Response Event to Oracle Workflow that indicates whether the workflow process concluded successfully, or failed.

If the workflow process expired or was cancelled, Oracle Files sends a Cancel Event to Oracle Workflow.

The following sections provide details on each of these messages in sequence.

The Launch Event

Oracle Files initiates a new workflow process by sending a Launch Event (message type=Start Event) to Oracle Workflow. To see an example of a Launch Event, refer to oracle.ifs.files.review, which is part of the Oracle Files default workflow process.

The Launch Event provides the following parameters:

• CORRELATIONID: The workflow process ID.

• URL[i]: The URL of the ith document being reviewed.

• NUMDOCS: The number of documents being reviewed.

• INITIATOR: The user who initiated the review process.

• JUSTIFICATION: The text justification entered by the initiator.

• APPROVERS: Users who must approve the documents, in the format of a space-delimited list of user names.

• REVIEWERS: Users who will receive notice that the workflow process has been initiated, in the format of a space-delimited list of user names.

All parameters passed to Oracle Workflow in the Launch Event must be included in all subsequent messages from Oracle Workflow to Oracle Files. For this reason, do not edit the Launch Event.

The Workflow Process URL

Oracle Workflow must respond to the Launch Event by providing Oracle Files with the URL to access the workflow process status page (message type=PROCESSURL).

Use the following workflow function to retrieve the URL:

wf_monitor.GetEnvelopeUrl(wf_core.Translate('WF_WEB_AGENT'),
                         itemtype,
                         itemkey,
                         'NO');

The PROCESSURL Event must contain the following parameters:

• CORRELATIONID: The workflow process ID.

• PROCESSURL: The URL of the workflow process status page. This URL is the one that was returned by the GetEnvelopeUrl() function.

  
  

  Note: Make sure that the PROCESSURL message includes all the parameters passed to Oracle Workflow in the Launch Event.

  
  

The Process Status Event

After voting is complete (i.e., after the required approvers have responded), Oracle Workflow must send a status message to Oracle Files, indicating whether the status is Approved or Rejected (message type=PROCESSSTATUS).

The PROCESSSTATUS Event must contain the following parameters:

• CORRELATIONID: The workflow process ID.

• PROCESSSTATUS: The status of the workflow process (Approved or Rejected).

  
  

  Note: Make sure that the PROCESSSTATUS message includes all the parameters passed to Oracle Workflow in the Launch Event.

  
  

The Response Event

The Response Event is the last message in the workflow process (message type=Response Event). Oracle Files sends the Response Event to Oracle Workflow, indicating whether the workflow process concluded successfully, or failed. To see an example of a Response Event, refer to oracle.ifs.files.response, which is part of the Oracle Files default workflow process.

The Response Event provides the following parameters:

• CORRELATIONID: The workflow process ID.

• STATUS: The final status of the workflow (Success or Failure).

• EXCEPTION: The error message that appears if STATUS=Failure.

The Cancel Event

Oracle Files sends a Cancel Event if the workflow process expired, or was cancelled, on the Oracle Files side (message type=Cancel Event). Oracle Workflow must respond to this event by canceling the corresponding workflow process. To see an example of a Cancel Event, refer to oracle.ifs.files.cancel, which is part of the Oracle Files default workflow process.

The Cancel Event provides only one parameter:

• CORRELATIONID: The workflow process ID.

Creating the Launch, Response, and Cancel Events

After the custom workflow process definition is complete, the workflow designer creates the Launch, Response, and Cancel Events in Oracle Workflow. Event names cannot be more than 30 characters in length.

Refer to Chapter 13, "Managing Business Events" in the Oracle Workflow Guide for detailed information about creating events in Oracle Workflow.

Creating Event Subscriptions for the Launch, Response, and Cancel Events

After the Launch, Response, and Cancel events have been created in Oracle Workflow, the workflow designer creates event subscriptions for each of the events:

• The Launch Event and Response Event need to be routed to the uploaded workflow process definition.

• The Cancel Event must send an abort message to the workflow process, using the wf_engine.AbortProcess() function.

Refer to Chapter 13, "Managing Business Events" in the Oracle Workflow Guide for detailed information about creating event subscriptions in Oracle Workflow.

After creating the event subscriptions, the workflow designer must ask the Site Administrator to register the custom workflow process with Oracle Files, with the Start, Response, and Cancel Event included in the request.

Registering a Custom Workflow with Oracle Files

The Site Administrator can register a custom workflow process definition on the Registered Workflow Process Definitions page in Oracle Files. Registering the custom workflow process definition will make it available to Workspace Administrators and Participants in a Subscriber.

Site Administrators can register, edit, or delete a custom workflow process definition.

Registering a Workflow Process Definition

A registered workflow process definition consists of the Workflow Process Definition Name, along with the Launch Event, Response Event, and Cancel Event strings.

To register a custom workflow process definition:

1. Click Workflow in Oracle Files.

2. On the Registered Workflow Process Definitions page, enter the Workflow Process Definition Name, along with the Launch Event, Response Event, and Cancel Event strings that the workflow designer has provided.The default Oracle Files workflow process definition is registered in the following way:

   • Launch Event: oracle.ifs.files.review

   • Cancel Event: oracle.ifs.files.cancel

   • Response Event: oracle.ifs.files.response

3. Click Apply to register the custom workflow process definition for use in Oracle Files.

   
   

   Note: To add another row, click Add Another Row.

   
   

Editing a Registered Workflow Process Definition

After you have registered a workflow process definition, you can edit its properties. These properties include the Workflow Process Definition Name, along with the Launch Event, Cancel Event, and Response Event strings.

To edit the Registered Workflow Process Definition properties:

1. Click Workflow in Oracle Files.

2. From the Registered Workflow Process Definitions page, you can edit one or more Event strings based on the workflow process definition (for Launch, Cancel, and Response Events). The workflow designer provides these strings.

   You can also change the Workflow Process Definition Name.

3. Click Apply. The page refreshes, and your new workflow process definition properties are displayed.

   
   

   Note: If you cannot cancel a workflow process, then the Cancel Event registered with Oracle Files is not consistent with the Cancel Event string in the workflow process definition in Oracle Workflow. Edit the Oracle Files Cancel Event to solve the problem.

   
   

Deleting a Registered Workflow Process Definition

When a Registered Workflow Process Definition is deleted, any pending processes using that definition are canceled.

To delete a Registered Workflow Process Definition:

1. Click Workflow in Oracle Files.

2. From the Registered Workflow Process Definitions page, click the Trash icon in the Delete column that corresponds to the Registered Workflow Process Definition you want to remove.

3. Click Apply. The deleted Registered Workflow Process Definition is not displayed, and is no longer available to Subscribers.

Setting Up E-Mail Notifications in Oracle Workflow

In order to configure Oracle Workflow to send e-mail notifications, you must perform the following tasks:

• Set up UNIX Sendmail

• Set up the Oracle Workflow Notification Mailer

• Create a configuration file for the Oracle Workflow Notification Mailer

• Start the Oracle Workflow Notification Mailer

  
  

  Note: Only instructions for UNIX and Linux are currently available.

  
  

Setting Up UNIX Sendmail

If you want to use UNIX Sendmail for Oracle Workflow email notifications, you must ensure that Sendmail is configured on the operating system so that users can send e-mail to external recipients, as well as receive e-mails from them.

To determine if Sendmail is running:

1. Log on to the middle-tier host where Oracle Workflow is installed as the "workflow" user.

2. Type the following command in a UNIX shell prompt:

   ps -ef | grep sendmail
   
   

   If Sendmail is running, it returns a valid Sendmail process.

To start Sendmail if it is not running:

1. Type the following command to start Sendmail:

   /usr/sbin/sendmail -bd -q15m
   
   

   The location of the Sendmail binary can vary depending on your operating system configuration.

To test if Sendmail is configured correctly:

1. Type the following commands:

   telnet localhost 25
   helo localhost
   mail from : <>
   
   

   You must get a response of "Sender OK."

2. Next, type the following:

   rcpt to : <email_address_of_recipient>
   
   

   You must get a response of "Recipient OK."

3. Next, type the following:

   data
   subject : xxx
   yyy
   zzz
   .
   quit
   

   
   

   Note: You must type a period to mark the end of the e-mail body.

   
   

4. Check whether the recipient receives the e-mail. If the recipient receives the e-mail, then Sendmail is configured correctly.

Setting Up the Oracle Workflow Notification Mailer

Set up the Oracle Workflow Notification Mailer on the middle-tier host where Oracle Workflow is installed.

1. Create a UNIX account for Oracle Workflow (for example, "Workflow"). This UNIX account should only receive Workflow mail.

2. Ensure that the environment for the Workflow UNIX user to run the Notification Mailer is set up in the same way as the environment for the user who installed Oracle Workflow.

3. Add the Workflow UNIX user to the dba group in the operating system, and set the umask for the account as 022.

4. Set PATH to sendmail binary.

5. Set LD_LIBRARY_PATH to $ORACLE_HOME/lib (if not already set).

6. Check that the Workflow UNIX user can log in to the server, and ensure that e-mail can be sent to and received from external recipients through Sendmail.

7. Ensure that the Workflow UNIX user can log in to the Oracle database server. You can check this by using SQL*Plus to log in to the database as the Workflow database user:

   sqlplus workflow_schema/password@connect_string
   
   

   The workflow_schema is typically owf_mgr.

8. Ensure that the Workflow UNIX user has the necessary permissions for the following three files:

   • The Notification Mailer program. The program file, wfmail.snd, is located in $ORACLE_HOME/bin.

   • The Notification Mailer tag file. The tag file, wfmail.tag, is located in $ORACLE_HOME/wf/res.

   • The sample configuration file. The configuration file, wfmail.cfg, is located in $ORACLE_HOME/wf/res.

Creating a Configuration File for the Oracle Workflow Notification Mailer

You must create a configuration file for the Oracle Workflow Notification Mailer. Edit the sample configuration file, wfmail.cfg, located in $ORACLE_HOME/wf/res.

The content of the configuration file is formatted as follows:

#Description
PARAMETR1=value_1

#Description
PARAMETR2=value_2

Edit the following parameters in the wfmail.cfg file:

• CONNECT. Connection information for the database account where Oracle Workflow server is installed, in the following format:

  user_name/password@connect_string
  
  

• ACCOUNT. Connection information for the mail account that the program uses to send notification messages. For Sendmail, the account information would be the full path of the mail spool file where the incoming messages are stored, such as:

  /var/mail/Workflow_UNIX_user_account
  
  

  For example:

  /var/mail/Workflow
  
  

• REPLYTO. A default reply-to e-mail address, if the e-mail account that processes responses is different from the e-mail account that sends outgoing notifications. For example:

  some_admin@yourDomainName
  
  

• HTMLAGENT. The base URL that identifies the HTML Web Agent that handles HTML notification responses. This URL is required to support e-mail notifications with HTML attachments. The format is:

  http://server_name:portID/pls/new_workflowDAD
  
  

  For example:

  http://myserver:8799/pls/ocs_wf
  
  

• TAGFILE. The full path and name of the Oracle Workflow tag file:

  ORACLE_HOME/wf/res/wfmail.tag
  
  

  Replace ORACLE_HOME with the actual Oracle home directory. Do not type $ORACLE_HOME.

• HTML_MAIL_TEMPLATE. The Workflow approval and rejection mail template.

  If you are using Sendmail, do not set this parameter. If you want to use a mail transfer agent other than Sendmail (for example, the Oracle Collaboration Suite mail transfer agent), make sure to set this parameter as follows:

  OPEN_MAIL_OUTLOOK
  
  

All other parameters take the default values.

Starting the Oracle Workflow Notification Mailer

After you have set up the Oracle Workflow Notification Mailer and created a configuration file, you should run the Notification Mailer in the background. Follow these instructions to keep the Notification Mailer running even after the Workflow UNIX account has logged out, and to record standard output and error messages separately:

• As the Workflow UNIX user, enter the following single line:

  nohup $ORACLE_HOME/bin/wfmail.snd –f $ORACLE_HOME/wf/res/wfmail.cfg 
  1>mailer.log 2>mailer_err.log &
  
  

• Since the password parameter in the $ORACLE_HOME/wf/res/wfmail.cfg file is in Cleartext and poses a security problem, you can start the Notification Mailer without specifying the CONNECT parameter in the configuration file:

  nohup $ORACLE_HOME/bin/wfmail.snd –f $ORACLE_HOME/wf/res/wfmail.cfg owf_mgr/password@connect_string 1>mailer.log 2>mailer_err.log &
  

  
  

  Note: Even this method of running the Oracle Workflow Notification Mailer is not entirely secure, since anyone with access to the middle tier could type /usr/ucb/ps –auxwww | grep wfmail.snd to get the CONNECT information.