12 Monitoring, Customizations and Audit Tools

Several optional tools are available to help administrators customize and track system performance and usage:

• Performance monitoring can be used to check the length of time needed to process service requests, to monitor batch requests and to check for items that have failed to process.

• Custom scripts can be written and applied to content for access control and to add notifications. This complies with DoD Chapter 4 certification requirements.

• Audit trails capture and record all user activity configured to be included. An audit trail is critical for tracking user actions within a record management system.

This chapter discusses using monitoring, custom scripts, and audit trails. It covers the following topics:

• Section 12.1, "Using Performance Monitoring"

• Section 12.2, "Using Custom Scripts"

• Section 12.3, "Using the Audit Trail"

12.1 Using Performance Monitoring

Performance monitoring can be enabled to check the status of batch processing, service calls, and other system information.

Several default numbers have been set as a starting point for monitoring. Actual performance variations will depend on the hardware used at the site and other variables such as total amount of content and software in use.

The frequency with which you need to update statistics depends on how quickly the data is changing. Typically, statistics should be updated when the number of new items since the last update is greater than ten percent of the number of items when the statistics were last updated.

If a large amount of disposition processing is being done (for example, at the end of the calendar year for organizations that synchronize dispositions on the calendar), you should update statistics at the end of the week rather than wait for a particular percentage of data updates.

Performance monitoring statistics are written to a database table and can be accessed later.

12.1.1 Enabling Performance Monitoring

Follow this procedure to use performance monitoring:

1. Choose Records then Audit from the Top menu. Choose Configure then Performance Monitoring.

   The Configure Performance Monitoring Page opens.

2. Select the items to monitor and the time intervals for reports and alerts.

3. Click Submit Update when done.

12.1.2 Checking Performance Results

After enabling performance monitoring, current performance information can be checked using this procedure:

1. Choose Records then Audit then Performance Monitoring from the Top menu.

   The Performance Processing Results Page opens.

2. Choose the type of information to view by clicking the tab at the top of the body section of the page:

   • Performance Processing: This page contains a summary of requests processed, total items processed, total number of queries run, total time to run queries, total time to validate data, total service request parse time and total service request time per each source. Averages for these are also included.

   • Report by Batch: This page contains a summary of batches/items pending, processed, and failed with a total for each source. If an item has failed, a batch file is created that can be re-run. Click on any value in a column to open a page showing details about that item and to access the option to re-run the batch.

   • Report by Item: This page contains the details per batch for a particular source, status or batch type as well as totals. The detail page for the item contains the batch type, start time, completed time, elapsed time, and number of items processed for each batch.

12.1.3 Viewing Performance Alerts and Details

If any performance activities exceed the limits set on the Configure Performance Monitoring Page, a message is displayed automatically when you log in to the system.

Click any link on the message to see details about the specific alert. For example, a detail screen opens when the first alert message is clicked. Click any link to show details about the specific items that caused the alert.

12.2 Using Custom Scripts

Custom scripts can be created using Idoc Script, a proprietary scripting language. This functionality is enabled by default when the DoD Configuration component is enabled. See the Oracle WebCenter Content Setup Guide for Records for details about different options.

Custom scripting can be disabled by deselecting Enable Custom Script in the DoD Config section of the Configure Retention Settings Page. To access that page choose Records then Configure then Settings from the Top menu.

When enabled, new content fields are available that allow you to define which scripts will apply to a folder or category.

Caution:

You must have a thorough understanding of Idoc Script to use this feature. The software does not validate the script. You are responsible for creating usable scripts. See the Oracle WebCenter Content Idoc Script Reference Guide for details about Idoc Script and its use.

Two types of scripts can be created using the Custom Script functionality:

• Security scripts, which allow users with the Records Administrator role to define and manage access control to content.

• Custom Notification scripts, which notify users of events. One custom script is provided, which notifies a list of reviewers when items are due for destruction after being superseded. Notification is sent in one consolidated e-mail when batches are run. Additional scripts can be created.

Scripts can be applied at a category or folder level but content in the category or folder does not automatically inherit the script. Consider the following scenario:

• A custom script is created to prevent user A from viewing content.

• A folder is created and the custom script is applied to it.

• An item is checked in by user B to the folder.

• User A browses through the folder and sees the title of the item checked in by user B. However, if user A tries to view the actual item, an error is returned.

To prevent user A from even seeing the title of the item, the security script must be set so items included in the object (category or folder) explicitly inherit the attributes of the script. For example, to set inheritance in a category, the following variable would be set in the config.cfg file:

