Oracle® Beehive Administrator's Guide Release 1 (1.5) Part Number E14836-04 |
|
|
View PDF |
This module describes how to view business events, create and manage policies including the default Oracle Beehive policies, and create and manage workflows. This module contains the following sections:
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 and/or workflow. 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.
You can also use special workflow policies to trigger workflows, such as an approval process when a file is uploaded to a particular workspace, or when a particular resource is reserved for a meeting. Oracle Beehive deployments include the Oracle BPEL Process Manager. Workflow policies are capable of triggering BPEL workflows. By this mechanism, a workflow can be triggered from various business events.
Oracle Beehive workflow can be created and managed using the
command line interface. Corresponding BPEL processes can be designed using Oracle JDeveloper. This BPEL Process archive (a jar file) is used during the creation of a workflow in Oracle Beehive.beectl
Workflows allow you to create a multi-stage process flow, in which users make decisions relating to whichever events were used to trigger a workflow policy. Workflow tasks are exposed to users in Oracle Beehive clients as task assignments.
This section includes the following topics:
Oracle Beehive provides about 400 business events on which you can base policies, generate notifications, and drive workflows. 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 (or workflow policies).
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 Oracle Beehive Release 1, 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 are used to customize what happens after an event completes. Policies or workflows 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 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. You may only create new, custom actions for the use of custom workflows.
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, such as for creating custom workflows, 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.
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.
Oracle Beehive provides integration with Oracle BPEL and the BPEL Process Manager, to allow you to automate approvals and other workflow tasks. You can invoke workflows in two ways:
By configuring workflow templates, which determine which default workflows are invoked (and when, that is, which container) based on content related operations
By configuring custom workflow policies, which invoke custom workflows you can define
Note:
For detailed instructions on creating and using custom workflow policies, see Oracle Beehive Application Developer's Guide.For custom workflows, you can create custom workflow policies, which determine which events will trigger workflows, and how the workflow process should complete.
Workflows are exposed to users through tasks, in Oracle Beehive clients including Microsoft Outlook, CalDAV clients, mobile clients, and so on. When a user needs to approve of an action, a task is delivered to the user. The user can then approve or disapprove of the task. When all approval tasks are complete, the workflow notifies the original caller of its completion.
You can create and manage custom templates by editing XML-formatted files, and importing them to Oracle Beehive from the command line. See "Managing Beehive Workflows" for details.
Oracle Beehive provides about 400 events for use by policies, workflows, 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
command:beectl
list_events
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. In Oracle Beehive Release 1, only asynchronous events are listed.
You can get detailed information about any event by using the
command with the beectl
list_events--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.
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. This section contains the following topics:
See Also:
"Policy Definitions" in Chapter 1, "Oracle Beehive XML File Reference" of the Oracle Beehive Administrator's Reference Guide,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
command to export the provisioning policy to an XML-formatted file:beectl
export_policy
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
command to upload your changes.beectl
modify_policy
Alternatively, you can create an entirely new provisioning policy, and then use the
command to overwrite the existing policy:beectl
modify_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 12-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 12-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 12-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.
See Also:
For more information about creating custom personal workspace templates, see "Managing Oracle Beehive Workspaces".Note:
The CollabID values shown are examples; you must replace them with correct CollabIDs from your own deployment.Example 12-1 Provisioning Policy with Customized Conditions
<?xml version = '1.0' encoding = 'UTF-8'?> <PolicyInfo isExtensible="true"> <collabId>4DA5:0F49:plcy:355E4C9DBE6147FDE040578C0309297700000000042A</collabId> <containerId>4DA5:0F49:enpr:355E4C9DBE6147FDE040578C030929770000000001D0</containerId> <templateId></templateId> <name>UserProvisioningPolicy</name> <RuleInfos> <RuleInfo priority="1"> <name>Provisioning_rule1</name> <eventTypeName>USER_PROVISIONING</eventTypeName> <ruleId></ruleId> <templateRuleIds/> <ConditionInfo> <conditionExpression> <simple> <leftSide>CUSTOM_ATTRIBUTES.JOB_TITLE</leftSide> <operator>=</operator> <rightSide>'MANAGER'</rightSide> </simple> </conditionExpression> </ConditionInfo> <ActionInfos> <name>ProvisioningPLSQLAction</name> <description>Provisioning action</description> <actionTypeName>PLSQL</actionTypeName> <actionString>uds_user_provisioning.apply_provisioning_policy</actionString> </ActionInfos> <ActionPreferenceInfos> <actionPreferenceInfo> <key>template_cid</key> <value>manager_template_collabID</value> </actionPreferenceInfo> <actionPreferenceInfo> <key>group_cids</key> <value><group_cid>managers_group_collabID</group_cid></value> </actionPreferenceInfo> </ActionPreferenceInfos> </RuleInfo> <RuleInfo priority="1"> <name>Provisioning_rule2</name> <eventTypeName>USER_PROVISIONING</eventTypeName> <ruleId></ruleId> <templateRuleIds/> <ConditionInfo> <conditionExpression> <simple> <leftSide>CUSTOM_ATTRIBUTES.JOB_TITLE</leftSide> <operator>!=</operator> <rightSide>'DEVELOPER'</rightSide> </simple> </conditionExpression> </ConditionInfo> <ActionInfo> <name>ProvisioningPLSQLAction</name> </ActionInfo> <ActionPreferenceInfos> <actionPreferenceInfo> <key>template_cid</key> <value>developer_template_collabID</value> </actionPreferenceInfo> </ActionPreferenceInfos> </RuleInfo> </RuleInfos> </PolicyInfo>
As this example demonstrates, a policy can string multiple <RuleInfo>
elements together, each one coupling a set of rules with an action.
Note:
Rules have priority numbers. Rules which are mutually exclusive, such as the two rules in this example, can have the same priority because they will never both occur. If you specify several rules which can evaluate as true at the same time, each such rule should have a different priority number to indicate which rule is evaluated first.Example 12-2, "Provisioning Policy with Complex Customized Conditions" demonstrates the use of a more complex condition in a provisioning policy. In this example, two conditions are tested: if the user has a job title of "MANAGER", and if the user belongs to an organization called "SALES". If both conditions are true, the "sales_manager_template" personal workspace template is assigned, and the user is added to both the "all_managers" and "abcdefg_managers" groups.
Example 12-2 Provisioning Policy with Complex Customized Conditions
<?xml version = '1.0' encoding = 'UTF-8'?> <PolicyInfo isExtensible="true"> <collabId>4DA5:0F49:plcy:355E4C9DBE6147FDE040578C0309297700000000042A</collabId> <containerId>4DA5:0F49:enpr:355E4C9DBE6147FDE040578C030929770000000001D0</containerId> <templateId></templateId> <name>UserProvisioningPolicy</name> <RuleInfos> <RuleInfo priority="1"> <name>Provisioning_rule1</name> <eventTypeName>USER_PROVISIONING</eventTypeName> <ruleId></ruleId> <templateRuleIds/> <ConditionInfo> <conditionExpression> <conjunction> <LeftBooleanExpression> <leftSide>custom_attributes.job_title</leftSide> <operator>=</operator> <rightSide>'MANAGER'</rightSide> </LeftBooleanExpression> <RightBooleanExpression> <leftSide>custom_attributes.organization_cid</leftSide> <operator>=</operator> <rightSide>'SALES"</rightSide>
</RightBooleanExpression> </conjunction> </conditionExpression> </ConditionInfo> <ActionInfo> <name>ProvisioningPLSQLAction</name> </ActionInfo> <ActionPreferenceInfos> <actionPreferenceInfo> <key>template_cid</key> <value>sales_manager_template _collabID</value> </actionPreferenceInfo> <actionPreferenceInfo> <key>group_cids</key> <value><group_cid>all_managers_group_collabID</group_cid><group_cid>abcdefg_manager_group_collabid</group_cid></value> </actionPreferenceInfo> </ActionPreferenceInfos> </RuleInfo> </RuleInfos> </PolicyInfo>
As this policy demonstrates, you can provide multiple <actionPreferenceInfo>
elements in a policy action, each one directing the system to perform a task.
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
command to export the provisioning policy to an XML-formatted file:beectl
export_policy
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
command to upload your changes.beectl
modify_policy
Alternatively, you can create an entirely new deprovisioning policy, and then use the
command to overwrite the existing policy:beectl
modify_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 12-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 12-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 12-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>
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
command to export the provisioning policy to an XML-formatted file:beectl
export_policy
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
command to upload your changes.beectl
modify_policy
Alternatively, you can create an entirely new password policy, and then use the
command to overwrite the existing policy:beectl
modify_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 12-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 12-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><</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)
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".
In addition to the default policies, you can create custom policies of your own, to suit your organization's needs. This section contains the following topics:
See Also:
"Policy Definitions" in Chapter 1, "Oracle Beehive XML File Reference" of the Oracle Beehive Administrator's Reference Guide,There are two types of actions: Java and PLSQL. The default provisioning, deprovisioning, password and auditing 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, or auditing 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, upload an XML formatted policy document using the
command:beectl
add_policy
beectl> add_policy --file <full path to the policy xml file>
See Also:
For detailed instructions on how to create a custom workflow policy using workflow actions, see Oracle Beehive Application Developer's Guide.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, which evaluates whether the document is owned by another user, and if so, triggers an approval workflow. 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.
To create a new policy template, create a template XML file and import it using the
command:beectl
add_policy_template
beectl> add_policy_template --file <full path to the policy template xml file>
To create a new policy based on a policy template, use the
command, referring to an XML-formatted file containing the policy information:beectl
add_policy
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>
...
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
command:beectl
list_policies
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
command:beectl
export_policy
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
command to import your changes:beectl
modify_policy
beectl> modify_policy --file <full path to the policy xml file>
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
command:beectl
delete_policy
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
command:beectl
delete_policy_template
beectl> delete_policy_template --policy_template <id or name of the policy template to be deleted>
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 workflow 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 (and dynamic workflow template 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 --event_name
option. For example:
beectl> list_events --event_name WORKSPACE_UPDATED
Oracle BPEL Process Manager is installed and configured, and seeded with default workflows, during Oracle Beehive installation. The
and beectl
start
commands start and stop the BPEL Process Manager along with the rest of the Oracle Beehive processes.beectl
stop
The default workflows provided by Oracle Beehive make use of workflow templates to define when (and which) default workflow is invoked. However, custom workflows make use of policies using the same policy XML files as other policies, with the exception that the actions are different. These custom actions must be created.
You can configure custom workflows using custom workflow policies. You can configure the default serial and parallel vote workflows using workflow templates.
See Also:
For detailed instructions on creating and using custom workflow policies, see Oracle Beehive Application Developer's Guide.
For documentation on using the BPEL Process Manager, see Oracle BPEL Process Manager Quick Start Guide."
You can list all workflows (both default and custom workflows) that have been initiated from Oracle Beehive, and check their status, using the
command:beectl
list_workflows
./beectl list_workflows [ --status <status of the workflow to be listed> ] [ --creator <creator id of the workflow to be listed> ]
This section contains the following topics:
There are two workflow processes provided with Oracle Beehive:
Serial workflows
Parallel vote workflows
A serial workflow may include one or more user tasks, but each task applies to only one user. If a serial workflow includes multiple tasks, Oracle Beehive creates and assigns each new task when the previous task is completed. If a serial workflow has multiple approvers, once any approver rejects the task, no further approvers will be assigned approval tasks.
A parallel vote workflow has a voting mechanism, so that several users collectively make a decision about the workflow tasks. Oracle Beehive determines whether to accept or reject the workflow based on the percentage of approvals. A workflow is accepted if greater than some specified percentage of approvers approve of the workflow.
Note:
A parallel vote workflow with a fractional vote percentage of 0.001 or less will fail. A parallel vote workflow must not include more than 999 users.Workflow approvals are exposed within Oracle Beehive and standards-based clients through tasks. When a workflow needs a user input (usually an approval), Oracle Beehive generates a task and assigns it to that user. The approver can approve or reject the workflow process by completing or declining the Oracle Beehive task. The operation that triggered the workflow to be initiated, such as creating a document in a team workspace, will then either be allowed to complete or be rejected. Oracle Beehive will automatically update the BPEL Process Manager, which will continue to process the workflow.
When the workflow is completed, the operation that triggered the workflow is either allowed to complete, or cancelled.
A task generated by a default workflow template includes the following components:
A title
An initiator: the user whose action triggered the workflow is shown in Oracle Beehive as the task assigner, while the approvers are the task assignees
A Justification: this may be an explanation for why the user action is justified. The workflow template provides a default justification. Future versions of Oracle Beehive may allow the triggering user to edit the justification
A URL, which is the WebDAV link to whatever location (document or folder) was involved in triggering the workflow. For example, if the workflow is triggered by DOCUMENT_DELETE, the link goes to the document being deleted
A payload: in the current release of Oracle Beehive, this content is not included. Future versions of Oracle Beehive will allow additional text in the payload to be included in the task
The client's usual task buttons or links to accept or decline (disapprove) the task
See Also:
"Workflow Templates," in Chapter 1, "Oracle Beehive XML File Reference" of the Oracle Beehive Administrator's Reference GuideOracle Beehive provides two default workflow processes, the serial workflow and the parallel vote workflow. You can determine when and where one such workflow process is triggered using workflow templates. Workflow templates allow you to create a variety of serial and parallel vote workflows at various levels of context, and triggered by various different events. This allows the same BPEL workflow process to be re-used in different contexts. Oracle Beehive workflow templates make use of "template keys", which are a set of specialized synchronous events on which workflows may be triggered. Oracle Beehive workflows may only be triggered by these specific events.
Because the workflow template keys are synchronous events, the workflow process blocks the event from completing. For example, a workflow triggered by the DOCUMENT_DELETE template key must complete successfully before the document will be deleted by Oracle Beehive. If the approval request is declined, the event does not occur or is cancelled; so if a workflow triggered by DOCUMENT_DELETE is declined, the document will not be deleted.
You can manage workflows by creating and using workflow templates. A Workflow template customizes the attribute settings of a default workflow.
Table 12-2, "Oracle Beehive Workflow Template Keys" lists the template keys available for Oracle Beehive workflow templates.
Table 12-2 Oracle Beehive Workflow Template Keys
Template key | Description |
---|---|
DOCUMENT_CREATE |
Invoked when a new document is created (uploaded) |
DOCUMENT_UPDATE |
Invoked when an existing document is altered |
DOCUMENT_CHECKIN |
Invoked when a document is checked in |
DOCUMENT_DELETE |
Invoked when an existing document is deleted |
DOCUMENT_COPY |
Invoked when a copy of an existing document is made |
DOCUMENT_MOVE_TO |
Invoked when a document is moved in to the designated location (container) |
DOCUMENT_MOVE_FROM |
Invoked when a document is moved from the designated location (container) |
FOLDER_DELETE |
Invoked when an existing folder is deleted |
FOLDER_COPY |
Invoked when a copy is made of an existing folder |
FOLDER_MOVE_TO |
Invoked when a folder is moved to the designated location (container) |
FOLDER_MOVE_FROM |
Invoked when a folder is moved from the designated location (container) |
A sample workflow template XML file, and its corresponding DTD, is located in the following folder:
$ORACLE_HOME/beehive/templates/workflow
Workflow templates include the following elements which you must specify:
Note:
A size limit exists (measured in bytes) for the <defaultValue> element of the tasktitle, initiator, and approvers attributes, in the serial and parallel vote workflows. Tasktitle is limited to 75 bytes, while initiator and approver are limited to 100 bytes. Note that when using multi-byte character sets, each character may consume more than one byte, reducing the effective limitation in characters to a smaller number.name:
A name for this workflow template
description:
A description of this workflow template
schemaname:
This value determines whether this is a serial or parallel vote workflow. For serial workflows, use SerialWorkflow. For a parallel vote workflow, use ParallelVoteWorkflow. No other values are supported for workflow templates
scope:
A container for this workflow template. In the example, an enterprise is specified, but you can specify any level of scope: enterprise, organization, workspace, or folder. Use the collabID or alias for any such scope
templatekey:
One of the templatekey values shown in Table 12-2. The templatekey determines the user operation that will trigger the workflow
default justification:
The justification appears in the body of the task generated by a workflow
default workflow timeout:
Specify a maximum time for the workflow to be completed before it will automatically complete with a failure (not approved) result. The timeout format is in the form P<days>D<hours>H<minutes>M, where each value must be an integer. For example, P1D12H specifies one day and twelve hours (1.5 days), P5D specifies five days, and P0D2H30M specifies zero days, two hours, and thirty minutes
default approver timeout:
Specify a maximum time for any approver to approve of a workflow task before the task automatically completes with a failure (not approved). If there are multiple approvers, each approver will get this amount of time to approve a task; however, the default workflow timeout takes priority, even if any approvers have not yet reached the default approver timeout
default approvers:
One or more approvers, separated by commas. This field is limited to 100 bytes. For a serial workflow, each approver is given a task in turn, while in a parallel vote workflow, all approvers are given the task at the same time. Approvers are specified using their login ID (Primary Principal) only; see "About User Account Principals and Credentials" for details about the Primary Principal user ID
Caution:
The user identifiers that are specified in the template are case-sensitive and must exactly match the identifier defined for the user in UDS. If a user identifier is not an exact match, other tasks in Oracle Beehive will not be created properly.default payload:
After listing the justification, the a task generated by the workflow contains the payload text
default tasktitle:
The title of the tasks generated by this workflow template. This field is limited to 75 bytes
default initiator:
When a workflow is generated from this workflow template, the user that took the action (the templatekey event) is the initiator. However, if a failure of some kind occurs, the value of the initiator element becomes the default workflow initiator, to prevent the workflow from becoming invalid. The initiator should be a user that is guaranteed to be valid, such as the BEEadmin user. This field is limited to 100 bytes.
default votepercent: (Parallel Vote workflow templates only)
This integer value is the percentage of votes needed to approve the workflow. Once the votepercent is reached in approvers, the workflow will complete
Note:
A parallel vote workflow with a fractional vote percentage of 0.001 or less will fail. A parallel vote workflow must not include more than 999 users.Note:
In the previous lists, items listed as "default" may be overridden in some cases when the workflow is generated, depending on how the user interface exposes the workflow. The option to substitute a new value for a default value does not exist in any client in Release 1 of Oracle Beehive, but future versions of Oracle Beehive clients may include such capability.Example 12-5, "Serial Workflow Template XML File" shows an example Serial Workflow template XML file. The items in bold indicate the element values you should specify when creating a new serial workflow template.
Note:
The workflow template attributes all have elements called <prompted> and <required>. Eventually these elements may be used by clients to determine whether a value is required, and whether a user triggering the workflow is prompted to enter a new value for the attribute. However, in Oracle Beehive Release 1, these element values are not used (although they must be present in the workflow template). Future releases of Oracle Beehive will expose this functionality.Similarly, the payload element is not exposed in Oracle Beehive Release 1.
Example 12-5 Serial Workflow Template XML File
<?xml version="1.0" encoding="UTF-8" ?> <WorkflowTemplateInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xml.oracle.com/beehive/workflow/workflow_template.xsd" xmlns="http://xml.oracle.com/beehive/workflow" isfinal="false"> <name>Serial WF approval</name> <description>A template for invoking Serial Workflow</description> <schemaname>SerialWorkflow</schemaname> <scope>enpr=my_enterprise_name</scope> <templatekey>DOCUMENT_CREATE</templatekey> <Attributes> <attribute> <name>justification</name> <defaultValue>justification Approval required to add a document to the team workspace</defaultValue> <prompted>true</prompted> <required>false</required> <final>false</final> </attribute> <attribute> <name>workflowtimeout</name> <defaultValue>P1D</defaultValue> <prompted>true</prompted> <required>false</required> <final>false</final> </attribute> <attribute> <name>approvertimeout</name> <defaultValue>P1D</defaultValue> <prompted>true</prompted> <required>false</required> <final>false</final> </attribute> <attribute> <name>approvers</name> <defaultValue>example.user,example2.user</defaultValue> <prompted>true</prompted> <required>false</required> <final>false</final> </attribute> <attribute> <name>payload</name> <defaultValue>defaultpayload</defaultValue> <prompted>true</prompted> <required>false</required> <final>false</final> </attribute> <attribute> <name>tasktitle</name> <defaultValue>Approval required to add a document to the team workspace</defaultValue> <prompted>true</prompted> <required>false</required> <final>false</final> </attribute> <attribute> <name>initiator</name> <defaultValue>beeadmin</defaultValue> <prompted>true</prompted> <required>false</required> <final>false</final> </attribute> </Attributes> </WorkflowTemplateInfo>
Example 12-6, "Parallel Vote Workflow Template XML File" shows an example Parallel Vote Workflow template XML file. The items in bold indicate the element values you should specify when creating a new parallel vote workflow template.
Example 12-6 Parallel Vote Workflow Template XML File
<?xml version="1.0" encoding="UTF-8" ?> <WorkflowTemplateInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xml.oracle.com/beehive/workflow/workflow_template.xsd" xmlns="http://xml.oracle.com/beehive/workflow" isfinal="false"> <name>Parellel workflow approval when documents are deleted from the WORKSPACE_NAME workspace</name> <collabid></collabid> <description>A Template for Parallel Workflow</description> <schemaname>ParallelVoteWorkflow</schemaname> <containerid>36CB:5780:wstm:DD649BD7DAA641CF811F5A7E1D9BA02D000000000037</containerid>
<templatekey>DOCUMENT_DELETE</templatekey> <Attributes> <attribute> <name>justification</name> <defaultValue>Request to delete a document in the WORKSPACE_NAME workspace</defaultValue> <prompted>true</prompted> <required>false</required> </attribute> <attribute> <name>workflowtimeout</name> <defaultValue>P1D</defaultValue> <prompted>true</prompted> <required>false</required> </attribute> <attribute> <name>approvertimeout</name> <defaultValue>P1D</defaultValue> <prompted>true</prompted> <required>false</required> </attribute> <attribute> <name>approvers</name> <defaultValue>jamie.rancourt,tait.mccarthy</defaultValue> <prompted>true</prompted> <required>false</required> </attribute> <attribute> <name>payload</name> <defaultValue>defaultpayload</defaultValue> <prompted>true</prompted> <required>false</required> </attribute><attribute> <name>initiator</name> <defaultValue>beeadmin</defaultValue> <prompted>true</prompted> <required>false</required> </attribute> <attribute> <name>tasktitle</name> <defaultValue>Request to delete a document in the WORKSPACE_NAME workspace</defaultValue> <prompted>true</prompted> <required>false</required> </attribute> <attribute> <name>votepercent</name> <defaultValue>51</defaultValue> <prompted>false</prompted> <required>false</required> </attribute> </Attributes> </WorkflowTemplateInfo>
A workflow template is used to configure a content operation to be driven by a workflow. The workflow that drives the operation can be a default workflow process (Parallel Vote or Serial), or it can be a custom workflow.
As with policies, you can use dynamic attributes in your custom workflow templates.
See Also:
Using Dynamic Policy AttributesYou can use any of the actions listed in Table 12-2, "Oracle Beehive Workflow Template Keys" in your workflow template. In the following example, the DOCUMENT_DELETE
template key is used:
<?xml version="1.0" encoding="UTF-8" ?> <WorkflowTemplateInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xml.oracle.com/beehive/workflow/workflow_template.xsd" xmlns="http://xml.oracle.com/beehive/workflow" isfinal="false"> <name>My Dynamic Workflow</name> <collabid></collabid> <description>This workflow uses dynamic attributes</description> <schemaname>Name of the Workflow Schema (ParrallelVoteWorkflow, SerialWorkflow, or Custom)</schemaname> <containerid>36CB:5780:wstm:DD649BD7DAA641CF811F5A7E1D9BA02D000000000037</containerid> <templatekey>DOCUMENT_DELETE</templatekey> <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> </WorkflowTemplateInfo>
You must replace the attribute1
to attribute n
values of the <name>
elements with the parameters of the workflow. For example, for ParallelVoteWorkflow, attribute1
to attribute n
would be justification, vote percent, and so forth. These values can come from the following sources:
Values provided by the user for attributes that are marked as prompted
Default values provided in the default templates
Dynamic workflow template attributes
To use a dynamic workflow template attribute, set the default value to be one of the following string constants:
#workflow.entity: The name of the entity (document or folder) that is triggering this workflow
#workflow.container: The name of the container (workspace or folder) where the triggering entity resides
#workflow.srccontainer: The name of the source container (workspace or folder) in a copy or move operation
#workflow.dstcontainer: The name of the destination container (workspace or folder) in a copy or move operation
#workflow.initiator: The name of the actor who caused the event which triggered the workflow
#workflow.startdate The date, in string format, when this workflow was triggered. The format is the same as calling Date.toString().
For example, to trigger a workflow that has a parameter called docname
with the actual document name, the template could have the following attribute:
<attribute> <name>docname</name> <defaultValue>#workflow.entity</defaultValue>
At runtime, the #workflow.entity
will be replaced with the actual name of the document.
You can list the workflow templates currently implemented in a given context (workspace or folder) with the
command:beectl
list_workflow_templates
beectl list_workflow_templates --scope <container where the workflow is configured> --template_key <workflow template key>
Specify the template key to list all workflow templates in that container that are triggered by that template key.
When you list a workflow template, its unique identifier is also listed.
You can export a workflow template. This creates an XML-formatted file (in a location you specify), which you can then review or edit. Export a workflow template by using the
command:beectl
export_workflow_template
beectl export_workflow_template --workflow_template <identifier of the workflow template to be exported> --destination <destination directory of the generated xml file>
Specify the unique identifier (found by using the list_workflow_templates command) of the workflow template you want to export to a file.
You create a workflow template by uploading an XML-formatted Workflow Template file to Oracle Beehive. To create a workflow template, use the
command:beectl
add_workflow_template
beectl add_workflow_template --file <full path to the workflow template xml file>