11 Managing Oracle Beehive Events and Policies

This module describes how to view business events, and create and manage policies including the default Oracle Beehive policies. This module contains the following sections:

Introduction to Beehive Events and Policies
Managing Beehive Events
Managing Beehive Policies

Introduction to B eehive Events and Policies

Oracle Beehive allows you to control how the system will react to a wide variety of user and system-generated events, collectively called "business events". Virtually every type of user interaction with the system, such as logging in, sending a message, performing a search, or editing a file, is "trapped," meaning, Oracle Beehive generates a business event. Events are loggable (and are logged according to the current log level), and any event may be used to trigger a policy. Oracle Beehive exposes about 400 business events.

Policies in Oracle Beehive are sets of ordered rules. Rules are if/then statements, which determine a response to a given condition. Policies are designed to be triggered from events, which determine how the system should behave. For example, the password policy determines, based on a set of criteria, whether a supplied new password is acceptable, or should be rejected. The provisioning policy determines which objects are created, by default, in a new user's personal workspace. You can make use of auditing policies to cause various user actions to be logged to an audit trail, and made available for analysis by privileged auditor users.

This section includes the following topics:

Introduction to Beehive Events
Introduction to Beehive Policies

Introduction to Beehive Events

Oracle Beehive provides about 400 business events on which you can base policies and generate notifications. In addition to these "non-blocking" events (asynchronous events), there are a number of "blocking" events (synchronous events). Synchronous events are not available for use in custom policies.

Synchronous Events

A synchronous event invocation is a "blocking call". What this means is that the event itself is prevented from completing until all policies have been evaluated to TRUE. However, in current Oracle Beehive versions, only the password policy, provisioning policy, and deprovisioning policy may make use of a synchronous event. Default password, provisioning, and deprovisioning policies are provided. You may not use synchronous events in your custom policies.

Asynchronous Events

Asynchronous events are used to customize what happens after an event completes. Policies may do something that has an impact on an entity or artifact involved the event (such as a file being updated), but the event first completes and then invokes these custom actions. For example, an asynchronous event raised after a document has been updated could be used for a policy that sends a notification to the document owner. In this case, first the file is updated, and then the event triggers the notification. You can define system-wide server-side rules by using asynchronous message-related events.

In fact, the Oracle Beehive subscriptions and notifications functionality makes extensive use of asynchronous events to trigger notifications about meeting updates, document updates, and so forth.

Asynchronous events may also be used for sending alerts. For example, a policy could send an urgent message to the mobile device of an administrator whenever a serious system fault occurs.

Asynchronous events are handled by an event queue. The event (and corresponding event payload) is accepted by the event management system, put in an event queue for later processing, and then the control is returned to the caller. This activity is transparent to users and administrators, although it may be logged for system troubleshooting purposes.

Event Subscriptions

Event subscriptions are the actions that can be attached to an event with an optional condition. When the subscription condition evaluates to true, the action attached to an event get executed.

The actions are defined by internal Oracle Beehive services and included in all deployments automatically. These actions are exposed through the policies.

Disabled Events

Certain events are disabled by default. All of the disabled events are part of the Time Management Service. The following events are not generated by the system by default:

ASSIGNMENT_ADDED
ASSIGNMENT_REMOVED
ASSIGNMENT_UPDATED
CALENDAR_ADDED
CALENDAR_REMOVED
CALENDAR_UPDATED
DEFAULT_REMINDER_ADDED
DEFAULT_REMINDER_REMOVED
DEFAULT_REMINDER_UPDATED
INVITATION_ADDED
INVITATION_REMOVED
INVITATION_UPDATED
OCCURRENCE_ADDED
OCCURRENCE_REMOVED
OCCURRENCE_UPDATED
REMINDER_ADDED
REMINDER_REMOVED
REMINDER_UPDATED
RESOURCE_CREATED
RESOURCE_UPDATED
RESOURCE_DELETED
TASKLIST_ADDED
TASKLIST_REMOVED
TASKLIST_UPDATED
TODO_ADDED
TODO_REMOVED
TODO_UPDATED