RecordsMetaInheritFromCategory=dSecurityScripts:xSecurityScripts

To set inheritance for a folder, use the RecordsMetaInheritFromFolder variable.

Note:

Custom scripts comply with the DoD 5015.2 specification, chapter 4.19 and chapter 4.20.

12.2.1 Creating or Editing Scripts

Note:

Any custom Idoc script that is entered is NOT verified for accuracy. You should have knowledge about Idoc script and its uses before creating scripts.

Follow this procedure to set up a custom script. Use the same procedure for both types of scripts.

1. Choose Records then Configure from the Top menu. Choose Security then Custom Scripts.

   The Configure Custom Script Page opens.

2. Select the type of script to use (Notification or Security) by clicking the tab for the script type. To edit an existing script, choose Edit from the script's Actions menu. To add a script, choose Add or Edit on the Custom Script Information Page.

   The Create or Edit Custom Script Page opens.

3. Add or edit the name for the script.

4. Add or edit the description for the script (optional).

5. Add or edit the Idoc code for the script. Note that the code is not verified for accuracy.

6. When finished adding a new script, click Create. When editing a script, click Submit Update. To reset the page without saving, click Reset.

12.2.2 Deleting a Custom Script

Follow this procedure to delete a custom script. Use the same procedure for both types of scripts.

1. Choose Records then Configure from the Top menu. Choose Security then Custom Scripts.

   The Configure Custom Script Page opens. Select the type of script for deletion by clicking the tab for either a Notification or a Security script.

2. To delete the script, select the box next to the script name and choose Delete or Delete Script from the script's Actions menu. You can also choose Delete on the Custom Script Information Page.

12.2.3 Viewing Script Information

Follow this procedure to view a script's information:

1. Choose Records then Configure from the Top menu. Choose Security then Custom Scripts.

   The Configure Custom Script Page opens. Select the script for viewing by clicking the tab for either a Notification or a Security script.

2. To view the script information, click the script name or choose Script Information from the script's Actions menu.

   The Custom Script Information Page opens.

12.3 Using the Audit Trail

The audit trail is generated in the format specified by the Report Format setting on the Configure Report Settings Page.

Permissions:

The Admin.Audit right is required to work with audit trails. This right is assigned by default to the Records Administrator role. Administrative privileges are required to check in the audit trail.

At certain points, the current audit trail can be cut off and archived and checked into the repository. This action can also be scheduled to occur on a regular basis. The audit trail must be cycled for growth reasons the same as other items. Be sure to check in the audit trail log on a regular basis to keep the file size smaller and the report generation time faster. Each current audit trail is generated from the time the system was installed or archived until the request to generate an audit trail.

An audit trail can be generated at any time. The columns within the audit trail correspond directly with the fields you can use to search within the Search Audit Trail Page.

If the generated file is in PDF format, Adobe Acrobat version 6.0 or later is required to view it.

Several tasks are involved in managing Audit Trails:

• Section 12.3.1, "Configuring the Audit Trail"

• Section 12.3.2, "Specifying Metadata Fields to Audit"

• Section 12.3.3, "Searching within the Audit Trail"

• Section 12.3.4, "Setting Default Metadata for Checking In Audit Trails"

• Section 12.3.5, "Checking In and Archiving the Audit Trail"

• Section 12.3.6, "Searching an Archived Audit Trail"

• Section 12.3.7, "Viewing an Archived Audit Trail"

12.3.1 Configuring the Audit Trail

The configuration on the Configure Audit Page determines the administrator and user actions recorded for an audit trail.

Permissions:

The Admin.Audit right is required to perform this action. This right is assigned by default to the Records Administrator role.

To configure an audit trail, complete the following steps:

1. Choose Records then Audit from the Top menu. Choose Configure then Audit Trail.

   The Configure Audit Page opens.

2. Select the boxes for the actions to audit for each entity.

3. Click Submit Update. A message indicates configuring the audit was successful. The next time the audit trail is generated, the trail reflects the chosen selections.

4. Click OK. The Configure Audit Page opens again with the updated settings.

   Caution:

   If actions are deselected for objects, the actions are not captured by the audit trail. It is recommended you leave all settings selected and use the Search Audit Trail Page to narrow down searches of the audit trail. If transactions are heavy and the audit log grows too large too fast, you might want to consider turning off capturing browsing actions to manage the audit trail size.

12.3.2 Specifying Metadata Fields to Audit

Use this procedure to specify which metadata fields should be included in the audit trail.

