Skip Headers
Oracle® Beehive Administrator's Guide
Release 1 (1.3)

Part Number E10477-07
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
View PDF

6 Managing Oracle Beehive Workspaces

Workspaces are the central focus of Oracle Beehive. The great majority of user interactions and collaboration processes take place within the context of the workspace. Every Oracle Beehive user is presented with a personal workspace, and most users will collaborate, share information, and access project resources using team workspaces. This module describes the properties of workspaces, how to create and manage workspaces, and how to manage content stored in workspaces.

This module contains the following topics:

About Workspaces

From an architectural standpoint, workspaces are containers. They fit into a hierarchy of containers in Oracle Beehive referred to as "scope", in which a single enterprise contains organizations and workspaces, with any organization containing organizations and workspaces.

From a user's perspective, however, the workspace is at the top of a different hierarchy. A workspace may contain any number of calendars, folders (containing files or messages), address books, and other entities. Each user has a private "personal workspace", and may also have access to any number of "team workspaces".

Other than users, resources, and groups, all Oracle Beehive objects are stored within a workspace - either a personal workspace, or a team workspace.

About Personal Workspaces

Every Oracle Beehive user has a single personal workspace, which acts as the container for all exposed Oracle Beehive services. The user's e-mail messages arrive in an Inbox within the personal workspace, the user's personal time management features such as calendar and task list are exposed as objects within the personal workspace, and the user can create folders and upload files to the personal workspace.

The Personal Workspace is the place where end users can see all information that is pertinent to them. E-mails and notifications are delivered to an Inbox, invitations are delivered to a personal calendar, tasks that are assigned to them or that they own are exposed in a task list. In addition, users can create folders to upload files and manage their messages, as well as manage their personal tags.

About Team Workspaces

Team workspaces are workspaces that may be created, managed, and deleted by users, and are designed for multiple users to access them and perform collaborative actions within them. Team workspaces may contain shared calendars, files and folders, tasks, address books, and other objects.

Team workspaces may be listed in the Workspace Directory, enabling them to be discovered by any user with access to the Workspace Directory. Team workspaces can be in one of two membership modes: Open Membership allows any user to join the team workspace; Invite Only ensures that a user must be added by a workspace administrator (someone with the workspace-coordinator role).

Commonly Used Commands

The following are commonly-used beectl commands related to managing workspaces:

About Workspace Properties and Controls

Workspaces have a number of required and optional properties that, together, control how they are displayed to users, and what features are enabled within the workspace. They also have a variety of controls and options available for use by the workspace users.

The workspace properties and controls are:

Locking

A user who has the workspace-coordinator role can lock a workspace. Once a workspace is locked, the workspace becomes read-only to all other members (even for other administrators). Only the person who locked the workspace (the lock owner) can modify the workspace. The locking user can optionally specify a set of users who can override the lock (and hence be able to modify the workspace or release the lock). This functionality is useful, for instance, when one or more users want to re-organize content in a workspace.

Address Books

Team workspaces may have one or more address books to manage contacts related to projects and activities within the workspace. The address book uses the workspace membership list as one of its data sources. Address books can contain Enterprise, Extended-enterprise, and External contacts. Addressable groups for workspace-scoped groups are managed by the address book functionality of the User Directory Service. Other contacts can also be created in the workspace contacts list.

See Also:

For more information about Enterprise and Extended-enterprise users, and External contacts, see "About User Accounts"

Messaging

Team workspaces are addressable entities. Messages sent to the workspace address are stored in the workspace inbox, while messages sent to the workspace members group will be sent to each member.

Announcements

Announcements are communications to the entire team, which usually have an expiration date. A user with appropriate privilege can perform the following operations on a team workspace:

All members can view announcements that are posted in the workspace. There is a default folder in team workspaces where all workspace announcements appear. Announcements are a special forum in the team workspace. Each announcement has an activation and an expiration date.

Trash

There is always a default trash folder within a workspace. A user with appropriate privileges can delete an item by moving it to the trash folder. Any deleted item will show up in the trash folder before it is explicitly purged.

When an item is moved to the trash folder, bonds between the item and other related items still exist. Traversing bonds will not work while an artifact is in the trash, but if the item is undeleted bonds will remain intact and become traversable. For example, a link or reference to a file in a different workspace stops working if that file is moved to the trash, but will work again if the file is removed from the trash.

The trash folder is read only. Items in the trash may only be read, purged or undeleted. Explicit access control on an item remains on a deleted item.

Items (documents and messages) in the trash folder count against the workspace quota until they are purged.

About Workspace Events

The workspaces service raises events for the purpose of notifications, triggering policies and workflows, and auditing. When you are creating policies, event subscriptions, or workflows related to Workspaces, use the Workspace events.

Table 6-1, "Workspace Related Business Events" shows a list of the business events related to workspaces.

See Also:

For more information about events, see "Managing Oracle Beehive Events, Policies, and Workflows".

Table 6-1 Workspace Related Business Events

Event Comments

ANNOUNCEMENT_CREATED

 

ANNOUNCEMENT_DELETED

 

ANNOUNCEMENT_READ

 

ANNOUNCEMENT_UPDATED

 

ATTACHMENT_CREATED

 

ATTACHMENT_DELETED

 

ATTACHMENT_UPDATED

 

BOND_CREATED

 

BOND_DELETED

 

BOND_UPDATED

 

CATEGORY_CLASS_CREATED

 

CATEGORY_CLASS_DELETED

 

CATEGORY_CLASS_UPDATED

 

CATEGORY_CONFIGURATION_ADDED

 

CATEGORY_CONFIGURATION_REMOVED

 

CATEGORY_CONFIGURATION_UPDATED 

 

CATEGORY_INSTANCE_APPLIED

 

CATEGORY_INSTANCE_REMOVED

 

CATEGORY_INSTANCE_UPDATED

 

ANNOUNCEMENT_CREATED

 

ANNOUNCEMENT_DELETED

 

ANNOUNCEMENT_READ

 

ANNOUNCEMENT_UPDATED

 

ATTACHMENT_CREATED

 

ATTACHMENT_DELETED

 

ATTACHMENT_UPDATED

 

BOND_CREATED

 

DOCUMENT_ARCHIVE

 

DOCUMENT_CHECK_IN

 

DOCUMENT_CHECK_OUT

 

DOCUMENT_COPIED

 

DOCUMENT_COPIED_TO_LATEST_VERSION

 

DOCUMENT_CREATED

 

DOCUMENT_DELETED

 

DOCUMENT_LOAD

 

DOCUMENT_MOVED

 

DOCUMENT_NEW_VERSION_AUTO_CREATED

 

DOCUMENT_PURGE

 

DOCUMENT_SECURITY_CONFIGURATION_ADDED

 

DOCUMENT_SECURITY_CONFIGURATION_REMOVED

 

DOCUMENT_SECURITY_CONFIGURATION_UPDATED

 

DOCUMENT_UNDELETED

 

DOCUMENT_UPDATED

 

ENTERPRISE_CREATED

 

ENTERPRISE_DELETED

 

ENTERPRISE_SECURITY_CONFIGURATION_UPDATED

 

ENTERPRISE_UPDATED

 

ENTERPRISETRASH_PURGED

 

ENTITY_LOCKED

 

ENTITY_UNLOCKED

 

FOLDER_ARCHIVE

 

FOLDER_COPIED

 

FOLDER_CREATED

 

FOLDER_DELETED

 

FOLDER_MOVED

 

FOLDER_PURGE

 

FOLDER_SECURITY_CONFIGURATION_ADDED

 

FOLDER_SECURITY_CONFIGURATION_REMOVED

 