If you want to use any of these events, you must enable them by changing the EnableGenericClassOfTMBusinessEvents property of the Time Management Service. See Chapter 4, "Oracle Beehive Parameter Reference," in the Oracle Beehive Administrator's Reference Guide.

Introduction to Beehive Policies

Policies are triggered by events. They establish rules for how the system should behave when certain events occur, based on evaluating the truth of a set of conditions, and then allowing or disallowing a resulting action.

Each policy is triggered by events.

A policy has one or more rules, each of which is triggered by one event.

Each rule contains one or more conditions, which are evaluated as true or false.

Each rule may activate an action, depending on the results of the evaluated conditions.

For example, the password policy is triggered whenever a user modifies their password; the password is evaluated (by a rule) by testing whether various conditions, such as minimum length, whether it was already used previously, whether it has numbers or special characters in it, and so forth, are true or false; and then, an action allows the password change if all of the conditions are successfully met.

Oracle Beehive is shipped and installed with three default policies:

Provisioning policy
Deprovisioning policy
Password policy

Additionally, Oracle Beehive includes default audit policy templates created during the installation process. However, you cannot access auditing functionality through the policy framework.

If you configure Oracle Beehive with Oracle Universal Records Manager (URM), you can use the policy framework to create records management policies. See "Managing Records Management" for details.

You can use these default policies without changes if you wish, or you can modify them to suit the requirements of your organization. In addition, you can create new, custom policies.

Managing Beehive Events

Oracle Beehive provides about 400 events for use by policies, logging, auditing, and other functions. Events are divided into two categories: synchronous events, and asynchronous events. Synchronous events are used internally and in default policies by Oracle Beehive. Asynchronous events are available for you to work with when creating custom policies.

You can list all available events using the beectl list_events command:

beectl> list_events

Each event is listed, along with an indication of whether it is synchronous (Y or N), and a short description of the event. Only asynchronous events are listed.

You can get detailed information about any event by using the beectl list_events command with the --event_name option. For example:

beectl> list_events --event_name DOCUMENT_UPDATED

This command produces output similar to the following:

Event Name: DOCUMENT_UPDATED
Event Description: Raised when an update to a document is about to be committed.
Is Synchronous: N
                                    
------------------------------------
                                    
Event Subscriptions:                
------------------------------------
There are no event subscriptions to be listed.
------------------------------------
                                    
------------------------------------
                                    
Event Attributes:                   
------------------------------------
    
     Name: COMMON_ATTRIBUTES              Type: BEE_CODE.ECA_COMMON_EVENT_ATTRIBS_T
        
         Name: ENTITY_ID                      Type: BEE_CODE.OCS_COLLAB_ID_T
        
         Name: CONTAINER                      Type: BEE_CODE.OCS_COLLAB_ID_T
        
         Name: ACTOR_ID                       Type: BEE_CODE.OCS_COLLAB_ID_T
        
         Name: OPERATION                      Type: STRING
        
         Name: STATUS                         Type: STRING
        
         Name: MESSAGE                        Type: STRING
        
         Name: EVENT_NAME                     Type: STRING
        
         Name: LOGON_RECORD_ID                Type: INTEGER
        
         Name: EVENT_ID                       Type: INTEGER
    
     Name: CUSTOM_ATTRIBUTES              Type: BEE_CODE.WS_DOCUMENT_EVENT_ATTRIBS_T
        
         Name: ARTIFACT_ATTRIBUTES            Type: BEE_CODE.AM_COMMON_EVENT_ATTRIBS_T
            
             Name: SIZE_CHANGE                    Type: INTEGER
            
             Name: NEW_CONTAINER                  Type: BEE_CODE.OCS_COLLAB_ID_T

In addition to the name and description of the event, any subscriptions to the event are listed, and the event's attributes are detailed. The attributes include the event payload.

You specify events (using an event name) in custom polices that you create, and their attributes are made available to consuming policies.

Managing Beehive Policies

Oracle Beehive is pre-seeded during installation with three default policies:

Provisioning policy
Deprovisioning policy
Password policy

You can modify each of these policies, and in addition, you can create new policies to suit the needs of your organization. Although you can manage policies using the beectl command-line tool, it is easier to manage policies using Oracle Beekeeper. Beekeeper has several modules that allow you to work with visual models of policies, policy templates, and policy schemas.

