Skip Headers
Oracle® Beehive Integration Guide
Release 2 (2.0.1.8)

Part Number E16650-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Integrating Oracle Information Rights Management (Oracle IRM) with Oracle Beehive

This module describes how to integrate Oracle Information Rights Management (Oracle IRM) 11g with Oracle Beehive. This module assumes the user has a strong understanding of the concepts and procedures related to managing Oracle IRM and developing applications for it.

This module includes the following topics:

For detailed information about Oracle IRM, see the following guides:

Overview of Oracle Information Rights Management (Oracle IRM)

Oracle Information Rights Management (Oracle IRM) enables users to manage and access sealed documents. When integrated with Oracle Beehive, users can seal documents inside Oracle Beehive workspaces. Document owners (that is, participants who add documents to workspaces) control access to their sealed document and any subsequent copies, including those saved by users on their computers or sent as e-mail attachments.

For example, consider a workspace called Patents, to which an Oracle Beehive administrator configures and applies an Oracle IRM policy that automatically seals all documents within the workspace. A workspace participant (Joe), uploads a document called beehive-patent.doc to the workspace. Joe's action automatically seals beehive-patent.doc as beehive-patent.sdoc, according to the specifications of the previously mentioned policy.

Note:

When a document is sealed, its extension is modified with the addition of a leading .s*. For example, Microsoft Word documents have an extension .sdoc. Microsoft Excel documents have an extension .sxls. Oracle IRM handles the conversion to the new extensions.

Joe then forwards a copy of the sealed document in an e-mail to another Patents workspace participant (Jennifer) who has READ privileges only. By using Oracle IRM Desktop, which she previously installed, Jennifer can save a copy of the sealed document on her computer. However Jennifer can only open and read it. She cannot modify it.

Futhermore, if Jennifer's membership in the workspace is modified, or if Joe changes the permissions associated with beehive-patent.sdoc, those changes apply to any copies of the document on Jennifer's computer. For example, copies on Jennifer's computer become inaccessible to her if any of the following occur:

  • Jennifer is removed from the workspace

  • The document is deleted from the workspace

  • The document is moved to a folder where Jennifer does not have access

  • Jennifer's Oracle Beehive account is suspended or removed (say, if she leaves the organization or company)

Overview of Integrating Oracle IRM with Oracle Beehive

The process of integrating Oracle IRM and Oracle Beehive consists of the following steps:

  1. Generate a universal unique identifier (UUID) for the Oracle IRM classification system that Oracle Beehive will use.

  2. Use beectl or Oracle Beekeeper to configure and start the Oracle Beehive Information Rights Management (IRM) Service. Configuring the IRM Service includes specifying the Oracle IRM server and other settings.

  3. Create an XML-based classification plug-in collection file and deploy it in a Java archive (.jar) on the Oracle WebLogic application server that hosts Oracle IRM.

  4. Use Oracle Beekeeper to configure one or more Oracle IRM policies and apply them to Oracle Beehive workspaces.

  5. Verify that the user accounts in Oracle Beehive match the user accounts in Oracle IRM server, and resolve any differences.

From the end-user perspective, the following steps are necessary:

  1. Install Oracle IRM Desktop on users' computers.

  2. Configure each user copy of Oracle IRM Desktop so that it points to the Oracle IRM server instance that was previously integrated with Oracle Beehive.

After completing these steps, Oracle Beehive users can upload documents to workspaces where they are sealed automatically, and then check out the sealed documents and manage them according to their permissions.

Prerequisites for Integrating Oracle IRM with Oracle Beehive

Oracle Beehive supports integration with Oracle IRM 11g. Integrating Oracle IRM with Oracle Beehive requires a strong understanding of the concepts and procedures related to managing Oracle IRM and developing applications for it.

Before integrating Oracle IRM with Oracle Beehive, verify your deployment meets the following prerequisites:

  • Both the Oracle IRM server and Oracle Beehive are installed and running

  • Oracle IRM Desktop is installed on users' computers

    Note:

    Oracle IRM Desktop is required to work with sealed documents, but it is not required for sealing documents. Oracle IRM automatically seals documents for users when they upload documents to Oracle Beehive workspaces where IRM policies have been applied.

Procedures for Integrating Oracle Beehive with Oracle IRM

The section describes the procedures for integrating Oracle Beehive with Oracle IRM, and includes the following topics:

Step 1: Generate a Universal Unique Identifier (UUID)