FOLDER_SECURITY_CONFIGURATION_UPDATED

 

FOLDER_UNDELETED

 

FOLDER_UPDATED

 

FOLDER_VERSIONING_CONFIGURATION_ADDED

 

FOLDER_VERSIONING_CONFIGURATION_REMOVED

 

FOLDER_VERSIONING_CONFIGURATION_UPDATED

 

FOLDER_WORKFLOW_CONFIGURATION_ADDED

 

FOLDER_WORKFLOW_CONFIGURATION_REMOVED

 

FOLDER_WORKFLOW_CONFIGURATION_UPDATED

 

LABEL_CLASS_CREATED

 

LABEL_CLASS_DELETED

 

LABEL_CLASS_UPDATED

 

LABEL_INSTANCE_APPLIED

 

LABEL_INSTANCE_REMOVED

 

LABEL_INSTANCE_UPDATED

 

LINK_CREATED

 

LINK_DELETED

 

LINK_UPDATED

 

ORGANIZATION_CREATED

 

ORGANIZATION_DELETED

 

ORGANIZATION_SECURITY_CONFIGURATION_ADDED

 

ORGANIZATION_SECURITY_CONFIGURATION_REMOVED

 

ORGANIZATION_SECURITY_CONFIGURATION_UPDATED

 

ORGANIZATION_UPDATED

 

WORKSPACE_ARCHIVED

 

WORKSPACE_CREATED

 

WORKSPACE_HQUOTA_OVERFLOW

 

WORKSPACE_MEMBERSHIP_CHANGED

 

WORKSPACE_PURGED

 

WORKSPACE_SECURITY_CONFIGURATION_ADDED

 

WORKSPACE_SECURITY_CONFIGURATION_REMOVED

 

WORKSPACE_SECURITY_CONFIGURATION_UPDATED

 

WORKSPACE_SQUOTA_OVERFLOW

 

WORKSPACE_TRASHFOLDER_EMPTIED

 

WORKSPACE_UPDATED

 

Managing Personal Workspaces

Personal workspaces are created automatically during user account creation, according to a personal workspace template. Oracle Beehive provides a default personal workspace template, but you can modify it or create additional personal workspace templates. For instructions on working with workspace templates, see "Using Workspace Templates".

Personal workspaces are only deleted during user account deletion. Otherwise, they are undeletable.

A user may only have a single personal workspace.

If you create additional, custom personal workspace templates, the user provisioning policy determines which personal workspace template to use when creating a user account. For more information about managing policies, see Module (UNKNOWN STEP NUMBER) , "Managing Oracle Beehive Events, Policies, and Workflows". For more information about managing and provisioning users, see Module (UNKNOWN STEP NUMBER) , "Managing and Provisioning Oracle Beehive Users".

Personal workspaces can be modified using the Platform Web Services or using beectl. The following items may be modified using the beectl utility:

To modify a personal workspace, use the beectl modify_personal_workspace command:

beectl> modify_personal_workspace --workspace <Workspace identifier> --name <Workspace name> --description <Description> --hard_quota <quota> --soft_quota <quota>

Hard and soft quota values are in megabytes (MB). Use 'UNLIMITED' to set an unlimited quota size.

Using Workspace Templates

A workspace template specifies the blueprint for a workspace. A template can be used for capturing best practices and for domain-specific customizations. For example, a New Product Launch Workspace Template could specify the blueprint for creating workspaces that are suitable for collaboration among members of teams responsible for launching new products.

This section contains the following topics:

About Workspace Templates

All workspaces are always created using a template. Personal workspaces are always created using a personal workspace template, and team workspaces are always created using a team workspace template.

Templates are stored in an XML format. To review the workspace template XML format, see Module 1, "Group, Policy, Workflow and Workspace Templates" in Oracle Beehive Administrator's Reference Guide.

Oracle Beehive comes with four pre-defined workspace templates. You can list them by using the beectl list_workspace_templates command:

beectl list_workspace_templates --scope <your enterprise identifier>

This produces output similar to the following:

----------------------------------------+---------------------------------------
Name                                    | Identifier                            
----------------------------------------+---------------------------------------
Basic Personal Workspace Template       | wstp=Basic Personal Workspace Template
                                        | ,enpr=yourcompany                     
----------------------------------------+---------------------------------------
Basic Team Workspace Template           | wstp=Basic Team Workspace Template,enp
                                        | r=yourcompany                         
----------------------------------------+---------------------------------------
Community of Practice Workspace Templat | wstp=Community of Practice Workspace T
e                                       | emplate,enpr=yourcompany              
----------------------------------------+---------------------------------------
Project Workspace Template              | wstp=Project Workspace Template,enpr=y
                                        | ourcompany                            
----------------------------------------+---------------------------------------
4 Record(s) displayed.

The four workspace templates are:

  • Basic Personal Workspace Template

    The personal workspace template is designed for personal workspaces, which are used solely by individual users to view and manage all of their content and collaborative activities in one primary location, including those that fall outside the scope of their team workspaces.

    By default, workspaces that are based on the Personal workspace are not listed in the system's public workspace directory. Also, although a user may not join another user's personal workspace, users can grant view-only access to each other's personal workspaces.

  • Basic Team Workspace Template

    The basic team workspace template is designed for general use in team-based workspaces. This template provides the broadest coverage of collaborative features and options, and it is not specific to any particular type of group or function.

    By default, workspaces that are based on the basic team workspace template are listed in the system's public workspace directory, although users must receive invitations to join them.

    The basic team workspace template is the default team workspace template: if a team workspace is created without designating a template, this template will be used.

  • Community of Practice Workspace Template

    The Community of Practice workspace template is designed for workspaces where users who share common interests can post topics discussions of interest and share best practices. Workspaces that are based on the Community of Practice workspace template are listed in the system's public workspace directory and any enterprise user can join them, with or without an invitation.

    By default, the Community workspace template provides a best practices folder hierarchy for optimized content management.

  • Project Workspace Template

    The Project workspace template is designed for time-constrained or date-defined projects. This template provides the Oracle Beehive features and options that facilitate collaborative, team-based projects such as repeating status meetings and a best practices folder hierarchy for optimized management of project content.

    By default, workspaces that are based on the Project workspace template are not listed in the system's public workspace directory and members may join them by invitation only.

Workspace Template Contents

A workspace template contains specification for workspace attributes, workspace members and entities contained in the workspace. It contains the following main items:

  • Template Attributes:

    In addition to the attributes that apply to all templates, a workspace template may also have the Domain attribute. The target domain of a workspace template is the line of business (such as life sciences, CRM, and so on) in which the template is intended to be used.

  • Workspace Attributes:

    A workspace template can include the specification of values for one or more workspace attributes (such as name, description, and so on).

  • Membership Information:

    A workspace template can specify members for the new workspace. For example, a workspace template can specify that the group PROJECT_MANAGERS should be a member of all workspaces created from the template.

  • Member Subgroups:

    One or more subgroups of workspace members can be specified in a team workspace template. These subgroups can be used in the template as targets of privilege and task assignments and as meeting attendees.

  • Roles:

    A team workspace template can specify roles that can be granted to workspace members in the scope of the workspace. These roles specify privileges and access types that are granted (or denied) to an actor in the scope of the workspace.

  • Labels:

    A personal workspace template can specify one or more labels to be created for the owner of the personal workspace. For example, the default personal workspace template shipped with Oracle Beehive specifies the following two labels: Personal and Business.

  • Folder templates:

    A workspace template can include templates for the following types of folders:

    • Heterogeneous real folder (a folder for documents and messages)

    • Specialized real folder (such as a Calendar, Task List or Address Book)

    A folder template, in turn, can include templates for sub-folders. A folder template can also include templates for entities to be created in the folder. For example, a folder template can include templates for labels, policies, documents, meetings, tasks, or messages.

  • Document templates:

    A document template may optionally specify the body of the document. The body of a document is specified by reference:. a complete path name of an existing document is specified, and the content of this document is copied into the workspace at the time of template instantiation

  • Meeting (occurrence) templates:

    A meeting template specifies values for one or more attributes of an occurrence. Values of temporal attributes (such as start time) can be specified either using template variables or as offsets from workspace creation time. Meeting attendees can also be specified in the template. A meeting attendee could be any user or group in the system. In addition to ordinary meetings, templates for repeating meetings (occurrence series) can also be included in a workspace template.

  • Task templates:

    A task template specifies values for one or more attributes of a task. Values of temporal attributes (such as start time) can be specified either using user-defined template variables or as offsets from workspace creation time. Task assignees can also be specified in the template. A task assignee could be any user or group in the system.

  • Discussion forum templates:

    A discussion forum template specifies values for one or more attributes of a discussion forum. It can also include specifications for sub-forums, discussion topics and announcements.

  • Address Book templates:

    An address book template can include templates for one or more contacts

