Managing Inbound Refinery

21.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 and 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 refineryadmin Inbound Refinery role 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 21-1 Additional System Security Documentation

Task	Where to Go For More Information
Administering Oracle WebLogic Server	Administering Oracle Fusion Middleware
Administering Oracle WebCenter Content	Administering Oracle WebCenter Content

21.2 Managing Refinery Conversion Queues

A refinery is set up as a provider to a Content Server instance. 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 (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 pages are used 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: Used to set the number of seconds between successive transfer attempts for each conversion job. By default, the Content Server waits 10 seconds between attempts to deliver a conversion job to one of its refinery providers.
- Minutes allowed to transfer a single job: Used to set the number of minutes allowed for the transfer of each conversion job. By default, the Content Server attempts to transfer a conversion job to one of its refinery providers for 30 minutes.
- Native file compression threshold: Used to set the native file compression threshold size in MB (default size is 1024 MB (1 GB)). Unless the native file exceeds the threshold size, it is compressed before the Content Server transfers it to a refinery. This setting avoids the overhead of compressing very large files, such as video files. To leave native files uncompressed before transfer, set the threshold size to 0.
- When the time for transferring a job expires, the conversion should fail: Used to specify the time to failure for a conversion. 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. If specified that the conversion job should fail, the content item remains in GenWWW status. A conversion error is displayed on the Content Information page with a Resubmit button, allowing the user to resubmit the content item for conversion.
- When a conversion sent to an Inbound Refinery fails, set the conversion to 'Refinery Passthru': Used to specify how the Content Server handles 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: Used to specify settings for an individual refinery provider.
- Handles Inbound Refinery Conversion Jobs: Used to specify if the provider handles conversion jobs. If this option is not selected, the Content Server does not attempt to transfer any conversion jobs to or from the provider.
- Inbound Refinery Read Only Mode: Used to prevent the Content Server from sending new conversion jobs to the refinery provider. However, the refinery provider continues to return conversion jobs as the jobs are finished.

The following refinery pages contain information and settings used to manage refinery queues:

Items in Queue page: Used to view items in the pre and post-converted queues for a specific refinery agent (such as a Content Server).
Conversion Listing page: Used 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: Used to set the total number of conversion jobs allowed to be queued by the refinery. Default: 0 (unlimited).
- Maximum number of conversions in post conversion queue: Used to specify the number of conversions allowed to be queued in the post conversion queue of a refinery. Default: 1000.
- Number of seconds the refinery should be considered busy: Used to specify the number of seconds the refinery is considered busy when the maximum number of conversions is reached. Default: 30 (seconds). When the maximum number of conversion jobs for the refinery is reached, Content Servers 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.

21.3 Managing Refinery Agents

The following tasks are performed when managing agents:

21.3.1 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:

Log in to the refinery.
Select Refinery Administration then Agent Management.
On the Agent Management page, select the Enable Verbose Logging check box for the refinery agent.
To revert to the last saved settings, click Reset.
Click Update to save your changes.

21.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:

Log in to the refinery.
Select Refinery Administration then Agent Management.
On the Agent Management page, select Delete Agent from the Actions menu for the refinery agent.
On the Delete Agent page, select the Confirm deletion of agent agent_name check box to confirm that you want the agent deleted. History, logs, and any jobs in the agent queue are also deleted.
Click Delete Agent.

21.4 Managing Refinery Providers

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

Log in to the refinery.
From the navigation menu, choose Refinery Administration then Providers.

21.5 Viewing Refinery Information

This section discusses methods to view refinery information:

21.5.1 Viewing Refinery Configuration Information

To view the configuration information for the refinery using the web-based Inbound Refinery interface:

Log in to the refinery.
From the navigation menu, choose Refinery Administration then Configuration Information.

The Configuration Information page opens, showing an overview of the main system settings. 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 and cannot be edited.

21.5.2 Viewing Refinery System Audit Information

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

Log in to the refinery.
From the navigation menu, choose Refinery Administration then System Audit Information.
The System Audit Information page opens, showing information which may be useful while troubleshooting a problem or adjusting 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.

Note:

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

21.6 Configuring the Web Server Filter

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

Log in to the refinery.
From the navigation menu, chose Refinery Administration then Filter Administration.

The Configure Web Server Filter page opens. This page is used to configure and troubleshoot the web server filter communication with the refinery.

21.7 Publishing Dynamic and Static Layout Files

To publish dynamic and static layout files:

Log in to the refinery.
To publish your dynamic layout files, choose Administration then Admin Actions, and under the Weblayout Publishing section select publish dynamic layout files. 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 the refinery. The PUBLISH_WEBLAYOUT_FILES service is also executed each time the refinery is restarted.
To publish static layout files, choose Administration then Admin Actions, and under the Weblayout Publishing section select publish static layout files. 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 the refinery.

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

21.8 Active Virus Scanning on Windows

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 Content Server \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)
the weblayout directory (WeblayoutDir)
IntradocDir\data\

