21 Setting Up an Approval Chain

This section discusses how to set up a chain of approval that documents must pass through before they are posted publicly (or to a specified group). It includes the following subsections:

Setting Up an Approval Process for a Page
Enabling Users to Subscribe to a Page or Item
Troubleshooting Approval and Notifications

Before you can set up an approval chain, approvals must be enabled for the relevant page group. You'll find information on how to do this in Section 6.4, "Setting Up Approvals" in Chapter 6.

Intended Audience

The content of this chapter is intended for users with at least the Manage privilege on the pages you will work with. If a particular task requires, or can be performed under, different privileges, those privileges will be listed before the steps of that task. For more information on page privileges, see Section B.3, "Page and Tab Privileges".

You'll find additional information related to the Approval and Notification process in Section 6.4, "Setting Up Approvals".

21.1 Setting Up an Approval Process for a Page

Once approvals are enabled for your portal, you can define an approval process. An approval process consists of one or more steps in which a newly created or updated item must be approved before it can be published. When a step in the approval process includes multiple users, groups, or both, you can specify whether:

The notification is sent to that step's approvers one at a time in the specified sequence, and all of the approvers must respond before the item is routed to the next step.
The notification is sent to that step's approvers all at the same time, and all of the approvers must respond before the item is routed to the next step.
The notification is sent to that step's approvers all at the same time, and only one of the approvers must respond before the item is routed to the next step.

At any point, a page group administrator or content manager can approve or reject a pending item. On approval by the portal administrator, the process skips the current approver and moves onto the next approver. On rejection, the approval process ends. This is a useful way of bypassing a user in an approval process who is unavailable.

The approval process can be modified so that users can add draft versions of an item without immediate approval. Draft items are only visible to the item owner, who can submit the item for approval, once it is finalized. See Section 2.7.1.1.3, "Submitting a Draft Item for Approval".

You can also extend the approval process to all users contributing content to the page, instead of just those with the Manage Items With Approval privilege.

Approvals can be enabled at the page group and page level. A page-level approval process overrides that of the page group, and sets up an approval process that is unique to the page.

To set up an approval process for a page, you must enable two options at the page group level: Enable Approvals and Notifications and Override the Page Group Approval Process. The Override option automatically adds an Approval tab to the Properties page of all standard pages created in this page group.

For users to receive notice of an approval, they must place a Notifications Portlet on one of their pages. For more information, see Section 2.7.2.1, "Setting Up the My Notifications Portlet to Show Approval Status".

To set up an approval process for a page:

Go to the page where you will define an approval process.

For information on locating a page, see Section 9.1, "Locating Pages in OracleAS Portal".
Switch to Edit mode.
Click the Properties link next to Page in the page toolbar.

Be sure to click the link for the page rather than the page group.
Click the Approval tab to bring it forward.

Select Define a New Approval Process for the Page.

The Approval Routing List section now appears.

Note:

If you do not select this option, the page uses the approval process defined for the page group.

If you select this option and then do not define an approval process for the page, users with the Manage Items With Approval privilege will be able to add items to the page without requiring approval.

In the Approvers field in the Approval Routing List section, select one or more approvers (users or groups) for the first step of the approval routing list.

Click the Users or Groups icon to add a user or a group. If you type in user and group names manually, check spellings carefully to avoid invalid entries.

Note:

Each step of the approval routing list can include both users and groups. Use a semicolon (;) as the separator between multiple users and groups.

Do not use the same approver in more than one step. Any additional times the approver is listed, he or she will be skipped.

OracleAS Portal provides the following special approvers:

#PAGE_GROUP_MANAGER#: Any user or group with the Manage All privilege on the page group, or the Manage All global level privilege on all page groups.
#PAGE_MANAGER#: Any user or group with the Manage privilege on the page.
#CONTENT_MANAGER#: Any user or group with the Manage Content privilege, or the higher-level Manage privilege, on the page.

OracleAS Portal uses the Oracle Internet Directory for identity management, serving as the repository for users and groups. In the Oracle Internet Directory, groups are uniquely identified by their distinguished name (DN). Each group has a unique DN, though many groups can share a common name, in the same way that two people can share a common name, yet have completely different lineage (for example, John Smith and John Doe). When working within the portal, groups created from within that portal are displayed simply with their common names. However, when the portal references a group from some other location in the Oracle Internet Directory—such as a group from some other portal associated with the same Identity Management Infrastructure—the DN of the group is displayed to distinguish it from the portal's locally defined groups.