Using Expressions in Workspace Templates

Both Meeting and Task workspace templates allow you to specify multiple meetings or tasks. Oracle Beehive 1.3 and later includes a feature (the temporalExpression element) that allows you to use an expression to specify the time for an attribute (such as start time) for these meetings and tasks. Meetings or tasks can be specified relative to the set value, using a numerical expression.

For example, a consulting workgroup might routinely use a standardized set of tasks on each consulting engagement. A workspace administrator uses a custom consulting template to create a team workspace for the project. Within the template, an initial task is specified to kick-off the consulting project, and then additional, specific tasks follow on at various time intervals; a planning task that should be completed two days after the intial task, a milestone task that should be completed one week after the initial task, and so on.

You can set the start time variable for the first task. Then, using expressions, you can specify that the second task have an offset of 48 hours (two days), and the third task have an offset of 168 hours (seven days), and so on. Expressions can use the PLUS, MINUS, or PRODUCT arithmetic operators, and may use any template variable. You can establish a specific time value in a variable, and then specify offsets using the expressions. In this manner, expressions allow you to pre-set a complex arrangement of tasks and meetings in the workspace template, rather than having to re-create them by hand each time you create a new workspace.

For more details about using variables in workspace templates, see "Template Variables" in Oracle Beehive Administrator's Reference Guide.

For more details about using the expressions in workspace templates, see "Expressions" in Oracle Beehive Administrator's Reference Guide.

Modifying Workspace Templates

To modify a workspace template, first, download the workspace template to an XML file using the beectl list_workspace_templates command with the --file option:

beectl> list_workspace_templates --scope <Identifier of enterprise or organization>
--name <Workspace template name> --file <Full path of the output file>

Note:

For the --name option, you do not need to provide the workspace template's ID: just the name. Enclose names with spaces in double quotation marks.

The workspace template you specify will be downloaded to the file location and name you specify with the --file option.

Then, edit the file, and use the beectl modify_workspace_template command to upload your changes:

beectl> modify_workspace_template --template <Workspace template identifier> --file <Full path of the input file> --name <Workspace template name>

Creating a New Workspace Template

You can create a new workspace template, by writing an XML-formatted file defining the template. For complete documentation on workspace template formatting, see Module 1, "Policy, Workflow and Workspace Templates Reference" in Oracle Beehive Administrator's Reference Guide.

Then, use the beectl add_workspace_template command to upload the file, creating the new workspace template:

beectl> add_workspace_template --scope <Identifier of enterprise or organization> --file <Full path of the input file> --name <Workspace template name>

If you create a workspace template at a scope other than Enterprise scope, it will only be available for creating workspaces at that scope. Using this technique, you could create different default workspace templates for members of different organizations.

Deleting a Workspace Template

You can delete a workspace template using the beectl delete_workspace_template command:

beectl> delete_workspace_template --template <Workspace template identifier>

Note:

You should not delete the default workspace templates. You should not delete a workspace template that is used by a policy, because it could render that policy invalid in some cases.

Creating and Managing Team Workspaces

Although Oracle Beehive users can create team workspaces, you can also create and manage team workspaces from the command line.

This section contains the following topics:

Creating Team Workspaces

There are three ways to create new team workspaces: by using the Platform Web Services; by using a client which supports workspace creation, such as Oracle Beehive Integration for Outlook (OBIO); or by using the command-line. When creating with OBIO, the workspace is created in the same enterprise or organization scope as the creator's personal workspace. The default team workspace template is used.

You can create a team workspace from the command-line. Optionally, you may create an XML-formatted file which defines one or more users as members of the workspace, and assigns those users with appropriate roles. You can then upload the XML file by designating it with the --file option during creation.

Create a new team workspace by using the beectl add_team_workspace command:

beectl> add_team_workspace --scope <Identifier of enterprise or organization> --template <Workspace template identifier> --name <Workspace name> --file <Full path of the input file>

A workspace always uses a template during creation. If you do not designate a template, the default workspace template for the given scope will be used.

Example 6-1, "Adding Members to a Team Workspace During Creation" shows the formatting of the XML file you may optionally upload when creating a workspace. In this example, two users are added to a workspace, and each user is given a role. In Oracle Beehive Release 1 version 1.2 or earlier, you must specify participants and roles using the <cen> element and full CollabIDs.

Example 6-1 Adding Members to a Team Workspace During Creation

<teamWorkspaceTemplate xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xmlns='http://xmlns.oracle.com/beehive/transportabletemplate'
    xsi:schemaLocation='http://xmlns.oracle.com/beehive/transportabletemplate http://xmlns.oracle.com/beehive/transportabletemplate.xsd'>
    
    <templateAttributes> 
    </templateAttributes> 
    <body> 
        <!-- Add users -->
        <participant>
            <identity type='USER'>
                <cen>0038:6B48:user:36C1F8C16EC34206A5021B92DDC97279000000000000</cen>
            </identity>
            <role>
               <cen>0038:6B48:acrd:8B1514BAD5FC427E9AE42FB3A88664D200000000001A</cen>
            </role>
        </participant>
         <participant>
            <identity type='USER'>
                <cen>0038:6B48:user:36C1F8C16EC34206A5021B92DDC9727900000000001B</cen>
            </identity>
            <role>
               <cen>0038:6B48:acrd:8B1514BAD5FC427E9AE42FB3A88664D200000000001A</cen>
            </role>
        </participant>
</body> 
</teamWorkspaceTemplate>

In Oracle Beehive Release 1 version 1.3 or later, you can alternatively specify participants and roles using the shorter BODN identifiers:

<participant>
      <identity type="USER">
         <bodn>user=example_user1</bodn>
      </identity>
      <role>
         <bodn>acrd=test_role1,orgn=example_organization1,enpr=example.com</bodn>
      </role>
</participant>

Once you have created a team workspace, you can use the command-line to modify it, as described in "Modifying Team Workspaces".

Viewing Team Workspaces

You can view the attributes and properties of a team workspace, by using the beectl list_workspaces command:

beectl list_workspaces --scope <Identifier of enterprise or organization> --type<p|t|a> --name <Workspace name>

Provide a value for the --name option to show details of a specific workspace. Example 6-2, "Example Team Workspace" is an example of the output from such a command.

Example 6-2 Example Team Workspace

