Oracle® Beehive Administrator's Guide Release 1 (1.4) Part Number E13797-02 |
|
|
View PDF |
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:
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
commands related to managing workspaces:beectl
list_categories
: Lists the categories in the enterprise. If the recurse option is used then sub-categories are also listed.
list_category
: Prints information about a category given a category identifier
add_category
: Creates a category at the enterprise scope
add_category_application
: Applies a category on a given entity
delete_category
: Deletes a category and all category applications
delete_category_application
: Removes a category from an entity
download_workspace_template_schema
: Downloads workspace template XML schema to a file
list_workspace_templates
: Lists all workspace templates
add_workspace_template
: Creates a workspace template in an organization or enterprise
modify_workspace_template
: Modifies an existing workspace template
delete_workspace_template
: Deletes an existing workspace template
list_workspaces
: Lists workspaces in an organization or enterprise
add_team_workspace
: Creates a team workspace from a template
modify_team_workspace
: Modifies an existing team workspace
delete_team_workspace
: Deletes an existing team workspace
modify_personal_workspace
: Modifies an existing personal workspace
add_sensitivity
: Creates a Sensitivity entity
list_sensitivities
: Lists Sensitivity entities
modify_sensitivity
: Modifies an existing Sensitivity entity
delete_sensitivity
: Deletes a Sensitivity entity
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:
Display Name: A plain text name for the team workspace. Display names of workspaces must be globally unique across the enterprise, and must not duplicate the names of organizations within the enterprise
Description: Optionally, a description of the workspace. By default it will be the same as the display name
Primary Contact: The user who should be contacted when workspace actions need to be taken, such as when a user requests to join the workspace. For team workspaces, the primary contact should usually be the person with the workspace-coordinator role
Summary: A URL that points to a document that exists within the workspace and that provides additional details about the workspace. The document to which the Summary property points is private and can only be viewed by workspace members
Public Summary: A URL that points to a document that exists outside of the workspace and that provides additional details about the workspace. The document to which the Public Summary property points is public and can be viewed by all users in an enterprise
Categories: Categories can be assigned to a team workspace just as they can be assigned to other artifacts within Oracle Beehive
Default role for new members: For team workspaces, the default workspace-scoped role is assigned to new members whenever they join or are added to the workspace. A workspace-coordinator or workspace-participant-coordinator can optionally assign a different role when adding a new user
Directory listed status: Whether the team workspace is listed in the public directory (true or false). Personal workspaces are not listed in the directory
Participation mode: Whether users may join a team workspace, or must be invited first (open, or invite only). Personal workspaces do not have the participation mode property
Soft Quota: The soft quota defines a threshold at which a warning is given that quota is being exceeded. This value is set in KB, but may be left open (unbounded)
Hard Quota: The hard quota defines a maximum consumption of space by quota-consuming artifacts in the team workspace. In Oracle Beehive, documents and messages are the only quota-consuming artifacts. Once the hard quota is reached, no further quota-consuming artifacts may be added. A hard-quota-exceeded error message will be given whenever an attempt is made to exceed the hard quota. This value is set in KB, and if set, must be equal to or greater than the soft quota, or it may be left open (unbounded). If the hard quota is unbounded, the workspace may consume as much storage as has been allocated to its parent scope (its parent organization or enterprise)
Default Sensitivity: The sensitivity that will be applied to artifacts created in the workspace by default. Sensitivities are unassigned (template) Access Control Lists
Members: Users and groups belonging to the workspace. Personal workspaces do not have the members attribute
Personal Tags: metadata objects that can be applied to data entities such as files and folders. Personal tags are for organizational convenience, because they can be used when searching for objects
Trash folder: A default trash folder is always created, and cannot be removed. When items are deleted from the workspace, they go in the trash folder, and can be recovered from the trash folder. Purging the trash folder permanently removes the items from the workspace
Inbox: A default inbox folder is always created. Messages addressed to a team workspace, or for personal workspaces, the user, will arrive in the inbox
Default calendar: A default calendar is always created in personal workspaces (according to the default personal workspace template). In team workspaces, the first calendar that is created becomes the default calendar (but if there are several, a user with the workspace-coordinator role can select which is the default calendar). When the workspace, or for personal workspaces, the user, is invited to calendar events such as meetings, they will be held in the default calendar
Default task list: A default task list is always created in personal workspaces (according to the default personal workspace template). In team workspaces, the first task list that is created becomes the default task list (but if there are several, a user with the workspace-coordinator role can select which is the default task list). Tasks assigned to the workspace, or for personal workspaces, the user, arrive in the default task list
Default Address Book: A default address book (contacts list) is always created in personal workspaces (according to the default personal workspace template). In team workspaces, the first address book that is created becomes the default address book (but if there are several, a user with the workspace-coordinator role can select which is the default address book). Members added to a team workspace (users and groups) are added to the default address book, and members of the workspace can add additional contacts as well
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:
Post an announcement.
Edit or delete an existing announcement.
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.
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 |
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 Chapter 12, "Managing Oracle Beehive Events, Policies, and Workflows." For more information about managing and provisioning users, see Chapter 3, "Managing and Provisioning Oracle Beehive Users."
Personal workspaces can be modified using the Platform Web Services or using
. The following items may be modified using the beectl
utility:beectl
Workspace name
Workspace description
Hard quota
Soft quota
To modify a personal workspace, use the
command:beectl
modify_personal_workspace
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.
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:
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
command:beectl
list_workspace_templates
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.
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.
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
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.
To modify a workspace template, first, download the workspace template to an XML file using the
command with the --file option:beectl
list_workspace_templates
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
command to upload your changes:beectl
modify_workspace_template
beectl> modify_workspace_template --template <Workspace template identifier> --file <Full path of the input file> --name <Workspace template name>
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
command to upload the file, creating the new workspace template:beectl
add_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.
You can delete a workspace template using the
command:beectl
delete_workspace_template
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.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:
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
command:beectl
add_team_workspace
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".
You can view the attributes and properties of a team workspace, by using the
command:beectl
list_workspaces
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.
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
command with the beectl
modify_team_workspace--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
command with the beectl
modify_team_workspace--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
command with the beectl
modify_team_workspace--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
command with the beectl
modify_team_workspace--directory_listed
option:
beectl> modify_team_workspace --workspace <Workspace identifier> --directory_listed <TRUE|FALSE>
You can delete a team workspace by using the
command:beectl
delete_team_workspace
beectl> delete_team_workspace --workspace <Workspace identifier>
When you delete a team workspace, all artifacts stored in that workspace are also deleted.
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
command:beectl
add_category
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
command:beectl
delete_category
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
command:beectl
add_category_application
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
command:beectl
delete_category_application
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>
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
command:beectl
list_role_definitions
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
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.)beectl
modify_team_workspace
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>
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 Chapter 13, "Managing Oracle Beehive Access Control."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.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 |
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 Chapter 13, "Managing Oracle Beehive Access Control."
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:
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
commands to manage file system directories and files:beectl
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.
Caution:
Before importing documents to a workspace using theimport_documents
command, you should consider the effects of any existing policies on that workspace. A policy that is triggered on any new document created or added in a workspace could be triggered repeatedly as multiple files are imported.list_filesystem_references
: Lists the file system path, read-only status, and identifier (CollabID) of all available file system references.
Using File System Directories with Multiple Oracle Beehive Servers
For high availability deployments with a shared file system (or that leverage the filesystem_reference
object within workspaces), all computers on which Oracle Beehive Application Tier instances and Oracle Database instances reside should have access to the file system reference paths at the same logical location. This shared access may be accomplished using a Network File System (NFS) server, symbolic links (symlinks), or another supported method. Typically, organizations will experience optimal performance if their file systems reside on computers other than those on which Oracle Beehive and Oracle Database reside.
The following two requirements detail the necessary access for file system references to function properly:
The BEECORE OC4J component executing the beectl import_documents
command must have file system access to the specified server path.
The computer hosting the Oracle Beehive database must have local filesystem access to the specified server path. SQL requires a local filesystem path when creating a BFILE.
Creating and Using File System References
To map existing files to Oracle Beehive, perform the following steps:
Use the
command to map an existing server path for Oracle Beehive:beectl
add_filesystem_reference
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.
Use the
command to create individual references to all of the documents within Oracle Beehive:beectl
import_documents
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>]
Caution:
Before importing documents to a workspace using theimport_documents
command, you should consider the effects of any existing policies on that workspace. A policy that is triggered on any new document created or added in a workspace could be triggered repeatedly as multiple files are imported.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
command:beectl
list_filesystem_references
beectl> list_filesystem_references
To delete a file system reference, use the
command:beectl
delete_filesystem_reference
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.
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".
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 records managed Oracle Beehive artifacts. Once URM is installed and configured with Oracle Beehive, you can start the Records Management Service, and begin filing records for documents and e-mails.
Oracle Beehive manages records in place. In-place means that Oracle Beehive retains artifiacts for which you have filed records within the Oracle Beehive database, but treats them specially.
When an artifact becomes records 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' e-mails or documents that are records managed, and empty them from the Workspace Trash.
Those records managed artifacts are then stored in a special Records 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.
Artifacts can also be "records managed" without being placed under retention. These types of records are called non-records (as a short form of "non-retained records"). Artifacts with non-records 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, you can create records of:
Any document stored in a workspace in Oracle Beehive
Any e-mail in an Oracle Beehive e-mail Inbox or subfolder of an Inbox
Any e-mail sent from an Oracle Beehive e-mail user, if you turn on this feature by setting a property of the E-mail Service
As an administrator, you can manually file records for these artifacts using a
command. Additionally, you can create policies to automatically file records for documents and e-mails, based on triggering criteria.beectl
Note:
Oracle Beehive's built-in auditing function automatically audits Records Management related events. Such auditing is not Administrator-configurable. You can create an audit trail to review Record managment activity. For more information about auditing in Oracle Beehive, see "Managing Auditing Policies".Whenever a record is filed for a document or e-mail, 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 a records are filed for e-mail messages.
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:
This section describes the steps required to enable the Records Management Service in Oracle Beehive. Oracle Beehive Release 1 (1.2 or later) should already be installed.
Oracle Beehive Records Management requires an existing installation of Oracle Universal Records Management 10g Release 3 (10.1.3) or later. 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 GuideAfter installing URM, to configure URM with Oracle Beehive, perform the procedures in each of the following sections, in order:
Perform the following steps to register URM in Oracle Beehive:
Ensure the Records Management Admin user in URM (typically the sysadmin
account) is granted all possible roles:
Log in to URM
Click Admin Applets
Click User Admin
Select the Admin user (sysadmin
) and click Edit
Add the following roles: rma
, rmaadmin
, admin
, ermadmin
, ermrequestor
, rmaprivileged
, sysmanager
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 thebeectl
modify_property
command to update these values.By default, the Records Management service is not deployed when you install Oracle Beehive. Deploy the Records Management service by using the
command:beectl
add_service_configuration
./beectl add_service_configuration --archive $ORACLE_HOME/beehive/seed/services/APP/rm-service.ear --oc4j_instance_name BEEAPP
Note:
Theadd_service_configuration
command shown must be issued from the operating system command line, and not from beectl
shell mode.Use the
command to update the values of the URM system object in Oracle Beehive:beectl
add_urm
./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:
Theadd_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 the question mark (?
). 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".
Use the
command to update Oracle Beehive with this proposed configuration:beectl
activate_configuration
beectl> activate_configuration
Restart the BEEAPP OC4J managed component using the
command with the beectl
restart--component
option:
beectl> restart --component <your OC4J BEEAPP component identifier>
You can use the
command to list the managed components and their identifiers for your deployment.beectl
status
If you intend to use Policies to automatically file records of documents, you must manually add the Records Management Java action, using the following
command:beectl
add_policy_action
beectl> add_policy_action --name RMJavaAction --type JAVA --action_string oracle.ocs.management.model.RecordsManagementService:RECORDIZE --description "Recordization Action"
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:
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.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
command:beectl
list_file_plan
beectl> list_file_plan
Disposition rules are set on Retention Categories only.
In Oracle Beehive Release 1, the Records Management Service supports only the "DESTROY" disposition action.
Perform the following procedure to set up disposition rules for testing:
Using the Oracle URM user interface, on the retention category page, select the Information drop-down list and click Disposition Information
On the Disposition Instruction page, click the Add link. A Disposition Rule panel is displayed
On the Disposition Rule panel:
Select a triggering event. For Oracle Beehive Records Management disposition tests, choose the Cancel event, which can be triggered from the Oracle URM administrator UI
Specify a retention period. For Oracle Beehive Records Management disposition tests, set the retention period to be zero weeks
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.Leave the Destination Location and Destination Container blank
Set values for Apply to Records Folder and Notification Reviewer. By default, the Notification Reviewer is sysadmin
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.
By default, you can file records of e-mail messages from any Oracle Beehive user's Inbox or subfolder of Inbox. However, you cannot file records of e-mail messages sent by Oracle Beehive users.
You can enable record filing of sent e-mails by modifying a property of the Transport Properties subcomponent of the E-mail Service.
See "Configuring Sent E-mail Plugins" for details.
You can manually file records of artifacts (documents and e-mails) using
commands.beectl
You can file records automatically using policies.
Each of these procedures is detailed in the following sections:
beectl
The command-line based record filing is provided primarily as a tool for system administrators to manually file records that were not filed using a policy action. You can file a record of an e-mail or document using the
command:beectl
add_record
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 for which you want to file a record.
Specify a Retention Category or Record Folder. You can view a list of record categories and record folders, along with their identifiers, using the
command:beectl
list_file_plan
beectl> list_file_plan
You can make use of the Oracle Beehive policy framework to create records management policies. Records management policies automate the process of filing records for artifacts. You specify a policy condition for record filing, and a destination Retention Category. Oracle Beehive automatically files records for artifacts that meet the policy condition.
Note:
The records management policy action must be manually created during setup in order to use polices for record filing. Be sure to perform step 6 in the procedure in "Registering URM in Oracle Beehive".To set up a records management policy, perform the following steps:
Select a Retention Category for this policy. All records that meet this policy's condition will be filed into that Retention Category. You can list available Retention Categories using the
command:beectl
list_file_plan
beectl> list_file_plan
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
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"Create the policy by using the
command:beectl
add_policy
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, a record will be filed on any file uploaded to a specified folder, with the Retention Category 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>
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:
Thebeectl
delete_record
command cannot be reversed or undone.You must have the RECORDS_MGR privilege in order to release the records management control of an artifact.
To release an existing artifact, use the
command:beectl
delete_record
beectl> delete_record --artifact <identifier of the artifact to be deleted as a record/non-record>
Note:
Thebeectl
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 its records management is removed (released), that artifact will be deleted from the system. This is because only those records managed artifacts that have been deleted and purged by users are placed in the Record Store. Once the record for the artifact is deleted, the previous action of deleting the artifact becomes complete.
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:
Use the following steps as guidelines for troubleshooting cases where the filing of a record for an artifact failed to occur:
If a policy-based record filing failed, check the following:
Check to see if the policy was successfully registered, using the
command. If your policy is not listed, it has not been created in Oracle Beehivebeectl
list_policies
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
Try creating a policy with the same triggering conditions and scope, but with a general (non record-filing) action. You can test to see if this policy successfully runs when the triggering event occurs
Note:
When writing policies for filing records of e-mail messages, you should be aware that a seperate e-mail event is raised once for each recipient of an e-mail. The event payload of each event contains therecipient_eid
of the user getting the e-mail.
If you create a policy which depends on recepient_eid
s with two or more different values, it will never be true, since the policy will only ever evaluate events containing one recepient at a time.
Ensure that the Records Management Service is running. You can use the
command, and check the status of the Records Management Service. Alternatively, try running the beectl
status --all_services
command: this command only completes successfully if the Records Management Service is runningbeectl
list_file_plan
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 CollabID for the document or e-mail for which you are trying to file a record, in the list of returned records
The Records Management Service audits all possible actions and errors. You can query the AUDIT_RECORDS table with the event names that should have triggered the records management policy, to see if there are any results
Check the ocs_logs
table in the bee_code
schema. Messages are stored here in the event that auditing fails
Typically, deleting a record of an artifact is a synchronous manual operation, so the exception message returned by
should tell you what went wrong.beectl
Use the following steps as guidelines for troubleshooting cases where the removal of an artifact's record failed to occur:
Ensure that the Records Management Service is running. You can use the
command, and check the status of the Records Management Service. Alternatively, try running the beectl
status --all_services
command: this command only completes successfully if the Records Management Service is runningbeectl
list_file_plan
Ensure that your Oracle Universal Records Management Server is running. You can verify this by logging in to URM as sysadmin
Disposition processing is an asynchronous automatic processing performed by the Records Management Service. By default, Oracle Beehive loads and processes dispositions from Oracle URM once every hour.
Use the following steps as guidelines for troubleshooting cases where a record disposition failed to occur:
Ensure that the Records Management Service is running. You can use the
command, and check the status of the Records Management Service. Alternatively, try running the beectl
status --all_services
command: this command only completes successfully if the Records Management Service is runningbeectl
list_file_plan
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
During the procedure outlined in "Registering URM in Oracle Beehive", if the
command was specified with incorrect beectl
add_urm--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
command to change the values:beectl
modify_property
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
command:beectl
list_components
beectl> list_components --type StellentUrm
You can then list the properties of the component using the
command:beectl
list_properties
beectl> list_properties --component <component identifier>
After making changes to component properties, you must run the
command to validate and activate your proposed configuration:beectl
activate_configuration
beectl> activate_configuration
Oracle URM processes dispositions in batches. The impact of this is that disposition tasks are not necessarily available at any given time. For convenient testing of dispositions in Oracle Beehive, you can make the following configuration changes:
From the Oracle URM administrator UI, click Administration, select Configure Records Management, choose the Audit tab, and select Checked-in Audit Entries
On the option screen that opens, click the link for Default Metadata for Checked-in Audit Entries
A check-in screen will open. Enter a value in the required Title field for the title of the checked in Audit logs and click the Submit button
Select a retention category, and the system will list records checked in under this retention category by a given agent
Choose a few documents, click Actions, select trigger dates, and select Cancel
Wait for one to two minutes for the Oracle URM table to get updated. Then from Administration, select Configure Records Management, select Batch Services, and select Run All
Click My Content Server and selectMy Records Assignments. All dispositions that are due will show up on the list
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 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> <title> Workspace Summary for Members </title> <b> ${sys.workspace.name} </b> <p>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. </p> </body> </inlineSummary> </summary> <publicSummary> <inlineSummary> <fileName>publicSummary.html</fileName> <mediaType>text/html</mediaType> <body> <title> Workspace Public Summary </title> <b> ${sys.workspace.name} </b> <p> 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. </p> </body> </inlineSummary> </publicSummary> </body> </teamWorkspaceTemplate>