Managing the Provisioning Policy

The provisioning policy is a definition of rules and actions that take affect when you create a user account. When Oracle Beehive is installed, a default user provisioning policy is seeded.

Provisioning policy rules can be applied based on any of the following:

Account type: enterprise user or extended enterprise user
Organizations to which the user belongs
Manager
Location
Job Title

Like all policies, the provisioning policy couples rules with actions. The provisioning policy always use the same action:

<ActionInfo>
            <name>ProvisioningPLSQLAction</name>
         </ActionInfo>

The provisioning action can specify the following:

Which workspace template to use to create the user's personal workspace
Which groups the user should be added to

Note:

The user provisioning policy can only be applied during user account creation. As a result, it is preferable to add the user to dynamic groups, based on user attributes. Doing so eliminates the need for administrator action in the future, when user attributes such as job title or manager change.

To view the default provisioning policy, use the beectl export_policy command to export the provisioning policy to an XML-formatted file:

beectl> export_policy --policy_name UserProvisioningPolicy --scope  enpr=<enterprise alias> --destination /tmp

You must provide the name of the policy, and the scope container of the policy (in this case, the enterprise alias). This command creates a file in the /tmp folder called UserProvisioningPolicy.xml. You can edit this file and then use the beectl modify_policy command to upload your changes.

Alternatively, you can create an entirely new provisioning policy, and then use the beectl modify_policy command to overwrite the existing policy:

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

Note:

Your new policy must specify the collabID of the policy to be replaced or modified, in the <collabId> element at the beginning of the XML file.

Table 11-1, "User Attributes in Provisioning and Deprovisioning Policy Conditions" summarizes the field names you can use for user attributes in your provisioning (and deprovisioning) policy conditions. For each user attribute, enter the field name listed, and provide the value shown in the table.

Table 11-1 User Attributes in Provisioning and Deprovisioning Policy Conditions

User Account Attribute	Field Name in Policy XML File	Valid Values
Office Location	custom_attributes.office_location	Value of office location
Job Title	custom_attributes.job_title	Value of job title
Is external user	custom_attributes.external_user	Y or N
Organization	custom_attributes.organization_cid	CollabID of organization
Manager	custom_attributes.manager_cid	CollabID of manager

In the action portion of the XML file, you can specify personal workspace templates and groups for the user account, by supplying the collabID of the template and each group.

You can only specify a single personal workspace template:

<actionPreferenceInfo>
           <key>template_cid</key>
           <value>collabID</value>
        </actionPreferenceInfo>

Enter the collabID of the personal workspace template inside the <value> element.

To specify multiple groups, use the following format:

<actionPreferenceInfo> 
           <key>group_cids</key>
           <group_cid>collabID1</group_cid><group_cid>collabID2</group_cid>...
        </actionPreferenceInfo>

Enter the collabID inside each <group_cid> element. You can specify any number of groups.

Example 11-1, "Provisioning Policy with Customized Conditions" demonstrates a modified provisioning policy XML file with added conditions and modified action. In this example, a simple condition is tested, in the <RuleInfo priority="1"> element: the policy checks if the user account being created has a job title of "MANAGER". If so, then an action is triggered, which is to select the "manager_template" personal workspace template. Otherwise, if the user account does not match that job title, a personal workspace template called "developer_template" is selected instead.

Managing the Deprovisioning Policy

The deprovisioning policy is the policy that is activated when an account is set to be deleted. Oracle Beehive is pre-seeded with an "empty" deprovisioning policy; by default it does not trigger any system actions when invoked. You may modify the deprovisioning policy to suit the needs of your organization.

Deprovisioning policy rules can be based on any of the following user attributes:

Organization
Manager
Extended enterprise user
Location
Job title

Like all policies, the deprovisioning policy couples rules with actions. The deprovisioning policy always uses the same action:

<ActionInfo>
    <name>DeprovisioningPLSQLAction</name>
</ActionInfo>

The deprovisioning action can specify any of the following:

A user to be the new owner for groups the deleted user owned
A rule reassigning all owned groups to the user's manager
A rule specifying a new assistant, when the user account being deleted is an assistant to another user