Generate a universal unique identifier (UUID). The UUID will be used to identify the classification plug-in collection file that you create in the steps that follow. For more information, refer to Oracle Fusion Middleware Developer's Guide for Oracle Information Rights Management Server.

Step 2: Configure and Start the Information Rights Management (IRM) Service

By default, the Information Rights Management (IRM) Service is disabled. To enable integration with Oracle IRM, configure and start the IRM Service using beectl or Oracle Beekeeper (recommended). The procedure in this section refers to Oracle Beekeeper, although you can use beectl if you're familiar with the equivalent commands and options.

To configure and start the IRM Service with Oracle Beekeeper:

  1. In the Services pane of Oracle Beekeeper (bottom left-hand side), click IrmService.

  2. Click the Configuration tab.

  3. Click Edit.

  4. Click Advanced.

  5. Modify the values for the following properties according to your deployment:

    Note:

    For more information on IRM Service properties, see "IrmService" in Oracle Beehive Administrator's Reference Guide.
    • ClassificationId

    • ClassificationLabelDescription

    • ClassificationLabelName

    • ClassificationLocale

    • ClassificationSystemId

    • ContentLabelDescription

    • ContentLabelLocale

    • ContentLabelName

    • DesktopSyncURI

    • DesktopURI

    • IrmDesktopServiceEndPoint

    • IrmSealingServiceEndPoint

    • IrmUserName

    • IrmUserPassword

    • KeysetUUID

    • LicenseExpirationTime

    • SystemLabelDescription

    • SystemLabelLocale

    • SystemLabelName

  6. From the status drop-down list, click Enable.

  7. Click Apply to apply the changes to the proposed configuration and leave the window open, or click Save & Close to apply the change and close the window.

  8. Activate your configuration. In the System panel, select Configuration. The Configuration pane appears on the right-side of the screen. The version number is displayed in the Active Configuration section.

Step 3: Create and Deploy a Classification Plug-in Collection File

After configuring and starting the IRM Service, create a classification plug-in collection file (.xml), bundle it in a Java archive (.jar), and deploy the archive on the Oracle WebLogic application server that hosts Oracle IRM.

For more information on context classification systems and collections, see the following guides:

To create and deploy a classification plug-in collection file:

  1. Create a classification plug-in collection file based on the sample provided in Appendix A, "Example of a Classification Plug-in Collection File."

  2. In the classification plug-in collection file, specify the following settings based on your deployment:

  3. Save the classification plug-in collection file as oracle_irm_classification_plugins.xml.

  4. Create a new Java archive (.jar) and include oracle_irm_classification_plugins.xml in it at the following location:

    <archive_name>/META-INF/

  5. Deploy the Java archive on the application server that hosts Oracle IRM and in the same domain as Oracle IRM. In other words, move the .jar file to the following directory:

    $WLS_HOME/<irm_domain>/lib

    where WLS_HOME is the Oracle WebLogic server home directory where Oracle IRM is running and <irm_domain> is the name of the Oracle WebLogic domain into which the Oracle IRM server was installed.

  6. Restart the application server that hosts Oracle IRM.

Step 4: Configure an Oracle IRM Policy

This section describes how to create and configure an Oracle IRM policy that seals documents in Oracle Beehive. The prerequisites are as follows:

  • An Oracle Beehive instance that is already configured to work with an Oracle IRM server

  • Administrative privileges for Oracle Beekeeper

For more information about Oracle Beehive policies, refer to Oracle Beehive Administrator's Guide.

To create and configure an Oracle IRM policy:

  1. Log into Beekeeper by using an account with ADMIN privileges.

  2. On the Enterprises pane, select Policies.

  3. Near the top of the Policies pane, select the workspace name.

    This controls the scope of the policy.

  4. Under the Policies tab, click New.

  5. In the New Policy window, select General tab.

    Provide the name and description of the policy.

  6. Select the Rules tab.

    Using the Condition Builder, specify the condition for the new policy.

    You may use such attributes as DOCUMENT_CREATED, DOCUMENT_COPIED, DOCUMENT_MOVED, and DOCUMENT_UPDATED.

    Note that Oracle supports only document events.

    For example, to seal all Microsoft Word documents, build the following condition:

    custom_attributes.document_name LIKE '%doc'

  7. Select the action Seal Document.

  8. Click Save.

  9. Click Close.

Step 5: Install and Configure Oracle IRM Desktop

This section contains the procedure for installing and configuring Oracle IRM Desktop on Microsoft Windows XP only. For more information about installing Oracle IRM Desktop, see Oracle Fusion Middleware User's Guide for Oracle Information Rights Management Desktop.