In the Routing Method for Approvers list, choose a routing method for the approval routing list:
- One at a time, all must approve (Serial, All)—This sends the approval to approvers in the step one at time in the sequence specified. All of the approvers must respond to the approval.
- All at the same time, all must approve (Parallel, All)—This sends the approval to approvers in the step all at the same time. All of the approvers must respond to the approval.
- All at the same time, only one must approve (Parallel, Any)—This sends the approval to approvers in the step all at the same time. Only one of the approvers must respond to the approval.
Click Add Step to continue adding steps to the approval routing list.

For each step, select approvers and a routing method. Each step you add is listed in the Current Approval Process section. You can edit existing steps by clicking the list of users and groups, or the Edit icon. When you edit a step, the step details are displayed in the routing method section and the Add Step button changes to Update Step.

Select Enable Item Drafts to enable users with the Manage Items With Approval privilege to add draft versions of items to this page, without having to submit them for approval.

Draft items are visible only to the item owner in the Pending Items Preview and List editing views. Once the draft is finalized, the user can submit the item for approval from the Actions page. Once enabled, this option cannot be disabled until all draft items in this page are submitted for approval.

If you do not want to allow content contributors to upload draft items without approval, do not select this option.

Note:

Regardless of whether Retain Deleted Items is enabled for the page group, when you delete an item with the status Draft, it is irrevocably deleted from the portal. The only way to restore the item is to add it to the page once again.

Select All Users Require Approval if every content contributor requires approval.

By default, this option is not selected which means that only users with the Manage Items With Approval privilege require approval.
Click OK when the approval routing list is complete.

An approval routing list is now defined for the page.

If there is an active approval process pending for an item, the approval routing steps for the item cannot be reordered. If the approval routing list is changed at the page group or page level, it does not affect the process pending for the item. However, the administrator can still delete routing steps and edit the recipients in individual steps of the pending process (but cannot reorder the steps).

21.2 Enabling Users to Subscribe to a Page or Item

You can enable users to subscribe to a page or items on a page, so that they can be notified whenever that page or item is updated. Note, however, that subscriptions are not possible unless Enable Approvals and Notifications is enabled for the relevant page group.

You can add the Subscribe link or icon to any page or region at any time. However, the Subscribe link or icon is visible only if the page group administrator has enabled approvals and notifications for the page group. See Section 6.4.1, "Enabling Approvals and Notifications for a Page Group".

Additionally, to enable users to subscribe to a page, you must have at least Manage Content privileges on the page. To enable users to subscribe to an item, you must have at least Manage privileges on the page that contains the item.

Enabling Users to Subscribe to a Page

Subscribing to a page automatically subscribes a user to every item on that page. To enable users to subscribe to a page:

Go to the page you will work with.

For information on locating a page, see Section 9.1, "Locating Pages in OracleAS Portal".
Switch to Edit mode.
Click the Add Item icon in an item region.

If the page does not have any item regions, you will need to add a new region to the page and make that region an item region.

Even if there is already an item region in the page, you may want to create a new region at the top of the page specifically for the Subscribe link. If the page includes a navigation page, you may want to consider adding the Subscribe link to the navigation page instead of the page itself.
From the Built-In Navigation Item Types list, select Portal Smart Link.
Click Next.
In the Portal Smart Link list, choose Subscribe.
If you want to use the default label for the Subscribe link, select Use The Default Display Name.

Using the default display name means that the display name will be automatically translated if users view the page in a different language.

When you select this check box, the Display Name field is cleared.
If you want to provide your own label for the Subscribe link, enter it in the Display Name field.
If you want to use an image instead of a label:
1. Provide the name of the image in one of the Image fields:
  
  You can add images in the JPEG, GIF, or PNG formats.
  
  In the first field, click the Browse button to locate and select a file on your file system.
  
  OR
  
  In the second field, either enter the URL and file name of an image on the Web, or enter the internal name of an image already uploaded to OracleAS Portal, for example 1655.gif. To get the internal name of the image, right-click the image in your portal, and select Properties from the resulting menu.
  
  If you are using item versioning and you always want to show the current version of an image—whether the image is the item itself or an attribute associated with the item—use the image's durable URL instead of the internal file name. The durable URL always picks up the latest version of the image. For more information, see Section 15.12.4, "Images and Item Versioning".