For example, the deprovisioning policy might indicate that when a user is removed, if this user has a title of "director," all of the user's documents will be reassigned to the user's manager, and all groups that the user owned will be reassigned to the system administrator.

To view the default deprovisioning policy, use the beectl export_policy command to export the provisioning policy to an XML-formatted file:

beectl> export_policy --policy_name UserDeprovisioningPolicy --scope  enpr=<enterprise alias> --destination /tmp

You must provide the name of the policy, and the name of the scope container of the policy (in this case, the enterprise alias). This command creates a file in the /tmp folder called UserDeprovisioningPolicy.xml. You can edit this file and then use the beectl modify_policy command to upload your changes.

Alternatively, you can create an entirely new deprovisioning policy, and then use the beectl modify_policy command to overwrite the existing policy:

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

Note:

Your new policy must specify the collabID of the policy to be replaced or modified, in the <collabId> element at the beginning of the XML file.

Table 11-1, "User Attributes in Provisioning and Deprovisioning Policy Conditions" summarizes the field names you can use for user attributes in your deprovisioning (and provisioning) policy conditions. For each user attribute, enter the field name listed, and provide the value shown in the table.

In the action portion of the XML file, you can specify a new owner for the user's owned groups by supplying the collabID of the new owner:

<actionPreferenceInfo> 
           <key>new_owner_cid</key> 
           <value>new_owner_collabID</value> 
        </actionPreferenceInfo>

You can indicate whether ownership should be re-assigned to the user's manager, using a value of Y or N in the assign_ownership_to_manager action preference:

<actionPreferenceInfo> 
           <key>assign_ownership_to_manager</key>
           <value>Y</value> 
         </actionPreferenceInfo>

You can indicate a new assistant if the user being deleted is an assistant to another user, by supplying the collabID of the new assistant:

<actionPreferenceInfo>
           <key>new_assistant_cid</key>
           <value>new_assistant_collabID</value>
        </actionPreferenceInfo>

Example 11-3, "Deprovisioning Policy with Customized Conditions" demonstrates how to modify the deprovisioning policy XML file to add customized conditions. In this example, a simple condition is tested, in the <RuleInfo priority="1"> element: the policy checks if the user account being deleted belonged to the "SALES" organization. If so, then an action is triggered, which is to assign all groups the user owns to a specific user.

Note:

The RuleID and CollabID values shown are examples; you must replace them with correct CollabIDs from your own deployment. If you export an existing policy, it will contain the correct ruleIDs and collabIDs.

Example 11-3 Deprovisioning Policy with Customized Conditions

<?xml version = '1.0' encoding = 'UTF-8'?>
<PolicyInfo isExtensible="true">
   <collabId>4DA5:0F49:plcy:355E4C9DBE6147FDE040578C0309297700000000042E</collabId>
   <containerId>4DA5:0F49:enpr:355E4C9DBE6147FDE040578C030929770000000001D0</containerId>
   <templateId></templateId>
   <name>UserDeprovisioningPolicy</name>
   <RuleInfos>
      <RuleInfo priority="1">
         <name>Deprovisioning PLSQL rule</name>
         <eventTypeName>USER_DEPROVISIONING</eventTypeName>
         <ruleId>4DA5:0F49:rule:355E4C9DBE6147FDE040578C03092977000000000430</ruleId>         <templateRuleIds/>
         <ConditionInfo>
            <conditionExpression>
               <simple>
                  <leftSide>CUSTOM_ATTRIBUTES.organization_cid</leftSide>
                  <operator>=</operator>
                  <rightSide>'SALES'</rightSide>
               </simple>
            </conditionExpression>
         </ConditionInfo>
         <ActionInfo>
            <name>DeprovisioningPLSQLAction</name>
         </ActionInfo>
         <ActionPreferenceInfos>
            <actionPreferenceInfo>
               <key>new_owner_cid</key>
               <value>new_owner_collabID</value>
            </actionPreferenceInfo>
         </ActionPreferenceInfos>
      </RuleInfo>
   </RuleInfos>
</PolicyInfo>

Managing the Password Policy

The password policy is a definition of rules and actions that take affect when a password for a user account is created or modified. When Oracle Beehive is installed, a default password policy is seeded.