Workspace name:                         my_team_workspace
Description:                            my_team_workspace
Workspace type:                         TEAM
Identifier:                             wksp=wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Hard quota in kilo-bytes (KB):          Unlimited quota
Soft quota in kilo-bytes (KB):          Unlimited quota
Workspace parent:                       orgn=human_resources,enpr=mycompany
Workspace path:                         /MYCOMPANY/HUMAN_RESOURCES/MY_TEAM_WORKSPACE
Primary contact:                        16C3:57F2:syac:37D536448BC43F3DE040578C211A3EA80000000001CA
Default sensitivity:                    acsn=Normal,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      adbk=Contacts,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      fldr=Announcements,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      fldr=INBOX,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      fldr=Documents,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      fldr=Public Documents,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      clnd=Calendar,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      fldr=Workspace Trash,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Folder identifier:                      fldr=Tasks,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany
Workspace template identifier:          16C3:57F2:ttws:37D536448BC43F3DE040578C211A3EA80000000001D6
Is directory listed?:                   false
Default role definition:                acrd=workspace-member,enpr=mycompany
Participation mode:                     INVITE_ONLY
Workspace participant:                  loginid=jsmith    Assigned role:                      acar=workspace-coordinator,wksp=my_team_workspace,orgn=human_resources,enpr=mycompany

In this example, a workspace named "my_team_workspace" has been created using the default team workspace template. The workspace was created within the "human_resources" organization of the enterprise called "mycompany". No quota or hard quota has been set. A user has been added, with the login ID of "jsmith", and granted the role of workspace-coordinator. The workspace is set to INVITE_ONLY participation mode, and is not listed in the public directory.

Modifying Team Workspaces

Once a team workspace is created, you can modify it from the command-line to add or remove users, change its e-mail address, change its participation mode, indicate whether or not it is directory listed, and to modify the quota. You can make many other modifications to a workspace using OBIO, and the Platform Web Services.

For information about adding and removing members, see "Managing Team Workspace Membership".

To change the e-mail address of a team workspace from the command line, use the beectl modify_team_workspace command with the --email_address option:

beectl> modify_team_workspace --workspace <Workspace identifier> --email_address <Team workspace email address>

To change the participation mode of a team workspace from the command line, use the beectl modify_team_workspace command with the --participation_mode option:

beectl> modify_team_workspace --workspace <Workspace identifier> --participation_mode <Team workspace participation mode>

You can use any of the following values: INVITE_ONLY, OPEN, or APPROVE_REQUIRED

To modify the quota of a team workspace from the command line, use the beectl modify_team_workspace command with the --soft_quota or --hard_quota options:

beectl> modify_team_workspace --workspace <Workspace identifier> --hard_quota <new quota in MB> --soft_quota <new quota in MB>

To modify whether a team workspace is directory-listed from the command line, use the beectl modify_team_workspace command with the --directory_listed option:

beectl> modify_team_workspace --workspace <Workspace identifier> --directory_listed <TRUE|FALSE>

Deleting Team Workspaces

You can delete a team workspace by using the beectl delete_team_workspace command:

beectl> delete_team_workspace --workspace <Workspace identifier>

When you delete a team workspace, all artifacts stored in that workspace are also deleted.

Managing Categories

Categories are a hierarchical structure of designations that may be applied to entities, including all of the artifacts stored in a workspace. Categories always exist at the enterprise scope.

You can determine default categories available in a workspace during workspace creation: either from the workspace template, or, directly by specifying them in the XML file provided when you create the workspace.

In addition, you can create and delete categories, and you can apply and remove them from objects in workspaces. You create a category by uploading an XML formatted category definition file.

To create a new category, use the beectl add_category command:

beectl> add_category --file <path to the category XML file>

Example 6-3 shows an XML file for adding a simple category to an enterprise.

Example 6-3 Example Category XML File

<?xml version = '1.0' encoding = 'UTF-8'?>
<!-- Sample Template to add a Category -->
<CategoryDefinition xmlns="http://xmlns.oracle.com/beehive/category">
   <name>TTTesCat1->1179090518828</name>
</CategoryDefinition>

Example 6-4 shows an XML file for adding a category with attributes. An attribute has a default value, and can also have allowed alternate values.

Example 6-4 Example Category with Attributes XML File

<?xml version = '1.0' encoding = 'UTF-8'?>
<!-- Sample Template to Create a Category with Attributes -->
<CategoryDefinition xmlns="http://xmlns.oracle.com/beehive/category">
   <name>Test Category16</name>
   <description>Test Category-Desc</description>
   <abstract>T</abstract>
   <defaultTemplate>
      <copyOnVersion>T</copyOnVersion>
      <mandatory>F</mandatory>
      <finalInd>F</finalInd>
      <attributeTemplates>
         <attributeTemplate>
            <attributeDef>
               <name>AdefX1-1</name>
               <propertyType>STRING</propertyType>
            </attributeDef>
            <mandatory>F</mandatory>
            <prompted>T</prompted>
            <finalized>F</finalized>
            <forceDefault>F</forceDefault>
         </attributeTemplate>
         <attributeTemplate>
            <attributeDef>
               <name>AdefX2-1</name>
               <propertyType>STRING</propertyType>
            </attributeDef>
            <mandatory>T</mandatory>
            <finalized>F</finalized>
            <forceDefault>T</forceDefault>
            <allowedValues>
              <allowedVal>
                 <name>AL2</name>
                 <description>Desc-AL2</description>
                 <value>TestVal2</value>
              </allowedVal>
            </allowedValues>
            <defaultValue>
              <value>
                TestVal2
              </value>
            </defaultValue>
         </attributeTemplate>
      </attributeTemplates>
   </defaultTemplate>
  <attributes>
      <attribute>
         <name>AdefX1-1</name>
         <description>TestAdef1</description>
         <propertyType>STRING</propertyType>
         <searchable>T</searchable>
         <defaultValue>
           <value>
             TestVal1-Def
           </value>
         </defaultValue>
      </attribute>
      <attribute>
         <name>AdefX2-1</name>
         <description>TestAdef2</description>
         <propertyType>STRING</propertyType>
         <searchable>F</searchable>
         <defaultValue>
           <value>
             TestVal2
           </value>
         </defaultValue>
         <allowedValues>
              <allowedVal>
                 <name>AL1</name>
                 <description>Desc-AL1</description>
                 <value>11</value>
              </allowedVal>
              <allowedVal>
                 <name>AL2</name>
                 <description>Desc-AL2</description>
                 <value>TestVal2</value>
              </allowedVal>
            </allowedValues>
      </attribute>
   </attributes>
</CategoryDefinition>

To delete a category, use the beectl delete_category command:

beectl> delete_category --category <Identifier of the category to be deleted>

Note:

When you delete a category, all applications of that category are automatically removed.

To apply a category to an entity in a workspace, use the beectl add_category_application command:

beectl> add_category_application --category <Identifier of the category to be applied> -- entity <Identifier of the entity to which the category needs to be applied>

To remove a category from an entity in a workspace, use the beectl delete_category_application command:

beectl> delete_category_application --category <Identifier of the category to be removed> --entity <Identifier of the entity from which the category needs to be removed>

Managing Team Workspace Membership

You can add members to a team workspace during creation by formatting an XML file for upload. In the file, you specify any number of users (and groups) to be members of the team workspace. You can also specify roles for the users. At least one user of any team workspace should have the workspace-coordinator role.

To view a list of all of the available roles, use the beectl list_role_definitions command:

beectl> list_role_definitions

For a list of team workspace-related roles, see Table 6-2, "Summary of Default Team Workspace Roles".