Tip:

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

21.9 Changing the Date Format and Time Zones

This section discusses changing the default date format and the default time zone setting:

21.9.1 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. For example, 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 must 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:

Start the System Properties utility:
- Microsoft Windows: Select Start then Programs then Oracle Content Server. Choose refinery_instance then Utilities then System Properties.
- UNIX: Start the SystemProperties script, which is located in the /bin subdirectory of the refinery's installation directory.
Select the Localization tab.
Select the English-US entry in the list of locales, and click Edit.
On the Configure Locale dialog, modify the date format to use four digits for the year ('yyyy') rather than two ('yy').
After you are done editing, click OK to close the Configure Locale dialog.
Click OK to apply the change and exit System Properties.
Stop and restart the refinery.

21.9.2 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:

Start the System Properties utility:
- Microsoft Windows: Select Start then Programs then Oracle Content Server. Choose refinery_instance then Utilities then System Properties.
- UNIX: Start the SystemProperties script, which is located in the /bin subdirectory of the refinery's installation directory.
Select the Server tab.
From the System Timezone list, choose the time zone you want to use for the refinery.
Click OK to apply the change and exit System Properties.
Stop and restart the refinery.

21.10 Monitoring Refinery Status

Log files are created to help monitor the refinery status. Agent are entities, such as a Content Server, that sends a job to the refinery. Conversion status information is separated and logged by agent to make it easier to view the information and find details.

Two types of log files are created for the refinery:

Refinery logs: These 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. For more information, see Viewing Refinery Status.
Refinery Agent logs: These 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. For more information, see Viewing Agent Statuses.

21.10.1 Viewing Refinery Status

Entries are added to the appropriate log file throughout the day as events occur and are listed by date and time. 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.

Verbose logging can be enabled. When on, it records 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. When verbose logging is off, only general agent status information and errors are recorded in the refinery agent log.

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.

The following sections describe how to view different types of conversion status information:

21.10.1.1 Viewing Conversion Statuses

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:

Log in to the refinery.
Choose Home from the main menu, or choose Status then Refinery Status from the Main menu.

21.10.1.2 Viewing Refinery Logs

To view the refinery log files:

Log in to the refinery.
Choose Home in the main menu and select the Refinery Logs tab, or choose Status then Refinery Status from the Main menu and select the Refinery Logs tab.
On the Refinery Logs page, click a log link to display the refinery log.

21.10.1.3 Viewing Console Output

To view the refinery console output:

Log in to the refinery.
Choose Home from the Main menu and select the Console Output tab, or choose Status then Refinery Status from the Main menu and select the Console Output tab.
- Click Update to refresh the console output.
- Click Clear to clear the console output.

21.10.1.4 Viewing Conversion History

To view the last fifty conversions in the conversion history for a specific refinery agent:

Log in to the refinery.
Choose Status then agent_name from the menu and select the Conversion History tab, or choose View Conversion History from the Actions menu for the agent on the Refinery Status page.
On the Conversion History page, click a Content ID link to display the Conversion Detail page.

21.10.2 Viewing Agent Statuses

The status of a specific agent can be viewed as well as the queues for all agents.

21.10.2.1 Viewing Specific Status

To view the current status of conversions for a specific refinery agent:

Log in to the refinery.
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.

21.10.2.2 Viewing Agent Queues

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

Log in to the refinery.
From the navigation menu, choose Status then agent_name and select the Items in Queue tab, or choose View Items In Queue from the Actions menu for the agent on the Refinery Status page.
On the Items in Queue page, click Refresh to update the information on the page.

21.10.2.3 Viewing Agent Logs

To view the log files for a specific refinery agent:

Log in to the refinery.
From the navigation menu, choose Status then agent_name and choose the Agent Logs tab, or choose View Agent Logs from the Actions menu for the agent on the Refinery Status page.
On the Agent Logs page, click a log link to display the refinery agent log.