Password policy rules can be applied based on any of the following:

Minimum length
Maximum length
Contains alphabetic characters
Contains upper-case alphabetic characters
Contains non-alphanumeric characters
Contains the user name
Was previously used as a password by the user

Like all policies, the password policy couples rules with actions. The password policy always use the same action:

<ActionInfo>
            <name>Password modification action</name>
         </ActionInfo>

The password policy action only specifies that the password modification action will be allowed. If all of the policy rules are met, the action allows the password to be modified; otherwise, it prevents the password modification.

To view the default password policy, use the beectl export_policy command to export the provisioning policy to an XML-formatted file:

beectl> export_policy --policy_name "Validate Password" --scope  enpr=<enterprise alias> --destination /tmp

You must provide the name of the policy, and the name of the scope container of the policy (in this case, the enterprise alias). This command creates a file in the /tmp folder called PasswordPolicy.xml. You can edit this file and then use the beectl modify_policy command to upload your changes.

Alternatively, you can create an entirely new password policy, and then use the beectl modify_policy command to overwrite the existing policy:

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

Note:

Your new policy must specify the collabID of the policy to be replaced or modified, in the <collabId> element at the beginning of the XML file.

Example 11-4, "Default Password Policy" shows the content of the default password policy. You can use this example as a reference for how password conditions are constructed in the <RuleInfos> section of the policy. As you can see, the password policy rule is triggered by the ON_AUTH_USER_PASSWD_MODIFICATION event. This is a synchronous (blocking) event. When you modify the password policy, you should not change this value.

Each of the conditions in the password policy is written as a condition of exclusion. This means, if the password matches any condition, it is disallowed. If it does not match any condition, it is allowed. This functionality is exposed by the password policy blocking the calling event if any condition is true.

Example 11-4 Default Password Policy

<?xml version = '1.0' encoding = 'UTF-8'?>
<PolicyInfo isExtensible="true">
   <policy>plcy=PasswordPolicy,enpr=oracle</policy>
   <scope>enpr=enterprise_alias</scope>
   <template></template>
   <name>PasswordPolicy</name>
   <description>Password policy desc</description>
   <RuleInfos>
      <RuleInfo priority="1">
         <name>Password Auth PLSQL Rule</name>
         <description>Password Auth rule description</description>
         <eventTypeName>ON_AUTH_USER_PASSWD_MODIFICATION</eventTypeName>
         <ruleId>713E:6031:rule:374B57D9F3BDC9A1E040578C211A7A46000000000419</ruleId>
         <toRemove>false</toRemove>
         <templateRuleIds/>
         <ConditionInfo>
             <DisjunctionInfo>
               <LeftBooleanExpression>
                  <DisjunctionInfo>
                     <LeftBooleanExpression>
                        <DisjunctionInfo>
                           <LeftBooleanExpression>
                              <DisjunctionInfo>
                                 <LeftBooleanExpression>
                                    <DisjunctionInfo>
                                       <LeftBooleanExpression>
                                          <Simple>
                                             <leftSide>LENGTH(CUSTOM_ATTRIBUTES.USER_PASSWD)</leftSide>
                                             <operator>&lt;</operator>
                                             <rightSide>8</rightSide>
                                          </Simple>
                                       </LeftBooleanExpression>
                                       <RightBooleanExpression>
                                          <Simple>
                                             <leftSide>LENGTH(CUSTOM_ATTRIBUTES.USER_PASSWD)</leftSide>
                                             <operator>></operator>
                                             <rightSide>128</rightSide>
                                          </Simple>
                                       </RightBooleanExpression>
                                    </DisjunctionInfo>
                                 </LeftBooleanExpression>
                                 <RightBooleanExpression>
                                    <Simple>
                                       <leftSide>AUTH_POLICY_FUNC_PKG.VERIFY_ALPHANUM(CUSTOM_ATTRIBUTES.USER_PASSWD)</leftSide>
                                       <operator>=</operator>
                                       <rightSide>0</rightSide>
                                    </Simple>
                                 </RightBooleanExpression>
                              </DisjunctionInfo>
                           </LeftBooleanExpression>
                           <RightBooleanExpression>
                              <Simple>
                                 <leftSide>AUTH_POLICY_FUNC_PKG.CONTAINS_USERNAME(CUSTOM_ATTRIBUTES.USER_NAME,CUSTOM_ATTRIBUTES.USER_PASSWD)</leftSide>
                                 <operator>=</operator>
                                 <rightSide>0</rightSide>
                              </Simple>
                           </RightBooleanExpression>
                        </DisjunctionInfo>
                     </LeftBooleanExpression>
                     <RightBooleanExpression>
                        <Simple>
                           <leftSide>AUTH_POLICY_FUNC_PKG.VERIFY_CASE(CUSTOM_ATTRIBUTES.USER_PASSWD)</leftSide>
                           <operator>=</operator>
                           <rightSide>0</rightSide>
                        </Simple>
                     </RightBooleanExpression>
                  </DisjunctionInfo>
               </LeftBooleanExpression>
               <RightBooleanExpression>
                  <Simple>
                     <leftSide>AUTH_POLICY_FUNC_PKG.IN_HISTORY(CUSTOM_ATTRIBUTES.USER_NAME,CUSTOM_ATTRIBUTES.ENCRYPTED_PASSWD)</leftSide>
                     <operator>=</operator>
                     <rightSide>0</rightSide>
                  </Simple>
               </RightBooleanExpression>
            </DisjunctionInfo>
         </ConditionInfo>
         <ActionInfo>
            <name>Password modification action</name>
         </ActionInfo>
         <ActionPreferenceInfos/>
      </RuleInfo>
   </RuleInfos>