Example 6-5, "Sample Team Workspace Adding Members XML File" is an example file, showing two members to be added to a workspace; each member is granted a role, by pasting in the CollabID of a role in the <cen> element.

Example 6-5 Sample Team Workspace Adding Members XML File

<teamWorkspaceTemplate xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xmlns='http://xmlns.oracle.com/beehive/transportabletemplate'
    xsi:schemaLocation='http://xmlns.oracle.com/beehive/transportabletemplate http://xmlns.oracle.com/beehive/transportabletemplate.xsd'>
    
    <templateAttributes> 
    </templateAttributes> 
    <body> 
        <participant>
            <identity type='USER'>
                <cen>0038:6B48:user:36C1F8C16EC34206A5021B92DDC97279000000000000</cen>
            </identity>
            <role>
               <cen>0038:6B48:acrd:8B1514BAD5FC427E9AE42FB3A88664D200000000001A</cen>
            </role>
        </participant>
         <participant>
            <identity type='USER'>
                <cen>0038:6B48:user:36C1F8C16EC34206A5021B92DDC9727900000000001B</cen>
            </identity>
            <role>
               <cen>0038:6B48:acrd:8B1514BAD5FC427E9AE42FB3A88664D200000000001A</cen>
            </role>
        </participant>
</body> 
</teamWorkspaceTemplate>