Permissions:

The Admin.SelectMeta right is required to perform this action. This right is assigned to the Records Administrator role by default.

1. Choose Records then Audit from the Top menu. Choose Configure then Audit Fields.

   The Audit Fields Page opens.

2. Select the boxes for the metadata field to include in the audit trail.

3. Click Submit Update when done.

Any changes take effect immediately without restarting the system.

12.3.3 Searching within the Audit Trail

Use this procedure to further refine a search within the current audit trail. For example, you can search for all delete actions, or all delete actions by a particular user, or all actions by a particular user, and so on. To search within archived audit trails, see Section 12.3.6, "Searching an Archived Audit Trail."

When sorting the audit trail using Oracle DB, the output depends on the type of sort being performed. When sorting with Fulltext Search, sorting is case-sensitive, meaning that upper case items (capitalized items) will appear first in a list. When sorting with Oracle Text Search, a case-insensitive search is performed.

Permissions:

The Admin.Audit right is required to perform this action. This right is assigned by default to the Records Administrator role.

1. Choose Records then Audit from the Top menu. Choose Search Audit Trail.

   The Search Audit Trail Page opens.

2. Make the selections to narrow the search. As much or as little detail can be included. To adjust the scope (narrow or widen) of the search, use the Boolean operators before each field.

3. Click Search. The search results are displayed in the format specified by the Report Format setting on the Configure Report Settings Page.

12.3.4 Setting Default Metadata for Checking In Audit Trails

Setting the default metadata is useful for setting similar checkin attributes. You must set the default metadata before checking in an audit trail for the first time. This is a required step during the setup of the software.

Permissions:

The Admin.Audit right is required to perform this action. This right is assigned by default to the Records Administrator role.

To set the default metadata for checking in and archiving a portion of the audit trail, complete the following steps:

1. Choose Records then Audit from the Top menu. Choose Checked-in Audit Entries.

   The Checked-in Audit Entries Page opens.

2. Click the Default Metadata for Checked-In Audit Entries link.

   The Default Metadata for Checked-In Audit Entries Page opens.

3. Make selections reflecting the metadata most commonly used when checking in an archived audit trail. When finished, click Submit Update. A message is displayed saying the default metadata has been updated successfully.

4. Click OK.

12.3.5 Checking In and Archiving the Audit Trail

A user must have performed at least one action while logged into the system to generate an audit trail entry. If an empty audit trail is submitted for check-in, a message is displayed indicating there are no entries in the audit trail. Before checking in an audit trail for the first time, set the default metadata for the checkin. For details, see Section 12.3.4, "Setting Default Metadata for Checking In Audit Trails."

Permissions:

The Admin.Audit right is required to perform this action. This right is assigned by default to the Records Administrator role.

1. Choose Records then Audit from the Top menu. Choose Checked-in Audit Entries.

   The Checked-in Audit Entries Page opens.

2. In the Check In Audit Entries area, specify the date and time to cut off the audit trail in the Date box, and click Archive.

3. The checkin confirmation page opens. The content ID of the checked-in audit trail is AUDITLOGARCHIVE. Every time it is checked in, a new revision is generated.

4. Click Content Info to view the information about the archived audit log. The Content Information Page opens. To view the audit log just checked in, click the Web Location or the Native File in the Links area of the Content Information page.

12.3.6 Searching an Archived Audit Trail

Use this procedure to search for all checked in and archived audit trails.

Prerequisites

• Section 12.3.5, "Checking In and Archiving the Audit Trail"

  Permissions:

  The Admin.Audit right is required to perform this action. This right is assigned by default to the Records Administrator role.

1. Choose Records then Audit from the Top menu. Choose Checked-in Audit Entries.

   The Checked-in Audit Entries Page opens.

2. Click Search Audit Entries. The results of the search are displayed in the search results page. From the search results page, click options in the Query Actions list to search within the results and save the search.

12.3.7 Viewing an Archived Audit Trail

Use this procedure to view an archived audit trail.

Prerequisites

• Section 12.3.6, "Searching an Archived Audit Trail"

To view an archived audit log from the search results page, do one of the following:

• Click the ID (quickest method)

• Click the Info icon then click the PDF links on the Content Information page.

12.3.8 Creating an Audit Trail Report

An audit trail report is automatically generated in the format specified by the Report Format setting on the Configure Report Settings Page. If the generated file is in PDF format, Adobe Acrobat version 6.0 or later is required to view it.

The following is a sample audit trail report.