</PolicyInfo>

This password policy sets the following rules for passwords:

Must not be fewer than 8 characters in length
Must not be more than 128 characters in length
Must not have 0 alphanumeric characters
Must contain both alphabetic and numeric characters
Must not contain the user name
Must not be a previously-used password (verified by checking the password history of the user)

Managing Audit Policies

Auditing allows you to track and record the activities of users and administrators as they perform actions in the system. These activities include logging on and off, creating, modifying, or deleting content, altering system configuration parameters, starting and stopping processes, and so forth. The goal is to provide a framework for keeping tabs on who does what to the system.

Audit policies are treated separately from other policy types. For example, they are not listed when you use the beectl list_policies command.

For full details about creating and managing auditing policies, see Chapter 14, "Managing Oracle Beehive Auditing".

Creating and Managing Custom Policies

In addition to the default policies, you can create custom policies of your own, to suit your organization's needs. Generally, it is much easier to create and manage custom policies using Oracle Beekeeper. In this section, procedures for creating and managing custom policies are presented using the beectl command-line tool. The Oracle Beekeeper Online Help includes instructions and assistance with creating and managing policies.

Creating New Policies

There are two types of actions: Java and PLSQL. The default provisioning, deprovisioning, password, auditing, and record management policies make use of PLSQL actions which are pre-defined in the system. When you modify any of the default policies, or create your own provisioning, deprovisioning, auditing, or record management policies, you do not need to make any changes to the actions.

You cannot create custom actions. You can create custom policies using the pre-existing actions.

To create a new policy using beectl, upload an XML formatted policy document using the beectl add_policy command:

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

You can also create and use policy templates. A policy template defines a set of rules containing conditions, and an action, but does not specify the actor or scope for the triggering event of the policy. For example, you could create a policy template that is triggered when a document in a workspace is deleted. You could then later apply this policy template by using it to create a policy applying it to a specific organization, or for a specific user's documents.

Policy templates may make use of schemas. Policy Schemas are pre-defined sets of rule and attribute definitions. When you use a schema to create a template, you are combining the schema's rules with actions defined in the template.

Oracle Beehive comes with two default schemas: the Audit schema and the Records Management schema. Additionally, you can create your own schemas: new Audit or Records Management schemas, or General schemas (for all other uses).

Creating New Policy Templates

To create a new policy template using beectl, create a template XML file and import it using the beectl add_policy_template command:

beectl> add_policy_template --file <full path to the policy template xml file>

An example policy template may be found in your Oracle Beehive installation at $ORACLE_HOME/beehive/templates/policy/TestAddPolicyTemplate.xml.

Creating New Policy Schemas

