2 Managing Conversions

Inbound Refinery offers a variety of conversion options depending on what components are installed and enabled on Content Server and Inbound Refinery. At minimum, the following components must be installed and enabled for basic conversion:

Component Name	Component Description	Enabled on Server
InboundRefinery	Enables Inbound Refinery	Inbound Refinery Server
InboundRefinerySupport	Enables the content server to work with Inbound Refinery	Content Server

This section covers the following topics:

• Section 2.1, "Configuring Content Server and Refinery Communication"

• Section 2.2, "Configuring Content Servers to Send Jobs to Refineries"

• Section 2.3, "Configuring Refinery Conversion Settings"

• Section 2.4, "Monitoring Refinery Status"

• Section 2.5, "Performing Refinery Administration"

2.1 Configuring Content Server and Refinery Communication

This section covers the following topics:

• "Content Server and Refinery Configuration Scenarios"

• "Configuring Refinery Providers"

• "Editing the Refinery IP Security Filter"

• "Setting Classpath to OpenOffice Class Files"

2.1.1 Content Server and Refinery Configuration Scenarios

Inbound Refinery can be used to refine content managed by Content Server. Inbound Refinery can be installed on the same computer as Content Server or on one or more separate computers. You must add the refinery as a provider to content servers on the same or separate computers after installation. For details, see "Configuring Refinery Providers".

Note:

Oracle Inbound Refinery does not support running in a cluster environment. Inbound Refinery can do conversion work for an Oracle Content Server cluster, but cannot run in a cluster environment itself. To ensure that Inbound Refinery functions properly, Inbound Refinery creates and maintains a long-term lock on the /queue/conversion directory. If mistakenly configured as part of a cluster and a second Inbound Refinery attempts to start and lock the same directory, the second Inbound Refinery will fail to start, and the attempt is logged.

Various configurations are possible, so keep the following general rules in mind as you set up your refinery environment:

• If you intend to process a large number of content items per day, do not run Inbound Refinery on the same computer as Content Server.

• The more dedicated refinery systems you have, the faster your content will be processed. Having more refinery systems than content server instances provides optimal speed. Having fewer refinery systems than content server instances can slow down performance if you need to convert large numbers of files.

• Typically, there is no reason to have multiple refineries on the same computer. One refinery can serve as a provider to multiple content servers. Having multiple refineries on one system usually does nothing to improve performance, because the refineries share the system's resources. This includes third-party applications used during conversion. To improve performance, you generally need to use separate computers for each refinery.

• Some file types and/or large files are processed considerably slower than average. If you have a lot of these files types to process in addition to other file types, consider setting up a refinery on a separate system to process just these file types. This requires more than one refinery system, but it does provide optimum refining speed and performance.

The following scenarios are common. Other refinery configurations are possible in addition to the ones described in this section. Specific content management applications might require their own particular refinery setup, which does not necessarily match any scenario mentioned in this section.

• Scenario A: One content server and one refinery on the same computer

• Scenario B: Multiple content servers and one refinery on the same computer

• Scenario C: Multiple content servers and one refinery on separate computers

• Scenario D: One refinery per content server on separate computers

• Scenario E: Multiple refineries per content server on separate computers

Each of these scenarios is explained in more detail in the following sections, including the benefits of each scenario and considerations to take into account for each scenario. In the scenario images, the following symbols are used to represent a computer, the Content Server, and the Inbound Refinery:

• Large Circle: computer

• Small Circle: Inbound Refinery

• Small Square: Content Server

2.1.1.1 Scenario A

This is the most basic scenario possible. It comprises one content server and one refinery on the same computer.

2.1.1.1.1 Benefits

• Least expensive and easiest to configure.

• Only one copy of third-party applications required for refinery conversions must be purchased.

2.1.1.1.2 Considerations

• Number and speed of conversions is limited.

• Not as powerful as scenarios where refineries are not deployed on the content server computer, because refinery processing on the content server computer can slow searches and access to the web site, and vice versa. Each conversion can take between seconds and minutes, depending on the file type and size.

2.1.1.2 Scenario B

This scenario comprises multiple content servers and one refinery on the same computer.

2.1.1.2.1 Benefits

• Only one copy of third-party applications required for refinery conversions must be purchased.

2.1.1.2.2 Considerations

• Number and speed of conversions is limited.

• Not as powerful as scenarios where refineries are not deployed on the content server computer, because refinery processing on the content server computer can slow searches and access to the web site, and vice versa. Each conversion can take between seconds and minutes, depending on the file type and size.

• In this configuration, typically the following choices should be made when deploying the refinery:

  • The refinery is set as a provider to one of the content servers. After deployment, the refinery will need to be added as a provider to the other content servers. For details, see "Configuring Refinery Providers".

2.1.1.3 Scenario C

This scenario comprises multiple content servers and one refinery on separate computers.

2.1.1.3.1 Benefits

• Only one copy of third-party applications required for refinery conversions must be purchased.

• Faster processing than when the refinery is deployed on the same computer as a content server.

• Refinery processing does not affect content server searches and access to the web site, and vice versa.

2.1.1.3.2 Considerations

• Not as powerful as scenarios where there is at least one refinery per content server.

• In this configuration, typically the following choices should be made when deploying the refinery:

  • The refinery will need to be added as a provider to each content server. For details, see "Configuring Refinery Providers".

2.1.1.4 Scenario D

This scenario comprises one refinery per content server on separate computers.

2.1.1.4.1 Benefits

• Faster processing for high volumes of content and big file sizes.

• Refinery processing does not affect content server searches and access to the web site, and vice versa.

2.1.1.4.2 Considerations

• Each refinery computer needs a copy of all third-party applications required for conversion.

• Each refinery will need to be added as a provider to each content server. For details, see "Configuring Refinery Providers".

2.1.1.5 Scenario E

This scenario comprises multiple refineries per content server on separate computers.

2.1.1.5.1 Benefits

• Fastest processing for high volumes of content and big file sizes.

• Refinery processing does not affect content server searches and access to the web site, and vice versa.

2.1.1.5.2 Considerations

• Each refinery computer needs a copy of all third-party applications required for conversion.

• In this configuration, typically the following choices should be made when deploying the refineries:

  • Each refinery will need to be added as a provider to each content server. For details, see "Configuring Refinery Providers".

2.1.2 Configuring Refinery Providers

This section covers the following topics:

• "About Content Server and Refinery Providers"

• "Adding Refinery Providers"

• "Editing Refinery Providers"

• "Disabling/Enabling Refinery Providers"

• "Deleting Refinery Providers"

2.1.2.1 About Content Server and Refinery Providers

A content server communicates with a refinery via a provider. A refinery can serve as a provider for one or multiple content servers. For more information about common configurations, see "Content Server and Refinery Configuration Scenarios".

You can add the refinery as a provider to a content server on the same computer, or you can add the refinery as a provider to content servers on separate computers after deployment.

2.1.2.2 Adding Refinery Providers

To add a refinery as a provider to a content server, complete the following steps:

1. Log into the content server as an administrator.

2. Choose Administration, Providers. The Providers Page is displayed.

3. In the Create a New Provider section, click Add in the Action column for the outgoing provider type. The Add/Edit Outgoing Socket Provider Page is displayed.

4. Complete the following fields:

   • Provider Name (required): a name for the refinery provider.

   • Provider Description (required): a user-friendly description for the provider.

   • Provider Class (required): the name of the Java class for the provider. The default is the intradoc.provider.SocketOutgoingProvider class.

   • Connection Class: not required.

   • Configuration Class: not required.

   • Server Host Name (required): The host name of the server on which the refinery is installed.

   • HTTP Server Address: The HTTP server address for the refinery. Not required when the refinery is on the same computer as the content server.

   • Server Port (required): The port on which the refinery provider will communicate. This entry must match the server socket port configured on the post installation configuration page during deployment of Inbound Refinery. For information on post configuration see the Oracle Fusion Middleware Installation Guide for Oracle Enterprise Content Management Suite. The default refinery port is 5555.

   • Instance Name (required): the instance name of the refinery. For example, ref2.

   • Relative Web Root (required): the relative web root of the refinery is /ibr/.