To install and configure Oracle IRM Desktop:

  1. Download the Oracle IRM Desktop installation program and save it on your computer. If you do not know the location of the Oracle IRM Desktop installation program for your deployment, contact your system administrator.

  2. Save all your work and close all Microsoft Office applications.

  3. Start the installation program.

  4. On the Welcome page, click Next.

    Click Next again.

  5. On the Oracle IRM Desktop options screen, select General tab.

    Ensure that Select all Preferences is checked.

  6. Select the Servers tab.

    Click New.

  7. On the Add Server window, enter the server URL.

    For example:

    https://irm.mycompany.com:8002/irm_desktop

  8. Click Validate.

    You may have a self-signed certificate, which you must validate or import.

  9. In the Certificate Import Wizard window, click View Certificate.

    Click Install Certificate.

  10. Click Finish.

    The desktop client prompts for your Oracle IRM Server credentials.

  11. In the Oracle IRM Server Credentials window, enter your username (your e-mail address) and password.

  12. Click OK.

  13. When the authetication completes, you can see the new server in the Oracle IRM Desktop options window in the Servers tab.

Using Documents Sealed by Oracle IRM

This section contains instructions for a subset of the tasks that you can perform with sealed documents using Oracle IRM Desktop. For more information, refer to Oracle Fusion Middleware User's Guide for Oracle Information Rights Management Desktop.

Sealing an Oracle Beehive Document

You may choose to configure a workspace-level policy to seal newly uploaded documents based on a particular condition. You may also specify folder options as a condition of a workspace policy.

For example to seal all documents that use the word patent in their name, build the following policy using the instructions in "Step 4: Configure an Oracle IRM Policy":

custom_attributes.document_name LIKE '%patent%'

Orace IRM can be used to seal all Microsoft Office format documents (with extensions .doc, .xls, .ppt, and so on), Acrobat documents (with extension .pdf), and image files (with extensions .jpg, .gif, and so on). For a complete list of supported file types and extensions, see Oracle Fusion Middleware User's Guide for Oracle Information Rights Management Desktop.

After an appropriate policy is implemented, upload a document to a folder or workspace with a defined sealing policy, and it is automatically sealed.

After a document is sealed, it replaces the original document by overwriting it.

Note that the sealing process is asynchronous and may take a few seconds to minutes depending on the size of the document and load on the system.

Note also that Oracle IRM supports manual sealing of documents, however the integration between Oracle Beehive and IRM does not because the Oracle IRM sealing capability is not exposed in the client. Therefore, documents can only be sealed using policies.

Opening a Sealed Document

After you install Oracle IRM Desktop, you may access a sealed document just like any other document, such as by double-clicking on the document icon. When you open a sealed document for the first time, you are prompted for your username and password. Enter your e-mail address, such as my.name@my.company.com, and the corresponding password. After you are authenticated, you may work with the document for sixty minutes.

The Oracle Beehive IRM Service prevents users from accessing local copies of documents that are deleted from the server. As this check occurs only once every sixty minutes (to avoid overloading the server with check requests), you may be able to access a sealed document for a short time even if the server copy is deleted.

To verify if a document exists in Oracle Beehive:

  1. In the system tray, right-click the Oracle IRM Desktop icon and select Checkin.

  2. Open the document.

    You may be prompted for your username and password.

    If the document is accessible, you can see the document content. Otherwise, you receive an Access Denied message with an explanation of why you are unable to access the document content.

Note that a sealed document is protected by Oracle Beehive workspace permissions. Therefore, if you do not have WRITE access to the document on the server, you will not be able to edit the local sealed copy. Similarly, you cannot copy the document content into another document if you do not have WRITE permissions for the document.

To summarize actions allowed based on Oracle Beehive permissions:

  • Oracle Beehive READ permission allows the actions OPEN and PRINT.

  • Oracle Beehive WRITE permission allows the actions OPEN, PRINT, EDIT, and COPY

Updating a Sealed Document

After opening a sealed document, you may edit it as you would a regular document provided you have Oracle Beehive WRITE permissions. If you have READ permissions only, then you cannot copy text from a sealed document and paste it onto another document.

After editing a document, you may save it as a sealed document. You may then upload the updated sealed document into the workspace, overwriting the older copy. A background process reseals the document with updates.

Note that if your workspace is set up with manual version management (check-in and check-out), you cannot open stale local copies of the document. You must obtain the most recent copy from the workspace to open or edit a sealed document.