To create a new policy schema using beectl, create a schema XML file and import it using the beectl add_policy_schema command:

beectl> add_policy_schema --file <full path to the policy schema xml file>

An example policy schema may be found in your Oracle Beehive installation at $ORACLE_HOME/beehive/templates/policy/TestAddPolicySchema.xml.

Creating New Policies

To create a new policy based on a policy template using beectl, use the beectl add_policy command, referring to an XML-formatted file containing the policy information:

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

Example policies may be found in your Oracle Beehive installation at $ORACLE_HOME/beehive/templates/policy.

The following is an example of a policy file. To specify a template to use for a policy, put the template identifier into the template element tag in the policy XML file:

<?xml version="1.0" encoding="UTF-8" ?>
<PolicyInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="policy_xml/policyInfo.xsd">
  <policy></policy>
  <scope></scope>
  <template></template>
  <name>FooAddPolicyTest_simple</name>
  <description>This is a test.</description>
...

Editing Existing Policies

You can edit any existing policy. First, locate the policy and export it to an XML file. Then, edit the file, and import it back to the system to modify the existing policy.

To list policies, use the beectl list_policies command:

beectl> list_policies --policy_name <name of the policy to be listed> --scope<container where the policy is deployed> --children <whether to include policiesdefined at child containers> --enforced <whether to include enforced policies>

To export a policy, use the beectl export_policy command:

beectl> export_policy --policy_name <name of the policy to download> --scope<identifier of container where the policy is defined> --destination <destinationdirectory>

After editing the policy XML, use the beectl modify_policy command to import your changes:

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

Deleting Custom Policies

You can delete an existing policy. You should never delete the provisioning, deprovisioning, or password policies.

If you delete a policy that prevents some action that you are prohibiting users from performing, the users will be able to perform that action. Thus, there is a potential security risk whenever you delete a policy. Use caution.

To delete a policy, use the beectl delete_policy command:

beectl> delete_policy --policy <id or name of the policy to be deleted>

You can also delete a custom policy template you have created. If the policy template is currently in use by any policy, when you attempt to delete it you will see an error message.

To delete a policy template, use the beectl delete_policy_template command:

beectl> delete_policy_template --policy_template <id or name of the policy template to be deleted>

Using Dynamic Policy Attributes

Beginning in Oracle Beehive 1.5, you can use dynamic attributes in your policies. This allows you to get data from the payload of a triggering event and use it in the policy. For example, if you built a policy template that triggers when a new document is created in a workspace, you could get the document name and use it in the generated task title.

To use a dynamic attribute, include XML in your policy (or policy template) similar to the following:

<Attributes>
   <attribute>
     <name>attribute1</name>
     <defaultValue>attribute1 default value</defaultValue>
     <prompted>true</prompted>
     <required>false</required>
 </attribute>
.
.
.
  <attribute>
   <name>attribute n</name>
   <defaultValue>attribute n default</defaultValue>
   <prompted>true</prompted>
   <required>false</required>
 </attribute>
</Attributes>

You can include any number of attribute elements.

Dynamic policy attributes are listed in "Dynamic Policy Attributes," in Chapter 1, "Oracle Beehive XML File Reference" of the Oracle Beehive Administrator's Reference Guide, along with an example. Attribute names must be from either the dynamic policy attribute list in that section, or the list of attributes for the given event that will trigger the policy. You can list all of the attributes of an event by using the beectl list_events command with the --internal_name option. For example:

beectl> list_events --internal_name WORKSPACE_UPDATED

11 Managing Oracle Beehive Events and Policies

Introduction to Beehive Events and Policies

Introduction to Beehive Events

Synchronous Events

Asynchronous Events

Event Subscriptions

Disabled Events

Introduction to Beehive Policies

Managing Beehive Events

Managing Beehive Policies

Managing the Provisioning Policy

Managing the Deprovisioning Policy

Managing the Password Policy

Managing Audit Policies

Creating and Managing Custom Policies

Creating New Policies

Creating New Policy Templates

Creating New Policy Schemas

Creating New Policies

Editing Existing Policies

Deleting Custom Policies

Using Dynamic Policy Attributes

Introduction to B eehive Events and Policies