5. Enable the Use Connection Password check box if the refinery you are connecting to imposes authentication for the content server (the content server will share the refinery's user base). If enabled, you must specify a user name and password to be used and have the ProxyConnections component installed and configured on the refinery.

6. Select the Handles Inbound Refinery Conversion Jobs check box. This is required.

7. Clear the Inbound Refinery Read Only Mode check box. Select this check box only when you do not want the content server to send new conversion jobs to the refinery.

8. If necessary, change the maximum number of jobs allowed in the content server's pre-converted queue. The default is 1000 jobs.

9. Click Add. The Providers Page is displayed, with the new refinery provider added to the Providers table.

10. Restart the content server.

2.1.2.3 Editing Refinery Providers

To edit information for an existing refinery provider, complete the following steps:

1. Log into the content server as an administrator.

2. Choose Administration, Providers. The Providers Page is displayed.

3. In the Providers table, click Info in the Action column for the refinery provider to edit. The Provider Information Page is displayed.

4. Click Edit. The Add/Edit Outgoing Socket Provider Page is displayed.

5. Make the required changes.

6. Click Update to save the changes and return to the Providers Page.

7. Restart the content server.

2.1.2.4 Disabling/Enabling Refinery Providers

To disable or enable an existing refinery provider, complete the following steps:

1. Log into the content server as an administrator.

2. Choose Administration, Providers. The Providers Page is displayed.

3. In the Providers table, click Info in the Action column for the refinery provider to disable or enable. The Provider Information Page is displayed.

4. Click Disable or Enable.

5. Restart the content server.

2.1.2.5 Deleting Refinery Providers

To delete an existing refinery provider, complete the following steps:

1. Log into the content server as an administrator.

2. Choose Administration, Providers. The Providers Page is displayed.

3. In the Providers table, click Info in the Action column for the refinery provider to delete. The Provider Information Page is displayed.

4. Click Delete. A confirmation message is displayed.

5. Click OK.

2.1.3 Editing the Refinery IP Security Filter

An IP security filter is used to restrict access to a refinery. Only hosts with IP or IPv6 addresses matching the specified criteria are granted access. By default, the IP security filter is 127.0.0.1|0:0:0:0:0:0:0:1, which means the Inbound Refinery will only listen to communication from localhost. To ensure that a content server can communicate with all of its refineries, the IP or IPv6 address of each content server computer should be added to the refinery's IP security filter. This is true even if the refinery is running on the same computer as the content server. To edit an IP security filter for a refinery, complete the following steps:

1. Access the refinery computer.

2. Start the System Properties application:

   • Windows: choose Start, Programs, Oracle Content Server/Inbound Refinery, <instance_name>, Utilities, System Properties

   • UNIX: run the SystemProperties script, which is located in the /bin subdirectory of the refinery installation directory

3. Select the Server tab.

4. Make sure the IP Address Filter field includes the IP or IPv6 address of each content server computer (even if this is the same physical computer that is also running the refinery server). The default value of this field is 127.0.0.1|0:0:0:0:0:0:0:1 (localhost), but you can add any number of valid IP or IPv6 addresses. You can specify multiple IP addresses separated by the pipe symbol (|), and you can use wildcards (* for zero or many characters, and ? for single characters). For example:

   127.0.0.1|0:0:0:0:0:0:0:1|10.10.1.10|62.43.163.*|62.43.161.12?
   

   Important:

   Make sure you always include the localhost IP address (127.0.0.1).

5. Click OK when you are done, and restart the refinery server.

   Tip:

   Alternately, you can add IP addresses to the IP security filter directly in the config.cfg file located in the IntradocDir/config directory. Add the IP or IPv6 address to the SocketHostAddressSecurityFilter variable. For example: SocketHostAddressSecurityFilter=127.0.0.1|0:0:0:0:0:0:0:1|10.10.1.10|62.43.163.*

2.1.4 Setting Classpath to OpenOffice Class Files

If converting documents using OpenOffice, Oracle Inbound Refinery requires class files distributed with OpenOffice. You must set the path to the OpenOffice class files in the refinery intradoc.cfg file, located in the DomainHome/ucm/ibr/bin directory. To set the path in the intradoc.cfg file, do the following:

1. Navigate to the DomainHome/ucm/ibr/bin directory and open the intradoc.cfg file in a standard text editor.

2. At the end of the file, enter the following:

   JAVA_CLASSPATH_openoffice_jars=<OfficePath>/Basis/program/classes/unoil.jar:<OfficePath>/URE/java/ridl.jar:<OfficePath>/URE/java/jurt.jar:<OfficePath>/URE/java/juh.jar
   

3. Save and close the intradoc.cfg file.

4. Restart the refinery.

2.1.5 Setting Library Path for UNIX Platform

Oracle Content Server and Oracle Inbound Refinery use Outside In Technology. Ouside In Technology is dynamically linked with the GCC libraries (libgcc_s and libstdc++) on all Linux platforms as well as both Solaris platforms and HPUX ia64. Oracle Content Server must be able to access these libraries, however Solaris and HPUX do not initially make these libraries available. If running Content Server or Inbound Refinery on either Solaris or HPUX, you need to obtain and install the GCC libraries and configure Content Server to find them. For information about configuring the library paths, see Oracle Fusion Middleware Installation Guide for Oracle Enterprise Content Management Suite.

2.2 Configuring Content Servers to Send Jobs to Refineries

This section covers the following topics:

• "Overview"

• "About Conversions"

• "Passing Content Items Through the Refinery and Failed Conversions"

• "About MIME Types"

• "Using the File Formats Wizard"

• "Using the Configuration Manager"

• "Launching Configuration Manager"

• "Adding File Formats"

• "Editing File Formats"

• "Adding File Extensions"

• "Editing File Extensions"

• "Configuring the Content Server for PassThru Files"

• "Configuring the Content Server Refinery Conversion Options"

• "Overriding Conversions at Check-In"

• "Changing the Size of Thumbnails"

• "Refinery Conversion Job Status Page"

• "IBR Provider Status Page"

2.2.1 Overview

File extensions, file formats, and conversions are used in Content Server to define how content items should be processed by Inbound Refinery and its conversion add-ons. In addition, application developers can create custom conversions.

File formats are generally identified by their Multipurpose Internet Mail Extension (MIME) type, and each file format is linked to a specific conversion. Each file extension is mapped to a specific file format. Therefore, based on a checked-in file's extension, the content server can control if and how the file is processed by refineries. The conversion settings of the refineries specify which conversions the refineries accept and control the output of the conversions.

Consider the following example: the doc file extension is mapped to the file format application/msword, which is linked to the conversion Word. This means that the content server will attempt to send all Microsoft Word files (with the doc file extension) checked into the content server to a refinery for conversion. As another example, if the xls file extension is mapped to the file format application/vnd.ms-excel, which is linked to the conversion PassThru, Microsoft Excel files are not sent to a refinery. Instead, the content server can be configured to place either a copy of the native file or an HCST file that points to the native vault file in the /weblayout directory. This means that users must have an application capable of opening the native file installed on their computer to view the file.

Figure 2-1 Mapping File Formats to a Conversion

When a file is checked into the content server and its file format is mapped to a conversion, the content server will check to see if it has any refinery providers that accept that conversion and are available to take a conversion job. This means that:

• Refinery providers must be set up for the content server. For details, see "Configuring Refinery Providers".

• The refinery(s) need to be configured to accept the conversion. For details, see "Setting Accepted Conversions".

2.2.2 About Conversions

Conversions specify how a file format should be processed, including the conversion steps that should be completed and the conversion engine that should be used. Conversions can be linked to a file format using either the File Formats Wizard Page or the File Formats Screen. For details, see "Using the File Formats Wizard" and "Using the Configuration Manager".

Conversions available in the content server should match those available in the refinery. When a file format is mapped to a conversion in the content server, files of that format will be sent for conversion upon checkin. One or more refineries must be set up to accept that conversion. For details, see "Setting Accepted Conversions".

The following default conversions are available. Additional conversions might be available when conversion add-ons are installed. For more information, see the documentation for each specific conversion add-on.

Conversion	Description
PassThru	Used to prevent files from being converted. When this conversion is linked to a file format, all file extensions mapped to that file format are not sent for conversion. The content server can be configured to place either a copy of the native file or an HCST file that points to the native vault file in the /weblayout directory. For details, see "Configuring the Content Server for PassThru Files".
Word	Used to send Microsoft Word, Microsoft Write, and rich text format (RTF) files for conversion. The files will be converted according to the conversion settings for the refinery.
Excel	Used to send Microsoft Excel files for conversion. The files will be converted according to the conversion settings for the refinery.
PowerPoint	Used to send Microsoft PowerPoint files for conversion. The files will be converted according to the conversion settings for the refinery.
MSProject	Used to send Microsoft Project files for conversion. The files will be converted according to the conversion settings for the refinery.
Distiller	Used to send PostScript files for conversion. The files will be converted to PDF using the specified PostScript distiller engine.
MSPub	Used to send Microsoft Publisher files for conversion. The files will be converted according to the conversion settings for the refinery.
FrameMaker	Used to send Adobe FrameMaker files for conversion. The files will be converted according to the conversion settings for the refinery.
Visio	Used to send Microsoft Visio files for conversion. The files will be converted according to the conversion settings for the refinery.
WordPerfect	Used to send Corel WordPerfect files for conversion. The files will be converted according to the conversion settings for the refinery.
PhotoShop	Used to send Adobe Photoshop files for conversion. The files will be converted according to the conversion settings for the refinery.
InDesign	Used to send Adobe InDesign, Adobe PageMaker, and QuarkXPress files for conversion. The files will be converted according to the conversion settings for the refinery.
MSSnapshot	Used to send Microsoft Snapshot files for conversion. The files will be converted according to the conversion settings for the refinery.
PDF Refinement	Used to send checked-in PDF files for refinement. Depending on the conversion settings for the refinery, this includes optimizing the PDF files for fast web viewing using the specified PostScript distiller engine.
Ichitaro	The Ichitaro conversion is not supported for this version of Inbound Refinery.
OpenOffice	Used to send OpenOffice and StarOffice files for conversion. The files will be converted according to the conversion settings for the refinery.
ImageThumbnail	Used to send select graphics formats for creation of simple thumbnails only. This is useful if Digital Asset Manager is not installed but thumbnail images of graphics formats are wanted. The returned web-viewable files are a copy of the native file and optionally a thumbnail image. When Digital Asset Manager is installed, it can be used instead of the ImageThumbnail conversion to send graphics formats for conversion, including the creation of image renditions and thumbnails.
NativeThumbnail	Used to send select file formats for creation of thumbnails from the native format rather than from an intermediate PDF conversion. Typically, this conversion is used to create thumbnails of text files (TXT), Microsoft Outlook e-mail files (EML and MSG), and Office documents without first converting to PDF. The returned web-viewable files are a copy of the native file and optionally a thumbnail rendition and/or a an XML rendition. For an XML rendition to be created, XMLConverter must be installed and XML step configured and enabled.
MultipageTiff	Used to send files for conversion directly to multi-page TIFF files using Outside In Image Export. When file formats are mapped to this conversion, the conversion settings for the refinery are ignored, and the files are sent directly to Image Export for conversion to a TIFF file.
OutsideIn Technology	Uses Outside In X to print supported formats to PostScript for conversion with WinNativeConverter on the refinery server.
Direct PDFExport	Used to send files for conversion directly to PDF using Outside In PDF Export.
FlexionXML	Used to send files for conversion using XML Converter.
SearchML	Used to send files for conversion using XML Converter
XML-XSLT Transformation	Used to send files for XSLT transformation using XML Converter. XSL transformation is used to output XML data into another format.
LegacyCustom	The LegacyCustom conversion is not supported for this version of Inbound Refinery.
Digital Media Graphics	When Digital Asset Manager is installed, this is used to send digital images for conversion into multiple image renditions using Image Manager.
Digital Media Video	When Digital Asset Manager is installed, this is used to send digital videos for conversion into multiple video or audio renditions using Video Manager.
TIFFConversion	Used to send TIFF files for conversion to a PDF format that enables indexing of text in the document.
Word HTML	Used to send Microsoft Word files for conversion to HTML using the native Microsoft Word application.
PowerPoint HTML	Used to send Microsoft PowerPoint files for conversion to HTML using the native Microsoft PowerPoint application.
Excel HTML	Used to send Microsoft Excel files for conversion to HTML using the native Microsoft Excel application.
Visio HTML	Used to send Microsoft Visio files for conversion to HTML using the native Microsoft Visio application.

2.2.3 Passing Content Items Through the Refinery and Failed Conversions

When a file format is linked to the conversion PassThru, all file extensions mapped to that file format are not converted. When a content item with a file extension mapped to PassThru is checked into the content server, the file is not sent to a refinery, and web-viewable files are not created. The content server can be configured to place either a copy of the native file or an HCST file that points to the native file in the weblayout directory. This means that the application that was used to create the file, or an application capable of opening the file, is required on each client for the user to be able to view the file. For details, see "Configuring the Content Server for PassThru Files".

If a file is sent to the refinery and the refinery notifies the content server that the conversion has failed, the content server can be configured to place a copy of the native file in the weblayout directory. In this case users must also have an application capable of opening the native file installed on their computer to view the file. For details, see "Configuring the Content Server Refinery Conversion Options".

2.2.4 About MIME Types

It is recommended that you name new file formats by the MIME (Multipurpose Internet Mail Extensions) type corresponding to the file extension (for example, the format mapped to the doc file extension would be application/msword).

When a content item is checked in to Content Server, the content item's format is assigned according to the format mapped to the file extension of the native file. If the native file is not converted, Content Server includes this format when delivering the content item to clients. Using the MIME type for the format assists the client in determining what type of data the file is, what helper applications should be used, and so on.

If the native file is converted, Inbound Refinery assigns the appropriate format to the web-viewable file (for example, if a refinery generates a PDF file, it would identify this file as application/pdf), and Content Server then includes this format when delivering the web-viewable file to clients (instead of the format specified for the native file).

Inbound Refinery includes an extensive list of file formats configured out of the box when installed. Check the listing in the Configuration Manager applet of the content server provider. New formats should only need to be added if working with rare or proprietary formats.

The are several good resources on the Internet for identifying the correct MIME type for a file format. For example:

• http://filext.com/

• http://www.webmaster-toolkit.com/mime-types.shtml

2.2.5 Using the File Formats Wizard

When the InboundRefinerySupport component has been installed and enabled and at least one Inbound Refinery provider enabled, you can access the File Formats Wizard page by selecting Refinery Administration, File Formats Wizard in the content server Administration menu. The File Formats Wizard page enables you to select types of files that should be sent to a refinery for conversion. The corresponding default file extensions, file formats, and conversions are mapped automatically.

Important:

The InboundRefinerySupport component must be installed and enabled on the content server and at least one Inbound Refinery provider enabled to make the File Formats Wizard page available. Also, conversion option components might add file types to the File Formats Wizard page.

You can also make file format configuration changes manually using the Configuration Manager applet. For details, see "Using the Configuration Manager". The File Formats Wizard page can be used to configure conversions for most common file types, however it does not replicate all of the Configuration Manager applet features.

To use the File Formats Wizard page, complete the following steps:

1. Make sure you are logged into the content server as an administrator.

2. In the navigation menu, click Administration, Refinery Administration, File Formats Wizard. The File Formats Wizard Page is displayed.

3. Select the check box for each file type to be sent to a refinery for conversion. To select or clear all check boxes, select or clear the check box in the heading row.

   Important:

   The Ichitaro conversion is not supported for this version of Inbound Refinery.

4. Click Reset if you want to revert to the last saved settings.

5. Click Update. The corresponding default file extensions, file formats, and conversions are mapped automatically for the selected file types.

2.2.6 Using the Configuration Manager

The File Formats Wizard can be used to configure default conversions for most common file types. For details, see "Using the File Formats Wizard". File extensions, file formats, and conversions can also be managed in Content Server using Configuration Manager, which is one of the Administration Applets. You should only need to use the Configuration Manager to change default conversions and set up conversions for uncommon file types.

This section covers the following topics:

• "Launching Configuration Manager"

• "Adding File Formats"

• "Editing File Formats"

• "Adding File Extensions"

• "Editing File Extensions"

2.2.6.1 Launching Configuration Manager

To launch Configuration Manager, complete the following steps:

1. Make sure you are logged into the content server as an administrator.

2. In the navigation menu, click Administration.

3. Click Admin Applets. The Administration Applets for <server name> page is displayed.

4. Click Configuration Manager. The Configuration Manager applet is started.

5. Select Options, File Formats. The File Formats Screen is displayed.

2.2.6.2 Adding File Formats

To add a file format and link it to a conversion, complete the following steps:

1. In the File Formats section, click Add. The Add New/Edit File Formats Screen is displayed.

2. In the Format field, enter the name of the file format. Any name can be used, but Oracle recommends that you use the MIME type associated with the corresponding file extension(s). For details, see "About MIME Types".

3. From the Conversion drop-down list, choose the appropriate conversion. For details, see "About Conversions".

   Important:

   The Ichitaro conversion is not supported for this version of Inbound Refinery.

4. In the Description field, enter a description for the file format.

5. Click OK to save the settings and return to the File Formats Screen.

2.2.6.3 Editing File Formats

To edit a file format, including changing the conversion to which it is linked, complete the following steps:

1. In the File Formats section, select the file format and click Edit. The Add New/Edit File Formats Screen is displayed.

2. The Format field cannot be changed.

3. From the Conversion drop-down list, choose the appropriate conversion. For details, see "About Conversions".

4. In the Description field, edit the description of the file format (if desired).

5. Click OK to save the settings and return to the File Formats Screen.

2.2.6.4 Adding File Extensions

To add a file extension and map it to a file format (and thus associate the file extension with a conversion), complete the following steps:

1. In the File Extensions section, click Add. The Add/Edit File Extensions Screen is displayed.

2. In the Extension field, enter the file extension.

3. From the Map to Format drop-down list, choose the appropriate file format from the list of defined file formats. Selecting a file format directly assigns all files with the specified extension to the specific conversion that is linked to the file format.

4. Click OK to save the settings and return to the File Formats Screen.

2.2.6.5 Editing File Extensions

To edit a file extension, including changing the file format to which it is mapped (and thus associate the file extension with a different conversion), complete the following steps:

1. In the File Extensions section, select the file extension and click Edit. The Add/Edit File Extensions Screen is displayed.

2. The Extension field cannot be changed.

3. From the Map to Format drop-down list, choose the appropriate file format from the list of defined file formats. Selecting a file format directly assigns all files with the specified extension to the specific conversion that is linked to the file format.

4. Click OK to save the settings and return to the File Formats Screen.

2.2.7 Configuring the Content Server for PassThru Files

When a file format is linked to the conversion PassThru, all file extensions mapped to that file format are not sent for conversion. By default, the content server places a copy of the native file in the weblayout directory. However, the content server can be configured to place an HCST file that points to the native vault file in the weblayout directory instead. This can be useful if you have large files that are not being converted, and you do not want to copy the large files to the weblayout directory.

Please note the following important considerations:

• The contents of the HCST file are controlled by the contents of the redirectionfile_template.htm file.

• The GET_FILE service is used to deliver the file, so no PDF highlighting or byte serving is available. This can be resolved by overriding the template and reconfiguring the web server.

• A simple template is used; the browser's Back button might not be functional and layout differences might occur. This can be resolved by overriding the template and reconfiguring the web server.

• There is no reduction in the number of files because there is still an HCST file in the weblayout directory. However, there can be disk space savings if the native vault file is large.

• This setting has no affect on files that are sent to a refinery for conversion; that is, if a file is sent to a refinery for conversion, another content server setting controls whether web-viewable files or a copy of the native file are placed in the weblayout directory, and an HCST file cannot be used. For more information, see "Configuring the Content Server Refinery Conversion Options".

To configure the content server to place an HCST file in the weblayout directory instead of a copy of the native file, complete the following steps:

1. Open the content server config.cfg file located in the IntradocDir/config/ directory in a text editor.

2. Include the IndexVaultFile variable, and set the value to true:

   IndexVaultFile=true
   

3. Save your changes to the config.cfg file.

4. Restart the content server.

2.2.8 Configuring the Content Server Refinery Conversion Options

You can configure several options that affect how a content server interacts with its refinery providers, including how the content server should handle pre and post-converted jobs. These settings are made using the Inbound Refinery Conversion Options page.

Important:

The InboundRefinerySupport component must be installed and enabled on the content server and at least one Inbound Refinery provider enabled to make the Inbound Refinery Conversion Options page available.

To configure how the content server should handle pre and post-converted jobs, complete the following steps:

1. Log into the content server as an administrator.

2. Choose Administration, Refinery Administration, Conversion Options. The Refinery Conversion Options Page is displayed.

3. Enter the number of seconds between successive transfer attempts for pre-converted jobs. The default is 10 (seconds).

4. Enter the total number of minutes allowed to transfer a single job before action is taken. The default is 30 (minutes).

5. Enter the native file compression threshold size in MB. The default threshold size is 1024 MB (1 GB). Unless the native file exceeds the threshold size, it will be compressed before the content server transfers it to a refinery. This setting enables you to avoid the overhead of compressing very large files (for example, large video files). If you do not want any native files to be compressed before transfer, set the native file compression threshold size to 0.

6. If you want the conversion to fail when the time for transferring a job expires, select the check box.

7. Determine how you want the content server to handle failed conversions. If a file is sent to a refinery and conversion fails, the content server can be configured to place a copy of the native file in the /weblayout directory ("Refinery Passthru"). To enable passthru, select the check box. To disable passthru, clear the check box.

   Please note the following important considerations:

   • When a file is sent to the refinery for conversion, an HCST file cannot be used instead of a copy of the native file. For more information on configuring how the content server handles files that are not sent to the refinery, see "Configuring the Content Server for PassThru Files".

   • This setting can also be overridden manually using the AllowPassthru variable in the config.cgf file located in the IntradocDir\config\ directory.

8. Click Reset if you want to revert to the last saved settings.

9. Click Update to save your changes.

10. Restart the content server.

For additional details about using content server and refinery settings to manage conversion queues, see "Managing Refinery Conversion Queues".

2.2.9 Overriding Conversions at Check-In

Certain file extensions might be used in multiple ways in your environment. A good example is the ZIP file extension. For example, you might be checking in:

• Multiple TIFF files compressed into a single ZIP file that you want a refinery with Tiff Converter to convert to a single PDF file with OCR.

• Multiple file types compressed into a single ZIP file that you do not want sent to a refinery for conversion (the ZIP file should be passed through in its native format).

If you are using a file extension in multiple ways, you can configure the content server to enable the user to choose how a file will be converted when they check the file into the content server. This is referred to as Allow override format on checkin. To enable this content server functionality, complete the following steps:

1. Make sure you are logged into the content server as an administrator.

2. In the navigation menu, click Administration.

3. Click Admin Server. The Admin Server page is displayed.

4. Click the button for the content server instance you want to configure. The administration page for that content server instance is displayed.

5. In the navigation menu, click General Configuration.

6. Enable the Allow override format on checkin setting.

7. Click Save.

8. Using the Configuration Manager, map the file extension to the conversion that will be used most commonly; this will be the default conversion. For details on setting up file extensions, file formats, and conversions using the Configuration Manager, see "Using the Configuration Manager". Continuing the preceding example for the ZIP file extension, you might set up the following default conversion:

   • Map the ZIP file extension to the application/x-zip-compressed file format, and the application/x-zip-compressed file format to the TIFFConversion conversion. Thus, by default it would be assumed that ZIP files contain multiple tiff files and should be sent to a refinery with Tiff Converter for conversion to PDF with OCR.

9. Using the Configuration Manager, set up the alternate file formats and conversions that you want to be available for selection by the user at check-in. Continuing the preceding example for the ZIP file extension, you might set up the following alternate conversions:

   • Map the application/zip-passthru file format to the PassThru conversion. This option could then be selected at check-in for a ZIP file containing a variety of files that should not be sent to a refinery for conversion. The ZIP file would then be passed through in its native format.

10. Restart the content server. When a user checks in a file, the user can override the default conversion by selecting any of the conversions you have set up.

Enabling users to override conversions at check-in is often used in conjunction with multiple, dedicated refineries and/or custom conversions. Continuing the preceding example for the ZIP file extension, you might have one refinery set up with Tiff Converter, which would be used to convert ZIP files containing multiple tiff files to PDF with OCR, and a second refinery set up to convert ZIP files containing Microsoft Office files to PDF.

2.2.9.1 Changing the Size of Thumbnails

By default, thumbnails are displayed as 80 x 80 pixels. If you require your thumbnails to display at a different size, complete the following steps (this updates the size of all of your thumbnails):

1. Open the config.cfg file located in the IntradocDir/config/ directory in a text editor.

2. To change the thumbnail height and width:

   • To change the thumbnail height, substitute the pixel size in the following line:

     ThumbnailHeight=xxx (where xxx is the value in pixels)

   • To change the thumbnail width, substitute the pixel size in the following line:

     ThumbnailWidth=xxx (where xxx is the value in pixels)

   Outside In Image Export performs scaling based on whichever setting is smaller (the height setting is used if the settings are equal), preserving the aspect ratio.

3. Save your changes to the config.cfg file.

4. Restart the content server.

For more information about the ThumbnailHeight and ThumbnailWidth variables, see the Oracle Fusion Middleware Idoc Script Reference Guide.

2.2.10 Refinery Conversion Job Status Page

Access this page by selecting Refinery Administration, Conversion Options in the content server Administration menu, or by clicking the Conversion Job Status tab on the IBR Provider Status Page. The Refinery Conversion Job Status page enables you to view information about jobs submitted for conversion, such as to which provider the job is submitted and where it is in the conversion process.

Important:

The InboundRefinerySupport component must be installed and enabled on the content server to enable The InboundRefinerySupport component must be installed and enabled on the content server and at least one Inbound Refinery provider enabled to make the Inbound Refinery Conversion Options page available.

Element	Description
Refresh	Updates the status of the displayed jobs.
Force Job Queue Check	Forces Content Server to deliver jobs to refinery providers. This is particularly useful if a refinery has gone down, causing any pending jobs to fail. In this situation, pending jobs are periodically resubmitted to providers for conversion. This button forces the submission.
Conversion Job ID	A unique identifier assigned by Inbound Refinery to each submitted job.
Content ID	The unique Content Server identifier of the content item submitted for conversion.
Conversion Job State	Identifies where a job is in the conversion process.
Job Submitted to Provider	Identifies the provider to which a job is submitted.
Last Action At	Lists the date and time of the last change in job state.
Actions	Links to the Content Server content information page of the content item submitted for conversion.

2.2.11 IBR Provider Status Page

Access this page by selecting Refinery Administration, IBR Provider Status in the content server Administration menu, or by clicking the IBR Provider Status tab on the Refinery Conversion Job Status Page. The IBR Provider Status page enables you to view information about all refinery providers to the content server, including availability, connection state, and number of jobs in each provider's queue.

Important:

The InboundRefinerySupport component must be installed and enabled on the content server and at least one Inbound Refinery provider enabled to make the Inbound Refinery Conversion Options page available.

Element	Description
Force Status Update	Refreshes the status of the displayed providers.
Provider	The name of each provider.
Available	Identifies whether a provider is accepting content for conversion.
Read Only	Identifies if a provider is read only, meaning that it can no longer accept jobs for conversion. It can only return conversions to Content Server.
Jobs Queued	Identifies the number of jobs each provider has waiting for conversion.
Last Message	Displays the last status message delivered by the provider.
Connection State	Identifies whether the provider is connected to the Content Server or not.
Last Activity Date	Lists the date and time of the last provider activity.
Actions	Displays the Provider Information Page, listing information regarding the specific provider.

2.3 Configuring Refinery Conversion Settings

This section covers the following topics:

• "About Conversion Settings"

• "About Thumbnails"

• "Calculating Timeouts"

• "Setting Accepted Conversions"

• "Setting Multi-Page TIFF Files as the Primary Web-Viewable Rendition"

• "Setting Up Thumbnails"

• "Configuring Rendering Options on UNIX"

• "Specifying the Font Path"

• "Configuring Third-Party Application Settings"

• "Configuring Timeout Settings for Graphics Conversions"

2.3.1 About Conversion Settings

Before configuring refinery conversion settings, you should complete the following tasks:

• Start your refinery.

• Make sure your refinery has been set up as a provider to one or multiple content servers. For details, see "Configuring Refinery Providers".

• Make sure the InboundRefinerySupport component is installed and enabled on each content server.

• Make sure each content server has been configured to send files to the refinery for conversion. For details, see "Configuring Content Servers to Send Jobs to Refineries".

Refinery conversion settings control which conversions the refinery will accept and how the refinery processes each conversion. Inbound Refinery includes Outside In Image Export, which can be used for the following.

• To create thumbnails of files. Thumbnails are small preview images of content. For details, see "About Thumbnails" and "Setting Up Thumbnails".

• To convert files to multi-page TIFF files, enabling users to view the files through standard web browsers with a TIFF viewer plugin. For details, see "Setting Multi-Page TIFF Files as the Primary Web-Viewable Rendition".

For more information about file formats that can be converted by Inbound Refinery using Outside In Image Export, see Appendix B, "File Formats Converted by Outside In Technology".

In addition, several conversion options are available for use with Inbound Refinery. When a conversion option is enabled, its conversion settings are added to the refinery.

2.3.2 About Thumbnails

Thumbnails are small preview images of content. They are used in Content Server on search results pages and typically link to the web-viewable file they represent. This means that users do not need to rely solely on text information such as the title to tell if a file is the one for which they are looking. A thumbnail provides consumers with a visual sample of a file without actually opening the file itself. This enables them to check a file before committing to downloading the larger, original file.

Inbound Refinery includes Outside In Image Export, which can be used to create thumbnails of files. Please note the following important considerations:

• For a list of file formats that can be converted to thumbnails by Outside In Image Export, see Appendix B, "File Formats Converted by Outside In Technology".

• The Outside In Image Export thumbnail engine cannot successfully create thumbnails of PDF files with Type 3 Fonts. This affects checked-in PDF files only. If a checked in PDF file contains Type 3 Fonts, the Outside In Image Export thumbnail engine will create a thumbnail with a blank page.

• Thumbnail files are stored as JPEG, GIF, or PNG files in content server's the weblayout directory. They can be recognized by the characters @t in their filenames. For example, the file Report2001@t~2.jpg is the thumbnail that belongs to Report2001~2.pdf (which is revision 2 of a file called Report2001.xxx).

• Thumbnails cannot be processed for any files that have been encrypted or are password-protected.

• Thumbnails can be created for EML files. If you are using Internet Explorer and have installed the April, 2003, Cumulative Patch for Outlook Express, you will receive an error if you click on the thumbnail to view an EML file. As clicking on a thumbnail opens the primary web-viewable file, this only applies if the primary web-viewable file is an EML file (a multi-page TIFF or a PDF version of the EML file was not generated by the refinery as the primary web-viewable file, and the native EML file was copied to the weblayout directory as the primary web-viewable file).

• Thumbnails of EML files do not exactly match the look-and-feel of the EML file as opened in Outlook Express. This is because the thumbnail is created based on a plain-text rendition, whereas Outlook Express opens the file in its own format.

• For details about changing the size of thumbnails displayed in the content server, see "Changing the Size of Thumbnails".

• If you turn off thumbnailing in Inbound Refinery, any thumbnails that were already created will still be displayed on the content server search results pages. To prevent this from happening, you can remove THUMBNAIL from the AllowableAdditionalRenditions entry in the config.cfg file located in the IntradocDir\config\ directory.

2.3.3 Calculating Timeouts

As content is processed by a refinery, it is allotted a certain amount of processing time based on the size of the file and the settings on the Timeout Settings Page. The timeout value, in minutes, is calculated in the following manner:

timeout value [in minutes] = ([file size in bytes] x timeout factor) / 60,000

In order to determine what file to use, Inbound Refinery first looks to see if the previous step produced a file, and if so that file is used in the timeout calculations. Otherwise, the native file is used. If the previous step outputted more than one file (for example, Excel to PostScript), the sum of the file sizes is used. The content item to be processed is allotted at least the number of minutes indicated in the Minimum column, but no more minutes than indicated in the Maximum column. If the calculated timeout value is lower than the minimum value, the minimum value applies. If the calculated timeout value is larger than the maximum value, the maximum value applies.

2.3.3.1 Timeout Calculations

The following examples show how timeouts are calculated:

• Example 1

File size = 10 MB (10485760 bytes or 10240 KB)

Minimum = 2

Maximum = 10

Factor = 3

Calculated Timeout = 10485760 * 3 / 60000 = 524.288 minutes = 8.74 hours

In this case, Inbound Refinery will wait only the maximum of 10 minutes.

• Example 2

File size = 200 KB (204800 bytes)

Minimum = 2

Maximum = 30

Factor = 2

Calculated Timeout = 204800 * 2 / 60000 = 6.83 minutes

In this case, Inbound Refinery will wait only the calculated 6.83 minutes and not the Maximum of 30 minutes.

• Example 3

File size = 50 KB (51200 bytes)

Minimum = 2

Maximum = 30

Factor = 2

Calculated Timeout = 51200 * 2 / 60000 = 1.71 minutes

In this case, Inbound Refinery will wait the minimum of 2 minutes and not the calculated timeout or the Maximum of 30 minutes

2.3.4 Setting Accepted Conversions

To set the conversions that the refinery will accept and queue maximums, complete the following steps:

1. Log into the refinery.

2. Select Conversion Settings, Conversion Listing. The Conversion Listing Page is displayed.

3. Set the total number of conversion jobs that are allowed to be queued by the refinery. The default is 0 (unlimited).

4. Enter the maximum number of conversions allowed to wait for pick up by a content server before Inbound Refinery will no longer accept conversion jobs from that content server. The default is 1000.

5. Enter the number of seconds that the refinery should be considered busy when the maximum number of conversions has been reached. The default is 120 (seconds). When the maximum number of conversion jobs for the refinery has been reached, content servers will wait this amount of time before attempting to communicate with the refinery again.

6. Enter the maximum number of conversions that the refinery should process at the same time. The default is 5.

7. Select the check box for each conversion that you want the refinery to accept.

   • By default, all conversions are selected and will be accepted.

   • To select all conversions, select the Accept check box in the column heading.

   • To clear all conversions, clear the Accept check box in the column heading.

     Important:

     The Ichitaro and LegacyCustom conversions are not supported for this version of Inbound Refinery.

8. Set the maximum number of jobs (across all refinery queues) for each conversion type. The default is 0 (unlimited).

9. Click Update to save your changes.

10. Restart each content server that is an agent to the refinery to effect your changes in the content server's queuing immediately. Otherwise, the changes in refinery's accepted conversions will not be known to the content server until the next time it polls the refinery.

For additional details about using content server and refinery settings to manage conversion queues, see "Managing Refinery Conversion Queues".

2.3.5 Setting Multi-Page TIFF Files as the Primary Web-Viewable Rendition

Inbound Refinery includes Outside In Image Export, which enables you to convert files to multi-page TIFF files as the primary web-viewable rendition. This enables users to view the files through standard web browsers with a TIFF viewer plugin.

Other conversion options, such as PDF Export, enable you to create other types of renditions as the primary web-viewable rendition. When conversion options that can generate a web-viewable rendition are enabled, additional options for the options are available.

To set multi-page TIFF files as the primary web-viewable rendition that the refinery will generate, complete the following steps:

1. Log into the refinery.

2. Select Conversion Settings, Primary Web Rendition. The Primary Web-Viewable Rendition Page is displayed.

3. Select Convert to multi-page Tiff using Outside In to convert files to multipage TIFF files as the primary web-viewable rendition.

4. Click Update to save your changes.

2.3.6 Setting Up Thumbnails

Inbound Refinery includes Outside In Image Export, which enables you to create thumbnails of files as an additional rendition. Thumbnails are the only additional rendition available in Inbound Refinery by default. Other conversion options and custom conversions enable you to create additional renditions.

To enable thumbnails and configure your thumbnail settings, complete the following steps:

1. Log into the refinery.

2. Select Conversion Settings, Additional Renditions. The Additional Renditions Page is displayed.

3. Select Create Thumbnail Images using Outside In.

4. Click Update to save your changes.

5. Click Options. The Thumbnail Options Page is displayed.

6. Select your thumbnail options. For a detailed description of the available options, see "Thumbnail Options Page" on page A-24.

   Note:

   When using Inbound Refinery on a SPARC system running Solaris, or any system running Linux, by default Outside In Image Export uses its internal graphics code to render fonts and graphics. You can also choose to use the operating system's native graphics subsystem instead. For details, see "Configuring Rendering Options on UNIX".

7. Click Update to save your changes.

Please note the following considerations:

• You must configure the file formats and conversions in each content server to send files to the refinery for thumbnailing. For details, see "Configuring Content Servers to Send Jobs to Refineries".

• The refinery must be configured to accept the conversions. For details, see "Setting Accepted Conversions".

• For details about changing the size of thumbnails displayed in the content server, see "Changing the Size of Thumbnails".

• If you turn off thumbnailing in the refinery, any thumbnails that were already created will still be displayed on the content server search results pages. To prevent this from happening, you can remove THUMBNAIL from the AllowableAdditionalRenditions entry in the config.cfg file located in the IntradocDir\config\ directory.

  For example, change AllowableAdditionalRenditions=THUMBNAIL to a blank value, as in this example:

  AllowableAdditionalRenditions=
  

2.3.7 Configuring Rendering Options on UNIX

This section covers the following topics:

• "Rendering Using Internal Graphics Code"

• "Rendering Using Native Graphics Subsystem"

2.3.7.1 Rendering Using Internal Graphics Code

When running Inbound Refinery on Linux or Solaris SPARC and creating multi-page TIFF files or thumbnails, by default Outside In uses its internal graphics code to render fonts and graphics. Therefore, access to a running X Window System display server (X Server) and the presence of either Motif (Solaris) or LessTif (Linux) is not required. The system only needs to be able to locate usable fonts. Fonts are not provided with Outside In. For information about setting the path to usable fonts, see "Specifying the Font Path".

2.3.7.2 Rendering Using Native Graphics Subsystem

To configure Inbound Refinery so that Image Export uses the operating system's native graphics subsystem to render fonts and graphics instead of its internal graphics code, complete the following steps:

1. Log into the Inbound Refinery computer as the Inbound Refinery user.

2. Make sure the Inbound Refinery computer has access to a running X Window System display server (X Server) and the presence of either Motif (Solaris) or LessTif (Linux).

3. Ensure that the DISPLAY variable in the Inbound Refinery startup script (.profile, .login, .bashrc, etc.) points to the running X server. For example:

   DISPLAY=:0.0
   export DISPLAY
   

4. Source the new .profile (for example, using /usr/bin/sh, run the command:

   ..profile
   

5. Give Outside In Image Export permission to use the running X Server with the following command:

   xhost +localhost
   

6. Lock the console, leaving the Inbound Refinery user logged in.

7. Log into the refinery.

8. Select Conversion Settings then Third-Party Application Settings. The Third-Party Application Settings Page is displayed.

9. Click Options under the General OutsideIn Filter Options section.

10. Select Use native operating system's native graphics subsystem.

11. Click Update.

2.3.8 Specifying the Font Path

One either Windows or UNIX, a path to the font directory must be specified. To configure Inbound Refinery so that Outside In can locate usable fonts, complete the following steps:

1. Log into the Inbound Refinery computer as the Inbound Refinery user.

2. Under Conversion Settings, click Third-Party Applications Settings. The Third-Party Application Settings Page is displayed.

3. Click Options under the General OutsideIn Filter Options section.

4. Enter the path to the font directories to be used by Outside In in the text field. For example, on Linux:

   /usr/lib/X11/fonts/TTF
   

   or on Windows:

   C:\WINDOWS\Fonts
   

   If fonts are called for and cannot be found, Outside In will exit with an error. Only TrueType fonts (*.ttf or *.ttc files) are supported. Also note that when copying Windows fonts to a UNIX system, the font extension for the files (*.ttf or *.ttc) must be lowercase, or they will not be detected during the search for available fonts.

5. Click Update.

2.3.9 Configuring Third-Party Application Settings

The Third-Party Application Settings Page is used to configure settings for third-party applications that are used during conversions, such as OpenOffice or Microsoft Word. When conversion options that use third-party applications are installed and enabled, settings are available on this page.

2.3.10 Configuring Timeout Settings for Graphics Conversions

To configure timeout settings for graphics conversions, complete the following steps:

1. Log into the refinery.

2. Select Conversion Settings, Timeout Settings. The Timeout Settings Page is displayed.

3. Enter the Minimum (in minutes), Maximum (in minutes), and Factor for Graphics conversions. For details, see "Calculating Timeouts".

4. Click Update to save your changes.

2.4 Monitoring Refinery Status

This section covers the following topics:

Concepts

• "About Agents"

• "About Refinery Logs"

Tasks

• "Viewing Refinery Status"

• "Viewing Refinery Logs"

• "Viewing Console Output"

• "Viewing Agent Status"

• "Viewing Agent Queues"

• "Viewing Conversion History"

• "Viewing Agent Logs"

2.4.1 About Agents

An agent is an entity, such as a content server, that sends conversion jobs to the refinery. The refinery separates conversion status information and logging by agent to make it easier to view the information and find details.

2.4.2 About Refinery Logs

There are two types of log files created for the refinery:

• Refinery logs: Refinery logs contain general information about refinery functionality that is not specific to conversions performed for agents (for example, startup information). One log file is generated for each day the refinery is running.

• Refinery Agent logs: Refinery agent logs contain information specific to conversions performed for agents sending conversion jobs to the refinery. One log file is generated for each agent, each day that the agent sends at least one conversion job to the refinery.

Log entries are listed by date and time. Entries are added to the appropriate log file throughout the day as events occur. The time stamp placed on a refinery log entry designates when the log entry was created, not necessarily when the action took place.

Refinery agent log entries list the conversion number at the beginning of each entry because each agent can have multiple concurrent conversions running at a given time. For example: Log entry for conversion job '3513'. The following types of log entries are generated:

Log Entry	Description
Info	Displays status information. For example, startup information or a description of a conversion engine action.
Error	Displays errors that occur.

You can enable verbose logging. When verbose logging is on, general agent status information, a detailed description of each conversion engine action (for example, when the conversion was started and file details, conversion step details, and conversion results), and errors are recorded in the refinery agent log. When verbose logging is off, only general agent status information and errors are recorded in the refinery agent log. For details, see "Enabling Verbose Logging".

A log file might include Details links. Clicking the Details links expands and collapses log details. Typically, the log details are either a stack dump or a trace back to the code that generated the error.

2.4.3 Viewing Refinery Status

The refinery creates each agent when it sends its first conversion job to the refinery. Until then, information for the agent is not available in the refinery.

To view the current status of conversions for all refinery agents, complete the following steps:

1. Log into the refinery.

2. Click Home in the main menu, or select Status, Refinery Status from the navigation menu. The Refinery Status Page is displayed.

2.4.4 Viewing Refinery Logs

To view the refinery log files, complete the following steps:

1. Log into the refinery.

2. Click Home in the main menu and select the Refinery Logs tab, or select Status, Refinery Status from the navigation menu and select the Refinery Logs tab. The Refinery Logs Page is displayed.

3. Click a log link to display the refinery log. For more information about refinery logs, see "About Refinery Logs".

2.4.5 Viewing Console Output

To view the refinery console output, complete the following steps:

1. Log into the refinery.

2. Click Home in the main menu and select the Console Output tab, or select Status, Refinery Status from the navigation menu and select the Console Output tab. The Console Output Page is displayed.

   • Click Update to refresh the console output.

   • Click Clear to clear the console output.

2.4.6 Viewing Agent Status

To view the current status of conversions for a specific refinery agent, complete the following steps:

1. Log into the refinery.

2. Navigate to the Agent Status Page in one of the following ways:

   • Click the agent name.

   • Select Status then <agent_name> from the navigation menu.

   • Select View Detailed Status from the Actions menu for the agent on the Refinery Status Page.

   The Agent Status Page is displayed.

2.4.7 Viewing Agent Queues

To view the items that are in the pre and post-converted queues for a specific refinery agent, complete the following steps:

1. Log into the refinery.

2. Select Status, <agent_name> from the navigation menu and select the Items in Queue tab, or select View Items In Queue from the Actions menu for the agent on the Refinery Status Page. The Items In Queue Page is displayed.

3. Click Refresh to update the information on the page.

2.4.8 Viewing Conversion History

To view the last fifty conversions in the conversion history for a specific refinery agent, complete the following steps:

1. Log into the refinery.

2. Select Status, <agent_name> from the navigation menu and select the Conversion History tab, or select View Conversion History from the Actions menu for the agent on the Refinery Status Page. The Conversion History Page is displayed.

3. Click a Content ID link to display the Conversion Detail Page.

2.4.9 Viewing Agent Logs

To view the log files for a specific refinery agent, complete the following steps:

1. Log into the refinery.

2. Select Status, <agent_name> from the navigation menu and select the Agent Logs tab, or select View Agent Logs from the Actions menu for the agent on the Refinery Status Page. The Agent Logs Page is displayed.

3. Click a log link to display the refinery agent log. For more information about refinery agent logs, see "About Refinery Logs". You can enable verbose logging to record a detailed description of each conversion engine action in the refinery agent log. For details, see "Enabling Verbose Logging".

2.5 Performing Refinery Administration

This section covers the following topics:

Concepts

• "Managing Refinery Authentication and Users"

Tasks

• "Managing Refinery Conversion Queues"

• "Performing Agent Administration"

• "Viewing Refinery Configuration Information"

• "Viewing Refinery System Audit Information"

• "Managing Refinery Providers"

• "Configuring the Web Server Filter"

• "Using Admin Server"

• "Publishing Dynamic and Static Layout Files"

• "Using Administration Utilities"

• "Active Virus Scanning and Inbound Refinery"

• "Changing the Date Format"

• "Setting the Time Zone"

2.5.1 Managing Refinery Authentication and Users

As a managed server running within an Oracle WebLogic Server domain, user and group access to Inbound Refinery is controlled by Oracle WebLogic Server. As such, system security configuration is handled through the WebLogic Server console. If additional services are required, such as Oracle Internet Directory or single sign on using Oracle Access Manager, these can be linked to the Oracle WebLogic Server domain managing Inbound Refinery using WebLogic Server controls.

When deployed, the Inbound Refinery role refineryadmin has permissions to administer Oracle Inbound Refinery. Any user needing administration rights to Inbound Refinery must be part of the corresponding refineryadmin group in Oracle WebLogic Server.

For additional information, see the following documentation:

Table 2-1 Additional System Security Documentation

Task	Where to Go For More Information
Administering Oracle WebLogic Server	Oracle Application Server Administrator's Guide
Administering Universal Content Management	Oracle Fusion Middleware System Administrator's Guide for Universal Content Management

2.5.1.1 Integration with Single Sign-On

Oracle Access Manager (OAM), part of Oracle's enterprise class suite of products for identity management and security, provides a wide range of identity administration and security functions, including several single sign-on options for Fusion Middleware and custom Fusion Middleware applications. OAM is the recommended single sign-on solution for Oracle Fusion Middleware 11g installations.

For smaller scale Oracle Fusion Middleware 11g installations, where you do not have an enterprise-class single sign-on infrastructure like Oracle Access Manager, you only need to provide a single sign-on capability within your specific Fusion Middleware application, you can configure a SAML-based SSO solution. If you need to provide single sign-on with other enterprise applications, this solution is not recommended.

If your enterprise uses Microsoft desktop logins that authenticate with a Microsoft domain controller with user accounts in Active Directory, then configuring SSO with Microsoft Clients may also be an option to consider.

The setup required for each of these SSO solutions is described in the following documents/sections:

Table 2-2 Single Sign-on Documentation

For Information On...	See The Following Guide...
Configuring OAM and OSSO	Oracle Fusion Middleware Security Guide
Using Windows Native Authentication for Single Sign-on	Oracle WebLogic Server Admin Console Help: Configure Authentication and Identify Assertion Providers
Using WebLogic SAML for Single Sign-on	Oracle Fusion Middleware Securing Oracle WebLogic Server, Section 5.7: Configuring the SAML Authentication Provider

2.5.2 Managing Refinery Conversion Queues

A refinery is set up as a provider to a content server. When a file is checked into the content server, a copy of the native file is stored in the /vault directory (the native file repository). The native file is the format in which the file was originally created (for example, Microsoft Word).

If the file format is set up to be converted, the content server creates a conversion job in its pre-converted queue. The content server then attempts to deliver the conversion job to one of its active refinery providers (a refinery that is configured to accept the conversion and is not busy). The content server sends the conversion parameters to an active refinery.

When the refinery receives conversion parameters, it returns the following data to the content server:

• JobAcceptStatus: The status can be one of the following:

  Status	Description	Content Server Action
  ERROR	There was an unexpected error in processing the request.	The content item is left in GenWWW status and removed from the content server's pre-converted queue.
  NEVER_ACCEPT	The refinery is not configured to accept the conversion, and it will never accept the job.	The refinery provider is marked as unavailable until the conversion job is cleared from the pre-converted queue
  ACCEPT	The refinery will take the conversion job.	The job is removed from the pre-converted queue, transferred to the refinery, and expected to be converted.
  BUSY	The refinery could take the conversion job, but it has reached its total queue maximum or the maximum number of conversion jobs for a specific conversion.	The refinery provider is not used again until the RefineryBusyTimeSeconds it provides to the content server has elapsed.

  
  

• JobAcceptStatusMsg: A string that explains the refinery's status, to be logged by both the refinery and the content server.

• JobCanAccept: A boolean that indicates if the job was accepted.

• RefineryBusyTimeSeconds: The number of seconds the refinery wants to be left alone (note that this is just a hint; the refinery will not stop accepting requests).

If the refinery does not accept the job, the content server tries the next available refinery. The content server keeps attempting to transfer the job until a refinery accepts the job or the maximum transfer time is reached. If the maximum transfer time is reached, the job is removed from the content server's pre-converted queue and the content item remains in GenWWW status.

When a refinery accepts the job, the content server then uploads a ZIP file, containing the conversion data and the file to be converted, to the refinery. The content server also places an entry in its RefineryJobs table, which it uses to track the conversion job. The refinery places the conversion job in its pre-converted queue.

The refinery then attempts to perform the specified conversion, calling the appropriate conversion options as necessary. When the refinery finishes processing the conversion job, it places it in its post-converted queue. The content server polls the refinery periodically to see if conversion jobs in its RefineryJobs table have been completed. When the refinery reports that it has finished processing a conversion job, the content server downloads any converted files (for example, a web-viewable thumbnail file and a PDF file) from the refinery, places the conversion job in its post-converted queue, and kicks off any post-conversion functionality as needed.

Refinery queue management settings can be configured both on the content server and on the refinery. The following content server pages contain settings that enable you to manage refinery queues:

• Refinery Conversion Options Page: This page contains settings that affect how the content server interacts with all of its refinery providers.

  • Seconds between successive transfer attempts: You can set the number of seconds between successive transfer attempts for each conversion job. By default, the content server will wait 10 seconds between attempts to deliver a conversion job to one of its refinery providers.

  • Minutes allowed to transfer a single job: You can set the number of minutes allowed for the transfer of each conversion job. By default, the content server will attempt to transfer a conversion job to one of its refinery providers for 30 minutes.

  • Native file compression threshold: You can set the native file compression threshold size in MB. The default threshold size is 1024 MB (1 GB). Unless the native file exceeds the threshold size, it will be compressed before the content server transfers it to a refinery. This setting enables you to avoid the overhead of compressing very large files (for example, large video files). If you do not want any native files to be compressed before transfer, set the native file compression threshold size to 0.

  • When the time for transferring a job expires, the conversion should fail: When the maximum allowed time for transferring a conversion job is reached, the conversion job is removed from the content server's pre-converted queue and the content item remains in GenWWW status. You can specify whether or not the conversion job should fail if this occurs. If you specify that the conversion job should fail, the content item will remain in GenWWW status; however a conversion error will be displayed on the Content Information page, along with a Resubmit button. This enables the user to resubmit the content item for conversion.

  • When a conversion sent to an Inbound Refinery fails, set the conversion to 'Refinery Passthru': You can specify how you want the content server to handle failed conversions. If a file is sent to a refinery and conversion fails, the content server can be configured to place a copy of the native file in the weblayout directory by enabling refinery passthru.

    Note:

    When a file is sent to the refinery for conversion, an HCST file cannot be used instead of a copy of the native file. For more information on configuring how the content server handles files that are not sent to the refinery, see "Configuring the Content Server for PassThru Files".

• Add/Edit Outgoing Socket Provider Page: This page enables you to specify settings for an individual refinery provider.

  • Handles Inbound Refinery Conversion Jobs: You can specify if the provider handles conversion jobs. If this option is not selected, the content server will not attempt to transfer any conversion jobs to or from the provider.

  • Inbound Refinery Read Only Mode: You can use this option to prevent the content server from sending new conversion jobs to the refinery provider. However, the refinery provider will continue to return conversion jobs as the jobs are finished.

The following refinery pages contain information and settings that enable you to manage refinery queues:

• Items In Queue Page: This page enables you to view items in the pre and post-converted queues for a specific refinery agent (such as a content server).

• Conversion Listing Page: This page enables you to view items in the pre and post-converted queues for a specific refinery agent (such as a content server).

  • Maximum number of conversions allowed to be queued: You can set the total number of conversion jobs that are allowed to be queued by the refinery. The default is 0 (unlimited).

  • Maximum number of conversions in post conversion queue: You can specify the number of conversions allowed to be queued in the post conversion queue of a refinery. The default is 1000.

  • Number of seconds the refinery should be considered busy: You can specify the number of seconds that the refinery should be considered busy when the maximum number of conversions has been reached. The default is 30 (seconds). When the maximum number of conversion jobs for the refinery has been reached, content servers will wait this amount of time before attempting to communicate with the refinery again.

  • Maximum conversions: You can specify the maximum number of jobs the refinery can process at the same time. The default is 5.

2.5.3 Performing Agent Administration

This section covers the following topics:

• "Enabling Verbose Logging"

• "Deleting Agents"

2.5.3.1 Enabling Verbose Logging

You can enable verbose logging for each refinery agent. When verbose logging is on, general agent status information, a detailed description of each conversion engine action (for example, when the conversion was started and file details, conversion step details, and conversion results), and errors are recorded in the refinery agent log. When verbose logging is off, only general agent status information and errors are recorded in the refinery agent log.

To enable verbose logging for a refinery agent, complete the following steps:

1. Log into the refinery.

2. Select Refinery Administration, Agent Management. The Agent Management Page is displayed.

3. Select the Enable Verbose Logging check box for the refinery agent.

4. To revert to the last saved settings, click Reset.

5. Click Update to save your changes.

2.5.3.2 Deleting Agents

A refinery agent can be deleted only when there are no conversion jobs in the refinery agent's pre or post-converted queues. To delete a refinery agent, complete the following steps:

1. Log into the refinery.

2. Select Refinery Administration, Agent Management. The Agent Management Page is displayed.

3. Select Delete Agent from the Actions menu for the refinery agent. The Delete Agent Page is displayed.

4. Enable the Confirm deletion of agent <agent_name> check box to confirm that you want the agent deleted. Note that history, logs, and any jobs in the agent queue are also deleted.

5. Click Delete Agent.

2.5.4 Viewing Refinery Configuration Information

To view the configuration information for the refinery using the web-based Inbound Refinery interface, complete the following steps:

1. Log into the refinery.

2. Select Refinery Administration, Configuration Information from the navigation menu. The Configuration Information Page is displayed. This page provides an overview of the main system settings, including server parameters and options, installation directories, Internet properties, version information, Java properties, and content security options. In addition, it lists all installed server components or custom components that are currently enabled and disabled.

The Configuration Information page is for information purposes only. You cannot change anything on it. If you want to modify any of the settings, you need to do that elsewhere. See "Using Admin Server" and "Using the System Properties Utility" for more information.

2.5.5 Viewing Refinery System Audit Information

To view the system audit information for the refinery using the web-based Inbound Refinery interface, complete the following steps:

1. Log into the refinery.

2. Select Refinery Administration, System Audit Information from the navigation menu. The System Audit Information Page is displayed. This page displays system audit information for the refinery, which might be useful while troubleshooting a problem or tweaking a server's performance.

   The General Information section of this page provides the following information:

   • Information regarding whether the system is receiving too many requests.

   • Information about the memory cache for the system, which is useful in troubleshooting any "out of memory" errors you may receive. This is important when running the refinery server with many users and a large quantity of data.

   • Information about which Java threads are currently running. This is useful in determining the cause of an error.

   • Listing of any audit messages.

   Tracing in a refinery can be activated on a section-by-section basis. Tracing for active sections is displayed on the Console Output Page. Section tracing is useful for determining which section of the server is causing trouble, or when you want to view the details of specific sections. Sections can be added by appending extra sections to create a comma separated list.

   A listing of the sections available for tracing, with brief descriptions, is available by clicking the information icon next to the Tracing Sections Information heading. For example, activating refinery displays extended information about conversion status, activating ref-config traces changes to the current running environment, and activating refsteplogic traces the logic that determines what conversion steps are used. The wildcard character * is supported so that ref* will trace all sections that begin with the prefix ref, including refinery, ref-config, and refsteplogic.

   Some tracing sections also support verbose output. Enable Full Verbose Tracing if you wish to see in-depth tracing for any active section that supports it.

   Important:

   Any options set on this page will be lost when the refinery is restarted unless you enable Save and click Update.

2.5.6 Managing Refinery Providers

You should not need to configure any refinery providers. To view refinery provider information using the web-based Inbound Refinery interface, complete the following steps:

1. Log into the refinery.

2. Select Refinery Administration, Providers from the navigation menu. The Providers Page is displayed.

2.5.7 Configuring the Web Server Filter

To configure the web server filter for a refinery using the web-based Inbound Refinery interface, complete the following steps:

1. Log into the refinery.

2. Select Refinery Administration, Filter Administration from the navigation menu. The Configure Web Server Filter Page is displayed. This page is used to configure and troubleshoot the web server filter communication with the refinery.

2.5.8 Using Admin Server

Admin Server is an administration tool that enables you to review or edit a number of system settings, as well as manage components. Every refinery deployed has a corresponding Admin Server.

To access Admin Server, complete the following steps:

1. Log into the refinery.

2. Select Refinery Administration, Admin Server from the navigation menu. The Admin Server Page is displayed.

2.5.9 Publishing Dynamic and Static Layout Files

To publish dynamic and static layout files, complete the following steps:

1. Log into the refinery.

2. To publish your dynamic layout files, select Administration, Admin Actions, and click publish dynamic layout files under the Weblayout Publishing section. The PUBLISH_WEBLAYOUT_FILES service is executed. All dynamic refinery layout files (.css files and .js files) are published from the refinery IntradocDir/shared/config/templates directory to the weblayout directory. This service is used when customizing your refinery. The PUBLISH_WEBLAYOUT_FILES service is also executed each time your refinery is restarted.

3. To publish your static layout files, select Administration, Admin Actions, and click publish static layout files under the Weblayout Publishing section. The PUBLISH_STATIC_FILES service is executed. All static layout files (graphic files) are published from the refinery IntradocDir/shared/publish directory to the weblayout directory. This service is used when customizing your refinery. The PUBLISH_STATIC_FILES service is not executed each time your refinery is restarted, as it can be very time-consuming to execute. This service must be executed manually when customizing your refinery.

For more information about other publishing options available and for customizing the content and refinery servers, see the documentation provided with Content Server.

2.5.10 Using Administration Utilities

This section covers the following topics:

• "Using the System Properties Utility"

• "Using the Component Wizard Utility"

2.5.10.1 Using the System Properties Utility

The System Properties utility is a stand-alone application (not a Java applet) that must be run locally from the server:

• Microsoft Windows: Start, Programs, Oracle Content Server, <refinery_instance>, Utilities, System Properties.

• UNIX: Run the SystemProperties script, which is located in the bin subdirectory of the Inbound Refinery installation directory.

You can use the System Properties utility to review and edit the following application settings:

• Internet configuration settings (see important caution below!)

• Server configuration settings (for example, system locale and time zone)

• Localization settings (enabling, disabling, or editing locales)

• Paths to some important files and directories

• Install a PostScript printer and specify the distiller engine path. No PostScript printer or distiller engine is supplied with Oracle Digital Asset Management and Conversion. You must obtain and install the distiller engine and PostScript printer of your choice.

Please note the following important considerations:

• Some of the settings that you can change using System Properties are critical to proper system operation (most notably the options on the Internet tab). Use the utmost care when editing these system-critical settings. If you set them to incorrect values, the Inbound Refinery system might shut down entirely.

• Most of the options in System Properties can also be set using Admin Server.

• If you make any changes, you need to restart the refinery before they take effect.

• For more information about using the System Properties utility, see the documentation provided with Content Server.

2.5.10.2 Using the Component Wizard Utility

The Component Wizard utility is a development tool that automates the process of creating custom components. You can use Component Wizard to create new components, modify existing components, and package components for use on refineries or content servers. You can also use Component Wizard to install, uninstall, enable, and disable components on refineries or content servers.

For more information about using the Component Wizard utility and component development, see the Oracle Fusion Middleware System Administrator's Guide for Universal Content Management, Oracle Fusion Middleware Developer's Guide for Universal Content Management, and other Content Server documentation for developers.

2.5.11 Active Virus Scanning and Inbound Refinery

When running Inbound Refinery on Windows, active virus scanning of some Inbound Refinery and Content Server directories can cause conversions to fail.

Exclude the following Content Server directories from active virus scanning:

• the weblayout directory (WeblayoutDir)

• the vault directory (VaultDir)

• IntradocDir\data\

• IntradocDir\search\

  Tip:

  The vault\~temp\ directory should not be excluded, as it is the most important directory to scan.

Exclude the following Inbound Refinery directories from active virus scanning:

• the vault directory (VaultDir)

• VaultDir\temp\

• the weblayout directory (WeblayoutDir)

• IntradocDir\data\

  Tip:

  If you feel that any of these directories need to be scanned, it is recommended that you run physical disk scanning on the Content Server and Inbound Refinery computers during off-peak hours rather than actively scanning these directories. Also, for best results a local anti-virus program should be used to scan local drives.

2.5.12 Changing the Date Format

The default English-US locale uses two digits to represent the year ('yy'), where the year is interpreted to be between 1969 and 2068. In other words, 65 is considered to be 2065, not 1965. If you want years prior to 1969 to be interpreted correctly in the English-US locale, you need to change the default date format for that locale to use four digits to represent years ('yyyy').

This issue does not apply to the English-UK locale, which already uses four digits for the year.

To modify the default English-US date format, proceed as follows:

1. Start the System Properties utility:

   • Microsoft Windows: Start, Programs, Oracle Content Server, <refinery_instance>, Utilities, System Properties.

   • UNIX: Start the SystemProperties script, which is located in the /bin subdirectory of the refinery's installation directory.

2. Open the Localization tab.

3. Select the English-US entry in the list of locales, and click Edit.

   The Configure Locale dialog is displayed.

4. Modify the date format to use four digits for the year ('yyyy') rather than two ('yy').

5. After you are done editing, click OK to close the Configure Locale dialog.

6. Click OK to apply the change and exit System Properties.

7. Stop and restart the refinery (otherwise the change will not take effect).

2.5.13 Setting the Time Zone

During the installation of Inbound Refinery, you might have indicated that you wanted to use the default time zone for the selected system locale. If that is the case, the installer attempted to automatically detect the time zone of the operating system and set the refinery time zone accordingly. In certain scenarios, the time zone of the operating system might not be recognized. The time zone will then be set to the UTC time zone (Universal Time Coordinated), which is the same as Greenwich Mean Time (GMT).

You then need to set the time zone manually:

1. Start the System Properties utility:

   • Microsoft Windows: Start, Programs, Oracle Content Server, <refinery_instance>, Utilities, System Properties.

   • UNIX: Start the SystemProperties script, which is located in the /bin subdirectory of the refinery's installation directory.

2. Open the Server tab.

3. From the System Timezone drop-down list, choose the time zone you want to use for the refinery.

4. Click OK to apply the change and exit System Properties.

5. Stop and restart the refinery (otherwise the change will not take effect).