Add an Approval Request Task

Add an approval request task to an agent when you want an event to occur only after approval. This task sends an approval request related to an event to the task inbox of specified recipients in IBM® Cognos® Analytics.

A recipient can be a potential owner or a stakeholder. Multiple users, groups, roles, and distribution lists can be assigned as potential owners of an approval request task. Stakeholders can be users, groups, roles, and distribution lists that are identified as interested parties, but are not potential owners.

Tip: To track the progress of an approval request task that you create, you can add yourself as a stakeholder.

You can include content, such as report output, in an approval request.

You can set up approval requests with different actions:

Approve/Reject the request
The task owner must approve or reject the request from their task inbox to complete the task. If you schedule further agent tasks to run after the approval request task, these are dependent on approval by the task owner. If the request is rejected, no further agent tasks will run.
Specify which of the remaining tasks to run
When you schedule further agent tasks to run after the approval request, the task owner must select which of those tasks to run on completion of the approval request.

You can add start date and due date deadlines to an approval request when you create the task in IBM Cognos Event Studio. Alternatively, potential owners or stakeholders can add deadlines at a later date by updating the approval request from their task inbox.

You can set up notification options for e-mails to be sent to

all potential owners when an approval request is created
the task owner when an approval request is not completed by the due date
the task owner when an approval request is not started by the start date

Note: Stakeholders are also copied on e-mails.

In addition, you can set up notification options for the task owner and all stakeholders to receive emails when

the status of an approval request changes (started, completed or canceled)
the owner of an approval request changes
a comment is added to an approval request

Note: Potential owners and stakeholders can unsubscribe from receiving specific notifications by updating the approval request from their task inbox.

You can add customized icons, using your own graphic files, to approval requests that appear in a recipient's task inbox.

To add a customized icon, use one of the following methods:

Type the explicit location and name for the graphic file.
Insert an item from the Insertable Items pane that contains a value for the relative path and name for the graphic file.

Files to support custom icons must be located within the c10_location\webcontent directory and a copy of the files must exist on all Cognos Analytics gateway server installs.

For example, to use the file green.jpg, where Cognos Analytics is installed in c:\program files\IBM\cognos\c10\, green.jpg must exist within a path contained within c:\program files\IBM\cognos\c10\webcontent\

When you configure a task to use green.jpg (located in c:\program files\IBM\cognos\c10\webcontent\samples\images\) as a customized icon, the value you enter in the icon Item box is either

./samples/images/green.jpg (explicit location)
or, an item from the insertable items pane which contains the value ./samples/images/green.jpg (relative location)

You can also add other types of tasks.

Procedure

Specify an event condition which always returns the value True. For example "1=1".
For more information, see Specify an Event Condition.
In the I want to area, click Add a task.
Click Run an approval request.
In the Potential owners box, and if applicable, in the Stakeholders box, enter the names of the recipients by using one or more of the following methods:
- If your model contains a data item that is a user, group, role or distribution list, drag this item from the source tab or from the data items tab. When the agent runs, the current value in the package replaces the data item for each event instance.
- Click Select the recipients to select the users, groups, roles or distribution lists.
  To choose from listed entries, click the appropriate namespace, and then select the required check boxes.
  
  Tip: To make the user entries visible, click Show users in the list.
  
  To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want.
  
  Click the Potential Owner or Stakeholder arrow button to update the Selected entries list, and click OK.
  
  Tip: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box.
  
  Click OK.
Note: You must add at least one stakeholder. By default, you are added as a stakeholder when you create the approval request.
In the Subject box, type the subject of the approval request.

Tip: You can also drag items from the source tab or from the data items tab. When the agent runs, the current value in the package replaces the data item for each event instance.
In the Body box, type text directly or drag items from the source tab or from the data items tab.

If you insert data items, the body message will be longer. When the agent runs, the current value in the package replaces the data item for each event instance. For more information, see How Multiple Events Affect E-mail Messages, Approval Requests, and Notification Requests.
To change the message format:
- Click Change to plain text to change from the default HTML format to plain text format.
  Note: If you switch to plain text format, any HTML formatting changes are lost.
- Click Change to HTML format to change from plain text to HTML. You can then use formatting buttons to edit the message.
To add attachments, click Attach and choose the attachments.
To add links, click Add links, select the entries you want, click the arrow button to update the Selected entries list, and click OK.
Select the following due date options if required:
- Start within to add a start by deadline, and then type the number of days in the Days box.
- Due within to add a due date deadline, and then type the number of days in the Days box.
To add a customized icon to the approval request in the task inbox, drag an item from the source tab or from the data items tab into the icon Item box.

Tip: To revert to using the default task icon, select the Default icon option.
To change the priority of the approval request, select a predefined option from the Priority list or drag an item from the source tab or from the data items tab into the priority Item box.
Select the action required by the task owner to complete the task:
- Approve/Reject the running of all remaining tasks (default)
  By default, the approval request contains Approve and Reject action buttons. To change the default button names, click Customize, type the required names, and then click OK.
- Specify which of the remaining tasks to run
  Select the tasks to include in the approval request.
  
  Note: Only agent tasks that are scheduled to run after the approval request are listed here.
  
  By default, the approval request contains a Submit action button. To change the default button name, click Customize, and type the required button name. When you have finished, click OK.
  
  Tip: You can also change the names of the agent tasks as they appear in the task inbox. For example, you could append the task type to the agent task name.
Select the approval request creation and deadline notification options as required:
- Send notification upon creation (default)
- Send notification if not started by start by date
- Send notification if not completed by due date
Select the approval request change notification options as required:
- Started
- Comment
- Owner changed
- Completed
- Canceled
From the File menu, click Save .

Results

You can preview the approval request task. When the agent runs, it retrieves values for all source and data items and sends the approval request to the recipients you specified.