You can add, modify, and remove members from an existing workspace, by using the beectl modify_team_workspace command. You will need the unique workspace identifier as well as the unique IDs of any users you will add, modify or remove from the workspace. (In this context, modifying the user only means modifying a user's role; you do not actually modify user accounts when managing team workspaces.)

To add a user (or a group):

beectl> modify_team_workspace --workspace <workspace identifier> --add_participant <user or group identifier> --role <workspace role>

For example:

beectl> modify_team_workspace --workspace wksp=our_project,orgn=human_resources,enpr=mycompany --add_participant loginid=jsmith --role acrd=workspace-coordinator,enpr=mycompany

In this example, a user with the ID of "jsmith" is added to a team workspace called "our_project", which is in the organization called "human_resources", and granted the role of workspace-coordinator.

To remove a user (or a group):

beectl> modify_team_workspace --workspace <workspace identifier> --remove_participant <user ID>

Managing Team Workspace Access Control

In addition to explicit access control (using Access Control Entities to explicitly allow or disallow levels of access on objects), there are two methods for general control of access to entities in workspaces: roles, and sensitivities.

You can also manage the visibility of workspaces (and the content within them) to users in the enterprise who are not already members of the workspace.

This section contains the following topics:

See Also:

For complete instructions on managing access control, see Module (UNKNOWN STEP NUMBER) , "Managing Oracle Beehive Access Control".

Managing Team Workspace Visibility

Team workspaces have an attribute called participation mode. It may be set to either INVITE_ONLY, or OPEN.

By default, users can join a team workspace by invitation only: a workspace membership coordinator can make them workspace members. This is defined as the invite-only membership mode.

In addition, a team workspace may be listed in the Workspace Directory for other users to see (discover) and join.

An artifact (folder, file, calendar, event, task, and so on) can be visible to users outside the workspace by setting the Public sensitivity on the artifact.

All actors who have appropriate permissions to browse the workspace directory may find workspaces of interest and can join (if Open Membership) or request membership (with an automated e-mail message that is sent to the workspace's primary contact).

Note:

The fact that a team workspace is listed in the Workspace Directory is unrelated to whether or not any content in the workspace is granted the Public sensitivity. See "Managing Team Workspace Sensitivities" for details.

Managing Team Workspace Roles

Within team workspaces, roles are used to define levels of control which workspace members may exercise over the workspace and its content.

Users with sufficient administrative privileges can perform the following administrative operations on a team workspace:

  • Make a user or a group member of the workspace. When a group is added as a member of a workspace, the group membership is honored dynamically. This means any new member of the group automatically becomes a member of the workspace (via the group).

  • Remove an existing member. When removing a member, option exists whether to revoke all the permissions that have been granted to the user for this workspace

  • Change the roles/permissions of a member

  • Invite the contacts, including enterprise users and extended-enterprise users, to become members

  • Remove himself or herself from the workspace

Users can perform the following read operations on a team workspace:

  • View the members of a workspace

  • Retrieve the workspace membership information of a specific user or group

Table 6-2, "Summary of Default Team Workspace Roles" shows the roles and granted privileges related to team workspaces.

Table 6-2 Summary of Default Team Workspace Roles

Role Granted Privileges Granted Access Types

workspace-coordinator

[ADDRESS_BOOK_MGR, CALENDAR_MGR, CONF_MGR, CONTENT_MGR, EMAIL_MGR, FORUM_MGR, IM_MGR, MARKER_MGR, MODIFY_ACL, NOTIFICATION_MGR, POLICY_MGR, PREFERENCE_MGR, READALL, ROLE_MGR, SECURITY, SUBSCRIPTION_MGR, USER_MGR, VERSION_MGR, WORKFLOW_MGR, WORKSPACE_MGR

discover, read, write, execute, delete

workspace-participant-coordinator

MODIFY_ACL, ROLE_MGR, USER_MGR

read, discover

workspace-document-coordinator

CONTENT_MGR, FORUM_MGR, MARKER_MGR, MODIFY_ACL, VERSION_MGR, WORKFLOW_MGR

discover, read, write, execute, delete

workspace-viewer

none

discover, read

workspace-member

none

discover, read, write, execute, delete


The workspace-participant-coordinator role grants the ROLE_MGR privilege, which allows the creation and management of custom roles, within the scope of the workspace. In addition, ROLE_MGR allows the user to grant and revoke workspace-scoped custom roles to and from other users in the workspace.

In addition to the workspace roles, there are application-level roles which grant privileges over all workspaces. These roles are summarized in Table 6-3, "Summary of Default Application-Level Roles".

Table 6-3 Summary of Default Application-Level Roles

Role Granted Privileges Granted Access Types

enterprise-administrator

ARCHIVE_MGR, EXCEED_QUOTA, MARKER_MGR, ORGANIZATION_MGR, PREFERENCE_MGR, QUOTA_MGR, ROLE_MGR, USER_MGR, VERSION_MGR, WORKSPACE_MGR

discover, read, write, execute, delete

enterprise-system

BYPASS

discover, read, write, execute, delete


Managing Team Workspace Sensitivities

Sensitivities are unassigned access control lists, packaged and given a name. Users with appropriate privileges may assign sensitivities to entities under their control. This allows users to manage access control over entities without needing to learn about or understand how access control works in detail.

The default personal workspace creates two sensitivities: public and private.

You can define sensitivities during workspace creation, by specifying them in the workspace template.

For detailed information about creating and managing sensitivities, see "Creating and Managing Sensitivities" in Module (UNKNOWN STEP NUMBER) , "Managing Oracle Beehive Access Control".

Managing Files

Workspace users can create heterogeneous folders (entity real folders) and sub folders within any workspace to manage artifacts, including "library content" (documents, URLs, notes, and links), topics and messages (e-mails, discussions, voice mail messages, fax messages), IM chat logs, calendar events, tasks, and contacts.

Some of these folders can contain artifacts that may be stored in external file system directories, or accessed over FTP and WebDAV protocols.

This section contains the following topics:

Managing File System Directories

In Oracle Beehive, by default all user content is stored in the database. However, you may elect to store some content in file system directories. A file stored in a file system directory is treated as read-only by Oracle Beehive.

Whenever a user or process performs a read action on the file, the file is read from the file system directory.

At any time, if changes are made to the file in Oracle Beehive, such as if a user modifies the file content, the file is imported from the file system directory into the Oracle Beehive database. The unchanged, original file remains in the file system directory, but Oracle Beehive stores the new file in the database, and will continue to make use of only the database copy of the file.

Note:

This functionality allows you to expose your existing documents and files to Oracle Beehive users without having to perform a batch-import of all files to the Oracle Beehive database. Instead, map your files using the file system reference commands, and individual files will be automatically imported only as needed.

You can use the following beectl commands to manage file system directories and files:

  • add_filesystem_reference: Creates a reference in Oracle Beehive to a directory on the file system

  • delete_filesystem_reference: Removes a file system reference from Oracle Beehive

  • import_documents: Imports documents into Oracle Beehive from files on the server without copying the file content. Data on the server files will be treated as read-only; should an imported document be edited in Oracle Beehive, a copy of the content will be made at that time.

  • list_filesystem_references: Lists the file system path, read-only status, and identifier (CollabID) of all available file system references.

To map existing files to Oracle Beehive, perform the following steps:

  1. Use the beectl add_filesystem_reference command to map an existing server path for Oracle Beehive:

    beectl> add_filesystem_reference --name <Filesystem reference name> --filesystem_path <Server path> --read_only <true or false>
    

    Note:

    If you set the --read_only flag to true, Oracle Beehive will treat the file objects as read-only internally, meaning, users will not be allowed to modify them. If you set it to false, users will be allowed to modify the files, which will trigger the file importation into the Oracle Beehive database.

    Under no conditions will files on the file system be modified by Oracle Beehive.

  2. Use the beectl import_documents command to create individual references to all of the documents within Oracle Beehive:

    beectl> import_documents --filesystem_reference_id <CollabId of the filesystem reference> --folder_path <Folder path> [--name_filter <name filter>] [--conflict_res_mode <ABORT|OVERWRITE|CREATE_UNIQUE>]
    

    The --folder_path specifies the folder path within Oracle Beehive to import the files. For example, you could specify a folder within a specific workspace.

    The --name_filter option allows you to specify only a subset of the files in the file system directory to be imported. For example, you could specify the filter %.doc to only import files with the .doc extension.

    the --conflict_res_mode determines how Oracle Beehive should treat files to be imported from the file system directory, when a file already exists in the target Oracle Beehive directory with the same name. You may choose to skip such files with the ABORT option, overwrite them, or create a new, unique file name for the file automatically.

You can also manage existing file system directories by listing them and deleting them.

To list all file system directories currently mapped in Oracle Beehive, use the beectl list_filesystem_references command:

beectl> list_filesystem_references

To delete a file system reference, use the beectl delete_filesystem_reference command:

beectl> delete_filesystem_reference --filesystem_reference_id <CollabID>

When you delete a file system reference, any files currently linked-to that have not been imported into the Oracle Beehive database become unavailable. Files already imported into the Oracle Beehive database remain available and are treated as normal files.

Managing FTP and WebDAV Access to Files

Content stored in workspaces may be made available to users over FTP and WebDAV protocols. FTP access is controlled by the FTP Service, and WebDAV access is controlled by the WebDAV service. When these protocols are enabled, users with supported clients can authenticate with Oracle Beehive, and then access files stored in any workspace with which they have sufficient privileges. In all respects, access via FTP and WebDAV is treated the same as access from any other user client; explicit and implicit access control is respected. User actions over these protocols are restricted to uploading, moving, and downloading files, and creating, moving, and deleting folders. Users cannot apply or change sensitivities or categories on files through these protocols.

For information about how to configure and enable FTP and WebDAV, see "Managing Oracle Beehive Services".

Managing Records Management

Records Management is an optional service, which is enabled by installing and configuring Oracle Beehive with Oracle Universal Record Manager (URM). URM provides lifecycle and disposition management of record-managed Oracle Beehive artifacts. Once URM is installed and configured with Oracle Beehive, you can start the Records Management Service, and begin recordizing documents and e-mails.

Oracle Beehive manages records in place. In-place means that Oracle Beehive retains the recordized artifiact within the Oracle Beehive database, but treats it specially.

When an artifact becomes record managed in-place, Oracle Beehive ensures that the content is never truly altered or deleted from the system until a URM action is issued. From an end-user perspective, users are able to 'delete' emails or documents that are record managed, and empty them from the Workspace Trash.

Those record managed artifacts are then stored in a special Record Management container in the Oracle Beehive database. The URM application can still query for and perform operations on such stored artifacts.

Artifacts can be placed under retention, which means that they can be treated as regular artifacts by Oracle Beehive. However,

Artifacts can also be "record-managed" without being placed under retention. These types of records are called non-records (as a short form of "non-retained records"). Non-records can be treated as regular artifacts (including being modified or deleted) by Oracle Beehive. URM will send an instruction to Oracle Beehive when it is time to handle non-record artifacts if they still exist in the system.

In Oracle Beehive Release 1 (1.2), you can create records of:

As an administrator, you can manually recordize these artifacts using a beectl command. Additionally, you can create policies to automatically recordize documents and e-mails based on triggering criteria.

Whenever a document or e-mail is recordized, metadata about the artifact is sent to URM. The metadata describes the artifact and its original context. The artifact itself continues to be stored in Oracle Beehive, which ensures that the content is immutable from a system perspective (unless it is a non-record). Table 6-4 lists the document metadata sent to URM with all artifacts. Table 6-5 lists the metadata also sent to URM when e-mail messages are recordized.

Table 6-4 Artifact Metadata Sent to URM with All Artifacts

Name Type

CollabID

String

Creator Name

String

Artifact URLFoot 1 

String

Media Type

String

Creation Date

Date in "MM/DD/YY" format


Footnote 1 Documents only. E-mail messages are not accessible via a URL.

Table 6-5 Artifact Metadata Sent to URM with E-Mail Messages

Name Type

Sender

String

Sent Date

Date in "MM/DD/YY" format

Subject

String

Hidden Addresses

String, comma delimited list of addresses

Primary Addresses

String, comma delimited list of addresses

Secondary Addresses

String, comma delimited list of addresses


This section contains the following topics:

Configuring Oracle Universal Records Management

This section describes the steps required to enable the Records Management Service in Oracle Beehive. Oracle Beehive Release 1 (1.2) should already be installed.

Oracle Beehive Records Management requires an existing installation of Oracle Universal Records Management 10g Release 3 (10.1.3) or higher. URM itself requires an Apache Web server.

See Also:

For detailed instructions on installing and configuring Oracle Universal Records Management, see the Universal Records Manager Installation Guide

After installing URM, to configure URM with Oracle Beehive, perform the procedures in each of the following sections, in order:

  1. Registering URM in Oracle Beehive

  2. Creating Retention Categories and Record Folders in URM

  3. Setting Up Disposition Rules in URM

Registering URM in Oracle Beehive

Perform the following steps to register URM in Oracle Beehive:

  1. Ensure the Records Management Admin user in URM (typically the sysadmin account) is granted all possible roles:

    1. Log in to URM

    2. Click Admin Applets

    3. Click User Admin

    4. Select the Admin user (sysadmin) and click Edit

    5. Add the following roles: rma, rmaadmin, admin, ermadmin, ermrequestor, rmaprivileged, sysmanager

    6. Save and exit

    Note:

    The Oracle Beehive Records Management Service uses this account to connect to URM using Web Services. These values must be updated and the Records Management Service restarted should these values change in URM. Use the beectl modify_property command to update these values.
  2. By default, the Records Management service is not deployed when you install Oracle Beehive. Deploy the Records Management service by using the beectl add_service_configuration command:

    ./beectl add_service_configuration --archive $ORACLE_HOME/beehive/seed/services/APP/rm-service.ear --oc4j_instance_name BEEAPP
    

    Note:

    The add_service_configuration command shown must be issued from the operating system command line, and not from beectl shell mode.
  3. Use the beectl add_urm command to update the values of the URM system object in Oracle Beehive:

    ./beectl add_urm --rm_admin_name name <URM Admin User, like sysadmin> --rm_admin_password <URM Admin Password> --urm_url <URL to connect with URM> --agent_name <Unique Agent Name for communication between Oracle Beehive and URM>
    

    Note:

    The add_urm command shown must be issued from the operating system command line, and not from beectl shell mode.

    The URL required by the adapter to communicate with the URM server varies depending on certain URM install options (instance name and server name). The URL can be obtained from any URL to the URM server on the Web interface. Discard everything after Ò?Ó. For example, if service requests on the Web interface are of the form:

    http://yourcompany.stellent.com/xpedio/idcplg?IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=HOME_PAGE&Auth=Internet
    

    You can find the service URL by taking the first part of any service URL string. In this case, it is http://yourcompany.stellent.com/xpedio/idcplg.

    The agent name can be any meaningful name that indicates that this agent is for the Oracle Beehive Records Management Service. For example, "BeeAdapter" or "BeehiveRMAdapter".

  4. Use the beectl activate_configuration command to update Oracle Beehive with this proposed configuration:

    beectl> activate_configuration
    
  5. 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.

  6. If you intend to use Policies to recordize documents, you must manually add the Records Management Java action, using the following beectl add_policy_action command:

    beectl> add_policy_action --name RMJavaAction  --type JAVA --action_string oracle.ocs.management.model.RecordsManagementService:RECORDIZE --description "Recordization Action"
    

Creating Retention Categories and Record Folders in URM

As the next step, log in to Oracle URM using a Records Management administrator account. Create the various Retention Categories and Record Folders as required by your organization.

To create Retention Categories and Record Folders, perform the following steps:

  1. Create retention categories under Record Series or under File plan in the Oracle URM user interface.

    To create a retention category under a file plan, click Create and select Retention Category.

    To create a retention category under a record series, click a record series, then click Create and select Retention Category.

    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 check box is checked, the retention category will allow non-records to be checked in.

    Note:

    Non-Records are artifacts that respect Disposition Rules but have no content modification or deletion restrictions.
  2. Create Record Folders under a retention category or under another record folder.

    To create a record folder under a retention category, click a retention category, click Create, and select Record Folder.

    Record folders can be nested, so you can create a record folder within another record folder. To create a record folder within another record folder, open a record folder, click Create, and select Record Folder.

    For each new record folder, fill in the values required on the creation page. Provide a unique record folder ID.

Once retention categories and record folders are created in Oracle URM, they may be viewed from Oracle Beehive using the beectl list_file_plan command:

beectl> list_file_plan

Setting Up Disposition Rules in URM

Disposition rules are set on Retention Categories only.

In Oracle Beehive Release 1 (1.2), the Records Management Service supports only the "DESTROY" disposition action.

Perform the following procedure to set up disposition rules for testing:

  1. Using the Oracle URM user interface, on the retention category page, select the Information drop-down list and click Disposition Information

  2. On the Disposition Instruction page, click the Add link. A Disposition Rule panel is displayed

  3. On the Disposition Rule panel:

    1. 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

    2. Specify a retention period. For Oracle Beehive Records Management disposition tests, set the retention period to be zero weeks

    3. Choose Disposition Action to be Destroy

      Note:

      In Oracle Beehive Release 1 (1.2), only Destroy commands are supported. Archive, transfer, and accession commands will be available in future versions of Oracle Beehive.
    4. Leave the Destination Location and Destination Container blank

    5. Set values for Apply to Records Folder and Notification Reviewer. By default, the Notification Reviewer is sysadmin

  4. After filing a record, you must manually click Actions, select Trigger Dates, and select Cancel on the record from Oracle URM. This will trigger a cancel action and starts disposition processing in Oracle URM.

Recordizing Artifacts in Oracle Beehive

You can manually recordize artifacts (documents and e-mails) using beectl commands.

You can file records automatically using policies.

Each of these procedures is detailed in the following sections:

Recordizing Artifacts using beectl

The command-line based record filing is provided primarily as a tool for system administrators to manually file records that were not recordized using a policy action. You can recordize an e-mail or document using the beectl add_record command:

beectl> add_record --artifact <identifier of the artifact to be filed as a record or non-record> { --retention_category <identifier of the URM retention category> | --record_folder <identifier of the URM record folder> } [ --no_retention <boolean specifying a record or non-record> ]

You must supply an identifier for the artifact you want to recordize.

Specify a Retention Category or Record Folder. You can view a list of record categories and record folders, along with their identifiers, using the beectl list_file_plan command:

beectl> list_file_plan

Recordizing Artifacts using Policies

You can make use of the Oracle Beehive policy framework to create record management policies. Record management policies automate the process of recordizing artifacts. You specify a policy condition for recordization, and a destination Retention Category. Artifacts that meet the policy condition are automatically recordized by Oracle Beehive.

Note:

The record management policy action must be manually created during setup in order to use polices for recordization. Be sure to perform step 6 in the procedure in "Registering URM in Oracle Beehive".

To set up a record management policy, perform the following steps:

  1. Select a Retention Category for this policy. All records that meet this policy's condition will be recordized into that Retention Category. You can list available Retention Categories using the beectl list_file_plan command:

    beectl> list_file_plan
    
  2. Create an Oracle Beehive policy XML file, using the special Records Management policy action, and setting the actionPreferenceInfo, as in the following example:

    .
    .
    .
          <ActionInfo>
            <name>RMJavaAction</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

  3. 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, see "Creating and Managing Custom Policies"
  4. Create the policy by using the beectl add_policy command:

    beectl> add_policy --file <full path to the policy xml file>
    

Example 6-6 shows an example of a typical Records Management policy. In this example, any file uploaded to a specified folder will be recordized with the Retention Category called LC.

Example 6-6 Sample Records Management Policy XML File

<?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>RMJavaAction</name>
      </ActionInfo>
       <ActionPreferenceInfos>
            <actionPreferenceInfo>
               <key>category_id</key>
               <value>LC</value>
            </actionPreferenceInfo>
         </ActionPreferenceInfos>
</RuleInfo>
  </RuleInfos>
</PolicyInfo>

Un-Recordizing Artifacts in Oracle Beehive

Filing an artifact as a record makes it immutable as long as it is under records management control. This means that no Oracle Beehive command or action will delete the artifact.

Caution:

The beectl delete_record command cannot be reversed or undone.

You must have the RECORDS_MGR privilege in order to un-recordize an artifact.

To unrecordize an existing record (artifact), use the beectl delete_record command:

beectl> delete_record --artifact <identifier of the artifact to be deleted as a record/non-record>

Note:

The beectl delete_record command does not delete the artifact from Oracle Beehive. Instead, it removes the designation of that artifact as a record, allowing it to be handled normally (including being deleted) by other Oracle Beehive operations.

If the artifact is in the Record Store and it is being unrecordized, it will be removed from system. This is because only those recordized artifacts that have been deleted and purged by users are placed in the Record Store. Once unrecordized, the previous action of deleting the artifact becomes complete.

Troubleshooting Records Management Service Operations

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, contact your Oracle support representative.

This section contains the following topics:

Recordization Failed

Use the following steps as guidelines for troubleshooting cases where a recordization of an artifact failed to occur:

  • If a policy-based recordization failed, check the following:

    1. Check to see if the policy was successfully registered, using the beectl list_policies command. If your policy is not listed, it has not been created in Oracle Beehive

    2. Check that the policy was created at the correct scope and for the correct operation (event). Review the policy XML file for the scope and event attributes, ensuring there are no errors

    3. Try creating a policy with the same triggering conditions and scope, but with a general (non-Recordization) action. You can test to see if this policy successfully runs when the triggering event occurs

  • 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 URM as sysadmin

  • Review the log files for the BEEAPP component, to see if the RM 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 RM Event Action, 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 messages stored to to event processing failures

  • Log in to URM as sysadmin. Select Browse Content and Search for Records filed under the name of the Adapter that was used when you registered URM with Oracle Beehive. Try to locate the document or e-mail CollabID you are trying to recordize, 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 recordization 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

Un-Recordization Failed

Typically, un-recordization 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 un-recordization of an artifact 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 URM as sysadmin

Disposition Not Processed

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

URM Login, Password, or URL Incorrect or Changed

During the procedure outlined in "Registering URM in Oracle Beehive", if the beectl add_urm command was specified with incorrect --rm_admin_name, --rm_admin_password, or --urm_url, or if these values change (such as if you change the URM admin password), you can use the beectl modify_property command to change the values:

beectl> modify_property --component <component id of the URM connector created with the add_urm command> --name <property name> --value <new value>

You can find the component ID by using the beectl list_components command:

beectl> list_components --type StellentUrm

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

Configuring URM for Dispositions Testing

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:

  1. From the Oracle URM administrator UI, click Administration, select Configure Records Management, choose the Audit tab, and select Checked-in Audit Entries

  2. On the option screen that opens, click the link for Default Metadata for Checked-in Audit Entries

  3. 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

  4. Select a retention category, and the system will list records checked in under this retention category by a given agent

  5. Choose a few documents, click Actions, select trigger dates, and select Cancel

  6. 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

  7. Click My Content Server and selectMy Records Assignments. All dispositions that are due will show up on the list

  8. For a given disposition, use the actions icon on the right side of the screen to approve it. Once you do that, the disposition will be a pending completion. You can see the disposition by clicking the Pending Completion tab and choosing My Completed Option for the external source. At this point the disposition is approved and will show up as a pending disposition for the Oracle Beehive adapter.

Example Workspace Template Contents

Example 6-7, "Example Workspace Template XML File" shows an example workspace template XML file (in this case, the Community of Practice Workspace template:

Example 6-7 Example Workspace Template XML File

<teamWorkspaceTemplate
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns="http://xmlns.oracle.com/beehive/transportabletemplate"
 xsi:schemaLocation="http://xmlns.oracle.com/beehive/transportabletemplate http://xmlns.oracle.com/beehive/transportabletemplate.xsd">
<templateAttributes>
<author>Oracle</author>
<authorCreationTime>2007-08-12</authorCreationTime>
<contactInfo>Oracle Corporation</contactInfo>
<copyrightInfo>Copyright (c) 2007 Oracle Corporation. All rights reserved.</copyrightInfo>
<description>template for creating a workspace that can serve as a place for individuals who share common interests to post interesting discussions and share best practices</description>
<name>Community of Practice Workspace Template</name>
<templateId>oracle.com.community-of-practice-workspace-template</templateId>
<domain>general</domain>
</templateAttributes>
  <templateVariable>
   <name>default-announcement-body</name>
   <description>starting instructions for workspace members</description>
  </templateVariable>
<body>
   <publicSensitivityTemplateBodyId>public_sensitivity</publicSensitivityTemplateBodyId>
   <defaultSensitivityTemplateBodyId>default_sensitivity</defaultSensitivityTemplateBodyId>
  <attributes>
     <name prompt="true" promptMessage="enter workspace name">workspace name</name>
     <description>enter project description here</description>
     <publiclyListed>T</publiclyListed>
     <participationMode>OPEN</participationMode>
  </attributes>
  <sensitivity id="default_sensitivity">
      <name>Normal</name>
      <description>normal sensitivity</description>
      <sensitivityOnly>false</sensitivityOnly>
      <delegatable>true</delegatable>
      <ace>
          <grantAccessType>DISCOVER</grantAccessType>
          <accessor type="GROUP"><systemDefinedGroupName>ALL_USERS</systemDefinedGroupName></accessor>
      </ace>
  </sensitivity>
  <sensitivity id="public_sensitivity">
      <name>Public</name>
      <description>public sensitivity</description>
      <sensitivityOnly>false</sensitivityOnly>
      <delegatable>true</delegatable>
      <ace>
          <grantAccessType>DISCOVER</grantAccessType>
          <grantAccessType>READ</grantAccessType>
          <accessor type="GROUP"><systemDefinedGroupName>ALL_USERS</systemDefinedGroupName></accessor>
      </ace>
  </sensitivity>
  <defaultAnnouncementsForum id="default_ann_forum">
     <name>Announcements</name>
     <description>forum for workspace announcements</description>
        <announcement>
           <subject>welcome to workspace ${sys.workspace.name}</subject>
           <messageBody>
              <mediaType>text/plain</mediaType>
              <body>${default-announcement-body}</body>
           </messageBody>
        </announcement>
  </defaultAnnouncementsForum>
  <defaultAddressBook id="default_address_book">
     <name>Contacts</name>
     <description>workspace address book</description>
  </defaultAddressBook>
  <defaultCalendar id="default_calendar">
     <name>Calendar</name>
     <description>workspace calendar</description>
  </defaultCalendar>
  <defaultEmailInbox id="inbox_folder">
     <name>INBOX</name>
     <description>inbox for email messages</description>
  </defaultEmailInbox>
  <defaultTaskList id="default_task_list">
     <name>Tasks</name>
     <description>workspace tasks</description>
  </defaultTaskList>
  <entities>
     <folder id="documents_folder">
        <name>Documents</name>
        <description>folder for workspace documents</description>
        <entities>
           <folder>
              <name>Best Practices</name>
              <description>folder for best practice documents</description>
           </folder>
        </entities>
     </folder>
     <folder id="public_documents_folder">
        <name>Public Documents</name>
        <description>folder for workspace documents</description>
        <ace>
           <grantAccessType>READ</grantAccessType>
           <accessor type="GROUP"><systemDefinedGroupName>ALL_USERS</systemDefinedGroupName></accessor>
        </ace>
     </folder>
     <forum>
        <name>Best Practices</name>
        <description>forum for discussing best practices</description>
     </forum>
  </entities>
  <summary>
     <inlineSummary>
        <fileName>summary.html</fileName>
        <mediaType>text/html</mediaType>
        <body> &lt;title&gt; Workspace Summary for Members &lt;/title&gt;
               &lt;b&gt; ${sys.workspace.name} &lt;/b&gt;
               &lt;p&gt;The Workspace Coordinator should edit this text to share private information about this workspace with the workspace members.  For example, add a little text here describing workspace goals and member etiquette. &lt;/p&gt;
        </body>
     </inlineSummary>
  </summary>
  <publicSummary>
     <inlineSummary>
        <fileName>publicSummary.html</fileName>
        <mediaType>text/html</mediaType>
        <body> &lt;title&gt; Workspace Public Summary &lt;/title&gt;
               &lt;b&gt; ${sys.workspace.name} &lt;/b&gt;
               &lt;p&gt; The Workspace Coordinator should edit this text to share public information about this workspace with others in your company.  For example, add a little text here describing the purpose of this workspace. &lt;/p&gt;
        </body>
     </inlineSummary>
  </publicSummary>
</body>
</teamWorkspaceTemplate>