Version: V7.1x & V7.2x

Modules: Governance

Product Area: Reviews

Note: A summary of all RSA IGL recipes can be found here: (TBC)

Time to apply: ~30 minutes

Summary:

This recipe combines web services and workflows to automate and control the review change request generation tasks. The recipe combines the benefits of both out of the box Automatic and Explicit review change request generation options with minimal configuration.

Background

The RSA IGL Reviews module provides 2 methods for generating change requests, as explained below:

1. Automatically

Since change requests are automatically created as soon as reviewers saves their decisions, you get the following:

Pros

• No additional administration overhead for the review owner or administrators to periodically generate change requests.

Cons

• There is no control over the timing of the generated change requests.
• There is no control over the grouping of change items.
• Reviewers have no margin for error since a change request is generated the moment they save their changes.

2. Explicitly by Owner

Since change requests are not generated until the review owner or administrator manually triggers the change request generation, you get the following:

Pros

• More control over the change request generation grouping (By Reviewer, By Component ... etc).
• More control over the time when change requests are generated (Daily, Weekly ... etc).
• Reviewers have the ability to review and change their decisions until the next change request generation task is run.

Cons

• Additional overhead of the review owner or administrators to manually start the change request generation process.
• Potential of missing a few changes if the review owner or administrator does not manually generate the change requests. 

Challenge

One of the most common requests we've seen is a solution that combines the benefits of both Automatic and Explicit change request generation. The requirements are mostly:

1. Having the ability to control the timing and grouping of generated change requests without requiring manual intervention from the review owner or administrators.
2. Giving reviewers a grace period - for example: until the end of the business day or end of the week - to change any decisions they took before any change requests are generated without requiring the review owner or administrators to perform manual actions outside business hours.

Suggested Solution 

We can leverage the createRequestsByOwner web service command which is used to generate change requests for a review. This is equivalent to the 'Create Change Requests' button found on the Change Preview tab of reviews that are configured to generate requests explicitly by owner.

Web Service Usage

Note: The below is only the relevant subset of the full web service description. For full usage details, you can go to Admin > Web Services > Requests > Click 'Click for details' beside the createRequestsByOwner web service.

Input Parameters

The command expects the following parameters where a * denotes a required parameter:

• id* - The id of the review result to create change requests for.
• group - Specifies how changes should be grouped together.
  • Reviewer, PerComponent, PerAsset valid for user reviews.
  • Reviewer, PerComponentResource, PerComponent, PerAsset valid for account reviews.
  • PerComponent valid for group and role reviews.
• format: The format to return the data in (default = properties)

 

Output Parameters

The command returns the following properties as output:

• name - name of the review.
• status - success or failure.
• message- Optional message to return along with the status.

A precondition failed (412) return code is returned if the review is not configured to generate requests explicitly by owner.

 

Example

An example url used to invoke this command is shown below:

https://<Hostname>:<Port>/aveksa/command.submit?cmd=createRequestsByOwner&id=1&group=Reviewer&format=properties

Calling the Web Service

There are two suggestions on how to call and schedule this web service:

Option 1 - Review Escalation Workflows

Using a Review Escalation workflow which calls createRequestsByOwner for the specific in scope.
Pros:

• Simple to implement and has better visibility on runs per review.
• Also easier to have different options/frequency per review.

Cons:

• Review Escalation workflows cannot be triggered in a recurring way (every day). So an escalation must be added per exection. Depending on the duration of the review, this could require a large number of escalation workflows.

Option 2 - Custom Task Workflows

Schedule a generic Custom Task workflow that calls the createRequestsByOwner for all open reviews.
Pros:

• A single workflow should work for all active reviews.
• Better scheduling frequency options.

Cons:

• Less visibility on runs per review.
• Extra complexity to control options/frequency per review type.

Implementation

Web Service Security Settings

Make sure you thoroughly test any changes in lower environments first before promoting them to Production.

Make sure you are on 7.1.1 P07 / 7.2.0 P01 or above to be able to call the web service from workflows without a token (Reference ACM-103573).

You need to make sure of two things:

1. Enable Web Services and whitelist the IGL server(s)' internal IP addresses.
   
    
2. Enable the "Request Forms and Workflows (no token)" checkbox for the createRequestsByOwner web service.
   

Workflow Configuration

Option 1 - Review Escalation Workflow

1. Create a new "per Review" Review Escalation Workflow
   
    
2. Configure a simple REST node that calls the createRequestsByOwner web service.
   
   REQUEST
   URL: https://<Internal-Hostname>:<Internal-HTTPS-Port>/aveksa/command.submit
   Method: GET
   Request Params:
   cmd: createRequestsByOwner
   format: properties
   group: <Grouping option of choice>
   id: ${jobUserData_acm.ReviewId}
   
   
   HEADER
   Content-Type: text/plain
   
   RESPONSE
   Proceed on failure: Checked
   Response Type: Properties
   Response Variables:
   status: Job, status
    
3. Add the escalation workflow to the Escalations tab of the review definition as much as required.
   Example running this workflow on a weekly basis for 4 weeks (28 days):
   

Useful Tip for Scheduling Review Escalation Workflows

Since Review Escalation Workflows do not have the ability to specify the exact time (hours and minutes) the workflow will run on a specific day, you can use a Delay node with SQL Delay that returns the today's date at a specific time.

For example, if you want the change request generation to be triggered at 9:00 pm. Then it can be calculated as follows: 

• trunc(sysdate) returns today's date at exactly 12:00 AM (00:00)
• + (day fraction) to add the exact time offset required. For example, 9:00 PM is 21:00 which means 21 / 24.

SELECT
    trunc(sysdate) + 21 / 24 AS wait_date
FROM
    dual‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Option 2 - Custom Task Workflow

1. Create a Custom Task workflow.
    
2. Add a SQL Select node that gets any non-completed Review ID that is configured to generate change requests explicitly by owner. Use the following SQL statement as an example:

   SELECT
       rv.id    AS review_ids,
       0        AS tmp_id
   FROM
            t_av_entreviewdefversions rdv
       JOIN pv_review rv ON rv.review_definition_id = rdv.id
                            AND rdv.generate_change_request = 'M'
                            AND rv.state IN (
           'InProcess',
           'InActionable'
       )

   ‍‍‍‍‍‍‍‍‍‍

    

3. Configure a Next Value node to loop through the Review IDs
   
    
4. Add a REST node with the same configuration as in Option 1 Step 2. The only difference is that the Review ID is now in the created Workflow Variable ${jobUserData_TMP_ID}
   
   
    
5. Make sure the two transitions coming out of the Next Value node are set to Completion Code.
   • True: Continue looping.
     
   • False: Finish process.
     
      
6. Schedule the Custom Task workflow as required.