| Oracle® Beehive Integration Guide Release 2 (2.0.1.8) Part Number E16650-06 |
|
|
PDF · Mobi · ePub |
| Oracle® Beehive Integration Guide Release 2 (2.0.1.8) Part Number E16650-06 |
|
|
PDF · Mobi · ePub |
This module provides an overview and steps for integrating Oracle Universal Records Management (Oracle URM) with Oracle Beehive.
This module includes the following topics:
Oracle URM enables organizations to manage their records and retention policies, disposition processes, and litigation holds or freezes in a central repository. Organizations can then apply those policies, dispositions, and holds to content stored in other systems, such as Oracle Beehive. Oracle Beehive integrates with Oracle URM through a records management service.
Records management is an optional service. It is enabled by installing and configuring Oracle Beehive with Oracle URM, which provides life cycle and disposition management of records-managed Oracle Beehive artifacts. After Oracle URM is installed and configured with Oracle Beehive, you may start the records management service and begin filing records for documents and e-mails.
Oracle Beehive manages records organized through Oracle URM. Oracle Beehive retains artifacts for which you have filed records within the Oracle Beehive database, but treats them differently from other artifacts.
When an artifact becomes records-managed in-place, Oracle Beehive ensures that the content is never truly altered or deleted from the system unless an Oracle URM action is issued. From an end-user perspective, users are able to delete e-mails or documents that are records-managed, and empty them from the Workspace Trash.
Those records-managed artifacts are stored in a special Records Management container in the Oracle Beehive database. The Oracle URM application can still query for, and perform operations on these stored artifacts.
Artifacts may be placed under retention, which means that they can be treated as regular artifacts by Oracle Beehive.
Artifacts may also become records-managed without being placed under retention. These types of records are called non-records (as a short form of non-retained records). Artifacts with non-records may be treated as regular artifacts, including being modified or deleted, by Oracle Beehive. Oracle URM sends an instruction to Oracle Beehive to handle non-record artifacts if they still exist in the system.
In Oracle Beehive, you can create records of any of the following:
Any document stored in a workspace in Oracle Beehive
Any e-mail in an Oracle Beehive e-mail Inbox or subfolder of an Inbox
Any e-mail sent from an Oracle Beehive e-mail user, if you turn on this feature by setting a property of the E-mail Service
As an administrator, you may manually file records for these artifacts using a beectl command, or by using Oracle Beekeeper. Additionally, you may create policies to automatically file records for documents and e-mails, based on triggering criteria.
Note that Oracle Beehive's built-in auditing function automatically audits events related to Records Management. Such auditing is not configurable by the administrator. You may, however, create an audit trail to review record management activity. For more information about auditing in Oracle Beehive, see "Managing Audit Policies" in Oracle Beehive Administrator's Guide.
Whenever a document is filed as a record, metadata about the artifact is sent to Oracle URM. This metadata describes the artifact and its original context. The artifact itself continues to be stored in Oracle Beehive. This ensures that the content is immutable from a system perspective (unless it is a non-record).
Table 7-1 lists the document metadata sent to Oracle URM with documents. Table 7-2 lists the metadata sent to Oracle URM when e-mail messages are filed as records.
Table 7-1 Artifact Metadata Sent to Oracle URM with All Artifacts
| Name | Type |
|---|---|
|
CollabID |
|
|
Creator Name |
|
|
Artifact URL |
|
|
Media Type |
|
|
Creation Date |
Date in " |
Table 7-2 Artifact Metadata Sent to Oracle URM with E-Mail Messages
| Name | Type |
|---|---|
|
Sender |
|
|
Sent Date |
Date in " |
|
Subject |
|
|
Hidden Addresses |
|
|
Primary Addresses |
|
|
Secondary Addresses |
String, comma delimited list of addresses |
Deploying Oracle Beehive with Oracle URM requires that you have both an Oracle Beehive instance and an Oracle URM 10g R3 (or later) instance installed and configured.
To integrate Oracle URM with Oracle Beehive, you perform certain tasks in Oracle Beehive and other tasks in Oracle URM, as follows:
In Oracle URM, ensure that the Records Management administrator has all the relevant roles and privileges. For details of this process, see "Step 1: Granting the Necessary Roles to the Records Management Administrator".
In Oracle Beehive, register Oracle URM and configuring Oracle Beehive. This includes the following:
Specifying the Oracle URM instance in Oracle Beehive
Enabling the Records Management Service
Optionally, enabling record filing of sent e-mails in Oracle Beehive.
Updating the Oracle Beehive configuration
Restarting the BEEAPP managed component
For details of this process, see "Step 2: Registering Oracle URM and Configuring Oracle Beehive".
In Oracle URM, create retention categories and record folders. This includes the following:
Creating retention categories in Oracle URM
Creating record folders under a retention category
Optionally, viewing the retention categories and folders in Oracle Beehive
For details of this process, see "Step 3: Creating Retention Categories and Record Folders in Oracle URM".
In Oracle URM, set up disposition rules on retention categories. For details of this process, see "Step 4: Setting Up Disposition Rules in Oracle URM".
For detailed instructions on installing and configuring Oracle URM see the Oracle Universal Records Manager Installation Guide.
Note that a special administrator account with super user privileges on all data may be created in Oracle Beehive. This account may be used for queries in Oracle URM, to enable access to the records that Oracle URM is pulling from Oracle Beehive.
The following sections describe the steps for integrating Oracle URM with Oracle Beehive. Both Oracle Beehive and Oracle URM should be installed before you perform these tasks. Additionally, you must have administrator privileges.
The Oracle Beehive Records Management Service uses the Oracle URM administrator account and Web Services to connect to Oracle URM. To enable this connection, you must grant the necessary roles to the Oracle URM administrator account.
To grant necessary roles to the Records Management administrator:
Log in to Oracle URM.
Click Admin Applets.
Click User Admin.
Select the Admin user (sysadmin).
Click Edit.
Add the following roles: rma, rmaadmin, admin, ermadmin, ermrequestor, rmaprivileged, and sysmanager.
Note:
If the values for these roles change in Oracle URM, corresponding changes must made in Oracle Beehive, and the Records Management Service must be restarted. You may use the
beectl modify_property command to update these values in Oracle Beehive.Click Save.
Exit the interaction.
To register Oracle URM and configure Oracle Beehive, complete the following tasks:
To specify the Oracle URM instance in Oracle Beehive, you can use the beectl command-line utility or Oracle Beekeeper.
To specify the Oracle URM instance using the beectl utility:
On the operating system command line, issue the beectl add_urm command to configure an agent for an Oracle URM instance, as follows:
beectl add_urm --rm_admin_name URM_Inst_RM_Administrator_Name --rm_admin_password URM_Inst_RM_Administrator_Password --urm_url URM_Inst_URL --rm_email_admin RM_Administrator_Email_Id [--disposition_loader_interval URM_Inst_Disposition_Loader_Interval] [--disposition_processor_interval URM_Inst_Disposition_Processor_ Interval] [--agent_name URM_Inst_Agent_Name]
where:
rm_admin_name is the Records Management administrator name for the Oracle URM instance. Permitted type is String. This option is mandatory.
rm_admin_password is the Records Management administrator password for the Oracle URM instance. Permitted type is a secure string. A prompted value (with re-confirmation) or an obfuscated value (along with --obfuscated option) may be provided on the command line. In shell mode, clear text may also be provided. This option is mandatory.
urm_url is the URL for the Oracle URM instance. Permitted value is String. This option is mandatory.
This URL, which is required by the adapter to communicate with the Oracle URM server, depends on the Oracle URM instance name and server name specified during installation. This URL may be obtained from any URL to the Oracle URM server on the Web interface. For example, a service requests on the Web interface may be of the following form. Discard everything after the question mark. The service URL is the first part of any service URL string. In this case, it is the text in bold face.
http://urm.yourcompany.com/xpedio/idcplg?IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=HOME_PAGE&Auth=Internet
rm_email_admin is the e-mail ID of the Records Management administrator. Permitted type is String. This option is mandatory.
If you use the rm_email_admin option to enable filing records of sent e-mail messages, the supplied user account must exist in Oracle Beehive. After activating the configuration, you cannot easily change this account value, so select it carefully. If you must change this account, contact Oracle Support.
disposition_loader_interval is the disposition loader interval for the Oracle URM instance. Permitted type is Long.
disposition_processor_interval is the disposition processor interval for the Oracle URM instance. Permitted type is Long.
agent_name is the agent name for the Oralce URM instance. Permitted type is String.
The agent name, specified by the agent_name option, may be any meaningful name that indicates that this agent is for the Oracle Beehive Records Management Service. It may contain up to 30 characters. Possible examples may be BeeAdapter or BeehiveRMAdapter.
Issue the beectl activate_configuration command:
beectl activate_configuration
To specify an Oracle URM instance using Oracle Beekeeper:
For the steps for specifying an Oracle URM instance using Oracle Beekeeper, refer to "Records" in the Oracle Beekeeper Online Help.
To enable the Records Management Service in Oracle Beehive, you can use the beectl command-line utility or Oracle Beekeeper.
To enable the Records Management Service using beectl:
Enable the Records Management Service by using the beectl modify_property command.
beectl>modify_property --component <RecordsManagementServiceInstance_id> --name Status --value ENABLED
Note that the records management service is disabled by default.
Note also that you can get the component identifier for the Records Management Service instance by using the beectl list_components command.
To enable the Records Management Service using Oracle Beekeeper:
For the steps for enabling the Records Management Service using Oracle Beekeeper, see "Managing Services" in the Oracle Beekeeper Online Help.
By default, you can file records of e-mail messages from any Oracle Beehive user's Inbox or subfolder of Inbox. However, to file records of e-mail messages sent by Oracle Beehive users, you have to modify a property of the Transport Properties subcomponent of the E-mail Service. To do this, run the beectl modify_property command.
Note:
Enabling record filing of sent e-mails is optional.To enable record filing of sent e-mails:
At the command prompt, issue the beectl modify_property command:
beectl modify_property --component _EmailService:TransportProperties --name SentEmailPluginEnabled --value true
where:
component is the Email Service, _EmailService:TransportProperties
name is the name of the property to modify, SentEmailPluginEnabled
value is the Boolean value for the named property, true
Issue the beectl activate_configuration command:
beectl activate_configuration
For more information about enabling record filing of sent e-mails, see "Configuring Sent E-mail Plugins" in Oracle Beehive Administrator's Guide.
To update the proposed configuration in Oracle Beehive:
Use the beectl activate_configuration command to update Oracle Beehive with this proposed configuration:
beectl> activate_configuration
BEEAPP is a managed component that contains a variety of Beehive services, such as the E-mail Service, the Presence Service, and the Records Management Service. You must restart it to use the new configurations and to restart the Records Management Service.
To restart the BEEAPP managed component:
Restart the BEEAPP OC4J managed component using the beectl restart command with the --component option:
beectl> restart --component <your OC4J BEEAPP component identifier>
You can use the beectl status command to list the managed components and their identifiers for your deployment.
After completing the steps in "Step 2: Registering Oracle URM and Configuring Oracle Beehive", log in to Oracle URM using a Records Management administrator account. Create the various Retention Categories and Record Folders as required by your organization. You may create retention categories either under Record Series or under File plan in the Oracle URM user interface. You may create Record Folders either under a retention category or under another record folder (nested record folders).
To create retention categories and record folders:
Click Create and select Retention Category to create a retention category under a file plan.
Click a record series, then click Create and select Retention Category to create a retention category under a record series.
For each retention category, provide values required on the creation page. The retention category ID must be unique, but names can be duplicated. If the Allow Non-records is checked, then the retention category will allow the check-in of non-records, artifacts that respect disposition rules but have no content modification or deletion restrictions.
Click a retention category, click Create, and select Record Folder to create a record folder under a retention category.
Open a record folder, click Create, and select Record Folder to create a record folder within another record folder.
Fill in the values required on the creation page and provide a unique record folder ID for each new record folder.
This is an optional step. To review the new retention categories and record folders in Oracle URM, view them in Oracle Beehive, in the beectl shell, using the list_file_plan command:
beectl> list_file_plan
Disposition rules are set on Retention Categories only. In Oracle Beehive, the Records Management Service supports only the DESTROY disposition action.
Disposition rules are set within the Oracle URM user interface.
To set up disposition rules for testing:
On the retention category page, select the Information drop-down list and click Disposition Information.
On the Disposition Instruction page, click the Add link.
A Disposition Rule panel displays.
On the Disposition Rule panel, select a triggering event.
For Oracle Beehive Records Management disposition tests, choose the Cancel event, which can be triggered from the Oracle URM administrator UI.
Specify a retention period.
For Oracle Beehive Records Management disposition tests, set the retention period to zero weeks.
Choose Disposition Action Destroy.
Leave the Destination Location and Destination Container blank.
Set values for Apply to Records Folder and Notification Reviewer.
By default, the Notification Reviewer is sysadmin.
Click Actions, select Trigger Dates, and select Cancel on the record from Oracle URM.
This is a mandatory action that triggers a cancel action and starts disposition processing in Oracle URM.
This section describes how to administer your Oracle URM and Oracle Beehive integration. This section includes the following topics:
You can manually file records of artifacts (documents and e-mails) using beectl commands. You can also file records automatically, using policies.
Each of these procedures is detailed in the following sections:
These tasks are comprehensive and fully explain the use of records in Oracle Beehive. However, Oracle recommends that in most cases you can use Oracle Beekeeper to manage records. For more information, see "Records" Oracle Beekeeper Online Help.
The command-line based record filing is provided primarily as a tool for system administrators to manually file records that were not filed using a policy action, using the beectl add_record command.
To manually file records using beectl:
At the command prompt, issue the beectl add_record command:
beectl add_record --artifact artifact_to_file_identifier { --retention_category Oracle_URM_retention_category_identifier | --record_folder Oracle_URM_record_folder_identifier } [ --no_retention Boolean_specifying_if_record_or_non-record ]
where:
artifact is the identifier of the artifact that must be filed
retention_category is the identifier of the retention category for the document, which is defined in Oracle URM; use either this parameter, or retention_folder
record_folder is the identifier of the record folder in Oracle URM; use this parameter or retention_category
no_retention is the Boolean value that specifies true if a record is of a non-retention type (non-record)
This is an optional step. To view a list of record categories and record folders, along with their identifiers, issue the beectl_list_file_plan command:
beectl> list_file_plan
You can make use of the Oracle Beehive policy framework to create records management policies. Records management policies automate the process of filing records for artifacts. You specify a policy condition for record filing, and a destination Retention Category. Oracle Beehive automatically files records for artifacts that meet the policy condition.
To set up a records management policy:
Select a Retention Category for this policy. All records that meet this policy's condition will be filed into that Retention Category. You can list available Retention Categories using the beectl list_file_plan command:
beectl> list_file_plan
Create an Oracle Beehive policy XML file, using the special Records Management policy action File a Record, and setting the actionPreferenceInfo, as in the following example:
...
<ActionInfo>
<name>File a Record</name>
</ActionInfo>
<ActionPreferenceInfos>
<actionPreferenceInfo>
<key>category_id</key>
<value>Your Category ID</value>
</actionPreferenceInfo>
<actionPreferenceInfo>
<key>is_record</key>
<value>true</value>
</actionPreferenceInfo>
</ActionPreferenceInfos>
...
In this example, you must replace Your Category ID with the actual Retention Category ID you determined in step 1
Complete the XML file by specifying conditions to trigger the policy. Any condition which is valid for an Oracle Beehive policy may be used.
See Also:
For detailed instructions on how to create Policy XML files, refer to "Creating and Managing Custom Policies" in the Oracle Beehive Administrator's Guide.Create the policy by issuing the beectl add_policy command:
beectl> add_policy --file full_path_to_policy_xml_file
The following example demonstrates a typical Records Management policy. Here, a record is filed on any file uploaded to a specified folder, with the Retention Category LC.
<?xml version="1.0" encoding="UTF-8" ?> <PolicyInfo isExtensible="true"> <policy></policy> <scope></scope> <template></template> <name>Records Management Document Policy</name> <description>This policy files all documents uploaded to container identified by eid 4A92592959297602769797962 under retention category with id LC</description> <attributes> <attributeDefId></attributeDefId> <type></type> <value></value> </attributes> <RuleInfos> <RuleInfo priority="1"> <name>RULE ONE</name> <description>Rule One</description> <eventTypeName>DOCUMENT_CREATED</eventTypeName> <ruleId></ruleId> <toRemove>false</toRemove> <templateRuleIds> <templateRuleId></templateRuleId> </templateRuleIds> <ConditionInfo> <Simple> <leftSide>common_attributes.container.eid</leftSide> <operator>=</operator> <rightSide>'4A92592959297602769797962'</rightSide> </Simple> </ConditionInfo> <ActionInfo> <name>File a Record</name> </ActionInfo> <ActionPreferenceInfos> <actionPreferenceInfo> <key>category_id</key> <value>LC</value> </actionPreferenceInfo> </ActionPreferenceInfos> </RuleInfo> </RuleInfos> </PolicyInfo>
Filing an artifact as a record makes it immutable when it is under records management control. Conversely, this means that no Oracle Beehive command or action may delete the artifact.
To release an existing artifact from records management control, you must use the beectl delete_record command. You must have the RECORDS_MGR privilege.
Note that the beectl delete_record command cannot be reversed or undone. It also does not delete the artifact from Oracle Beehive. Instead, it removes the designation of that artifact as a record, enabling other Oracle Beehive operations to handle it normally (including deleting).
Note also that if the artifact is in the Record Store and its records management is removed or released, that artifact is deleted from the system. Only deleted and purged records-managed artifacts are placed in the Record Store. When the record for the artifact is deleted, the earlier action of deleting the artifact completes.
To delete a record from Oracle Beehive:
Issue the beectl delete_record command:
beectl> delete_record --artifact artifact_to_delete_identifier
where:
artifact is the identifier of the artifact that must be deleted
This section describes actions you can take to help troubleshoot issues with Records Management in Oracle Beehive. If you cannot diagnose your problem using the following steps, then contact your Oracle support representative.
This section contains the following topics:
Use the following steps as guidelines for troubleshooting cases where the filing of a record for an artifact failed to occur.
To troubleshoot a failed record filing:
If a policy-based record filing failed, then check the following:
Check to see if the policy was successfully registered, using the beectl list_policies command. If your policy is not listed, then it has not been created in Oracle Beehive.
Check that the policy was created at the correct scope and for the correct operation (event). Events include DOCUMENT_CREATED, ES_MSG_SENT for filing sent e-mail messages as records, and ES_MSG_DELIVERED for filing received e-mail messages as records. Review the policy XML file for the scope and event attributes, ensuring there are no errors.
Attempt to create a policy with the same triggering conditions and scope, but with a general (non record-filing) action.
Test to see if this policy successfully runs when the triggering event occurs.
Note that when writing policies for filing records of e-mail messages, you should be aware that a separate e-mail event is raised for each recipient of an e-mail. The event payload of each event contains the recipient_eid of the user.
Note also that if you create a policy that depends on recipient_eids with two or more different values, it will never evaluate to true because the policy only evaluates events that containing one recipient.
Ensure that the Records Management Service is running.
Use the beectl status --all_services command, and check the status of the Records Management Service.
Alternatively, run the beectl list_file_plan command. It completes successfully only if the Records Management Service is running.
Ensure that your Oracle Universal Records Management Server is running. You can verify this by logging in to Oracle URM as sysadmin.
Review the log files for the BEEAPP component, to see if the Records Management Event Action is triggered. Event processing is asynchronous, so there is a delay between the service raising an event (such as document_created) and the event service sending the event to the interested service (in this case the Records Management Service). If the log file does not show the Records Management Event Action, then it may be that the event was not dispatched.
The log file is located at $ORACLE_HOME/beehive/logs/oc4j/BEEAPP/log.txt. You may have rotated logs of the format log.txt.<number>.
In the Oracle Beehive database, check the ECA_FAILED_ACTION_DETAILS in the bee_code schema for any exception message stored for event processing failures.
Log in to Oracle URM as sysadmin. Select Browse Content and Search for Records filed under the name of the Adapter that was used when you registered Oracle URM with Oracle Beehive. Try to locate the CollabID for the document or e-mail for which you are trying to file a record, in the list of returned records.
The Records Management Service audits all possible actions and errors. You can query the AUDIT_RECORDS table with the event names that should have triggered the records management policy, to see if there are any results.
Check the ocs_logs table in the bee_code schema. Messages are stored here in the event that auditing fails.
Typically, deleting a record of an artifact is a synchronous manual operation, so the exception message returned by beectl should tell you what went wrong.
Use the following steps as guidelines for troubleshooting cases where the removal of an artifact's record failed to occur:
Ensure that the Records Management Service is running. You can use the beectl status --all_services command, and check the status of the Records Management Service. Alternatively, try running the beectl list_file_plan command: this command only completes successfully if the Records Management Service is running.
Ensure that your Oracle Universal Records Management Server is running. You can verify this by logging in to Oracle URM as sysadmin.
Disposition processing is an asynchronous automatic processing performed by the Records Management Service. By default, Oracle Beehive loads and processes dispositions from Oracle URM once every hour.
Use the following steps as guidelines for troubleshooting cases where a record disposition failed to occur:
Ensure that the Records Management Service is running. You can use the beectl status --all_services command, and check the status of the Records Management Service. Alternatively, try running the beectl list_file_plan command. This command completes successfully only if the Records Management Service is running.
Ensure that your Oracle Universal Records Management Server is running. You can verify this by logging in to Oracle URM as sysadmin.
Review the log files for the BEEAPP component and the ocs_logs table in the bee_code schema, to see if there are any messages that indicate dispositions have been fetched from Oracle URM and loaded in the Oracle Beehive database.
If there are any dispositions listed, check the AUDIT_RECORDS table and ocs_logs table for disposition errors. If a disposition action fails, its status will be changed to ERR. The disposition_exception column indicates the cause of the failure, along with a full stack trace.
During the procedure outlined in "Step 2: Registering Oracle URM and Configuring Oracle Beehive", if the beectl add_urm command was specified with incorrect rm_admin_name, rm_admin_password, or urm_url properties, or if these values change (such as if you change the Oracle URM admin password), you can use the beectl modify_property command to change the values:
beectl> modify_property --component component_id_URM_connector_from_add_urm --name property_name --value new_value
You can find the component ID by using the beectl list_components command:
beectl> list_components --type your_company_URM
You can then list the properties of the component using the beectl list_properties command:
beectl> list_properties --component component_identifier
After making changes to component properties, you must run the beectl activate_configuration command to validate and activate your proposed configuration:
beectl> activate_configuration
Oracle URM processes dispositions in batches. The impact of this is that disposition tasks are not necessarily available at any given time. For convenient testing of dispositions in Oracle Beehive, you can make the following configuration changes:
From the Oracle URM administrator UI, click Administration, select Configure Records Management, choose the Audit tab, and select Checked-in Audit Entries.
On the option screen that opens, click the link for Default Metadata for Checked-in Audit Entries.
A check-in screen will open. Enter a value in the required Title field for the title of the checked in Audit logs and click the Submit button.
Select a retention category, and the system will list records checked in under this retention category by a given agent.
Choose a few documents, click Actions, select trigger dates, and select Cancel.
Wait for one to two minutes for the Oracle URM table to get updated. Then from Administration, select Configure Records Management, select Batch Services, and select Run All.
Click My Content Server and select My Records Assignments. All due dispositions appear on the list.
Use the actions icon to the right of a particular disposition to approve it. After, the disposition is in a pending completion state.
To see the disposition, click Pending Completion tab and choose My Completed Option for the external source. This approves the disposition and shows it as a pending disposition for the Oracle Beehive adapter.
|
 Copyright © 2008, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|