2. In the Image Alignment field, choose how you want the image to be aligned within the region.
  
  For descriptions and examples of image alignment options, see Table 14-1, "Item Image Alignment Options" in Chapter 14.
Click Finish.

Users can now click the Subscribe link to be notified whenever that page is updated. Subscribing to a page automatically subscribes a user to every item on that page.

Users are notified through the My Notifications portlet of the changes to pages or items they have subscribed to. Users must have access to a page that includes the My Notifications portlet. Also, the My Notifications portlet must be set up to display subscription notifications. See Section 2.4.3, "Setting Up the My Notifications Portlet to Show Your Subscriptions".

Enabling Users to Subscribe to an Item

To enable users to subscribe to an item:

Go to the page you will work with.

For information on locating a page, see Section 9.1, "Locating Pages in OracleAS Portal".
Switch to Edit mode.
Click the Edit icon in the region you will work with.
Click the Attributes tab.
From the Available Attributes list, select Subscribe.
Click the Move icon to move the attribute to the Displayed Attributes list.
Click Apply.

It is very important that you click Apply. If you do not click Apply, any changes that you make to the list of displayed attributes will be lost when you click Close.
Click Close.

Users can now click the Subscribe icon next to any item in the region to be notified whenever that particular item is updated.

Users are notified of changes through the My Notifications portlet. Users must have access to a page that includes the My Notifications portlet. Also, the My Notifications portlet must be set up to display subscription notifications.

If you include a Subscribe link on a template, all the pages that are based on the template will include the link. When users subscribe to the pages, they will receive notifications when the pages and the template itself are updated.

Enabling Users to Subscribe to Items on a Tab

If your page contains tabs, you can add a Subscribe link at the tab level. Subscribing to a tab automatically subscribes a user to every item on that tab.

Note:

Provide Subscribe links at the page level or the tab level, but not both. When a user subscribes to a page, the user is automatically subscribed to all items on the page (including items on tabs). If you provide a Subscribe link on a tab, it has no effect if the user is already subscribed to the page, and this behavior could be confusing for the user.

To enable users to subscribe to a tab:

Go to the page you will work with.

For information on locating a page, see Section 9.1, "Locating Pages in OracleAS Portal".
Switch to Edit mode.
Click the Add Item icon in the tab.
From the Built-In Navigation Item Types list, select Portal Smart Link.
Click Next.
In the Portal Smart Link list, choose Subscribe.
If you want to use the default label for the Subscribe link, select Use The Default Display Name.

Using the default display name means that the display name will be automatically translated if users view the page in a different language.

When you select this check box, the Display Name field is cleared.
If you want to use an image instead of a label, enter Image and Image Alignment details as described previously in Enabling Users to Subscribe to a Page - Step 9.
Click Finish.

Users can now click the Subscribe link to be notified whenever items on that tab are updated.

21.3 Troubleshooting Approval and Notifications

I'm defining my approval process, and Group IDs are being displayed instead of Group Names.

When a group from one instance of OracleAS Portal is added to an approval routing step in another instance, the group's internal ID may appear instead of its name. This may arise when a non-local group is selected in the Recipient(s) field on the Approval Routing page. Non-local groups are those that are defined and created in another portal instance. Non-local groups are included in the list when you search for All (instead of Local) when selecting a user group for an approval routing step. You cannot replace a non-local group's ID with the group name.

The approval process is not being triggered when I add or modify an item.

When the Require Approval for All Users option has been set at the page group or page level, the approval process initiates when any user creates or modifies an item. If this option is not set, the approval process begins only when a user with the Manage Items with Approval privilege creates or modifies an item. If the approval process is not initiating, check to see if:

The user who created or modified an item had a higher privilege level than Manage Items with Approval. In this case, the approval process will not (and should not) be initiated.
The user with the Manage Items with Approval privilege is also the owner of the page, or is the page group administrator. These higher privileges override the Manage Items with Approval privilege.

I modified an item that was pending approval. Will my modifications be lost?

Only a user who is an approver and has Manage Content or higher privileges can edit a pending item. The changes are made directly to the pending item. The modifications are not lost but will appear once the item is approved.

I uploaded a draft item but cannot see it on my page. Pending, rejected, and deleted rejected items are not displayed either.

Drafts do not display as expected when the page that contains the draft item is cached at the system level. To avoid access problems, do not cache pages (or templates) at the system level when Approvals and Notifications are enabled. See Section 22.1, "Page Caching".