Posts in Category "Review Commenting and Approval Building Block"

Create a custom process that initiates a new review process


At the end of this exercise you will be able to create a new process that initiates a review process.


Using eSubmissions review portal, you can create review template and initiate Review Commenting and Approval workflow (to know more, read my previous post). Essentially, even eSubmissions web UIs talk to Review Commenting and Approval (known as RCA) building block apis for all the backend processing.

The Review, Commenting and Approval building block is a set of services, samples, processes,
and APIs that extend the functionality of LiveCycle ES for building structured and auditable
review and approval solutions.

In this article, I will discuss how to initiate a RCA process using LiveCycle processes. This will showcase the use of core RCA apis and can come handy when integrating RCA with other applications.

I have divided the whole exercise into two phases.

Phase 1: Initiate a RCA process using LiveCycle orchestration

Phase 2: Using RCA events to track the review completion and perform some post process completion chores.

Phase 1 – Initiate a RCA process using LiveCycle orchestration

To, initiate a RCA process, you need a review template. You can use any existing review template or create a new review template.

Review Template is just an XML

Review Template
is nothing but an XML. Review Template schema is published in RCA technical guide. So, creating a review template is just as easy
as creating any other XML. You can create a review template using any
XML editor, you can also create review template using LiveCycle

Once a review template XML is created, you can store it in Review Zone using RZP apis.

RCA stores review templates and all other content like in progress review documents,  supporting documents etc in Review Zone. To know more about review template & supporting documents, please read my previous post.

What is a Review Zone

Review Zone is a storage area for -

  • Review templates
  • Original Review Documents
  • Comments
  • Tracking sheets
  • Supporting documents

ReviewZoneProvider (RZP) interface defines abstract set of apis that can be used to store and retrieve content from the persistence store.

Two default RZP implementations are provided:

  •  File System Based
  •  LiveCycle Content Services Based

Any new custom implementation that conforms to RZP interface can be defined and plugged into RCA system. There can be only one active RZP implementation as service “ReviewZoneProvider”. 

In this article, I will use an already existing review template. You can create a review template using eSubmissions review portal (to know more read here). Once the template is created, you can create a process that will use that template.

Creating the process

1. Create a new short lived process called InitiateReview under any process category.
2. Create the following variables:

Name                                          Type                            Purpose
xmlReviewTemplate                      XML                           
inDocToReview                             document                   Input
strReviewID                                   String                         Output
initiator                                          User
strTemplateName                          String                         Input
strInitiatorEmail                              String                         Input

3. Add the getReviewTemplate operation from the ReviewZoneProvider service within the BB-Review Commenting and Approval category (make this a start activity). In the properties view:

a. Set the Review Template Name to the strTemplateName variable.
b. Set the Review Template Document to the xmlReviewTemplate variable.

Now, you need to set some additional properties in the review template, before we can pass it to initiateReview operation.

Note: The initiateReview operation requires the review template to
contain the canonical name of the initiator. The Find User service can
be used to return the canonical name for a particular user in LiveCycle.

4. Add a Find User operation from the User Lookup service within the Foundation category.

a. Set the Email property to a strInitiatorEmail variable in the Filter section.
b. Set the User property in the Result section to the initiator variable created in step 4.

6. Add a SetValue operation to set the following information in the review template xml:

  • /process_data/xmlReviewTemplate/review_context/initiator/@domain = /process_data/initiator/object/@domainName
  • /process_data/xmlReviewTemplate/review_context/initiator/@canonical_name = /process_data/initiator/object/@canonical_name

7. Add the initiateReview operation from the RCA Core Service service within the BB-Review Commenting and Approval category.

a. Set the Review Context to the xmlReviewTemplate variable.
b. Set the Review Document to the inDocToReview variable.
c. Set the Review ID to the strReviewID variable.

8. Connect all the operations in the same order in which these were added (as mentioned above).

9. Save, activate and invoke the process using the Invoke Process … menu.

10. Set the inDocToReview to the PDF to be reviewed. You can browse to the file on your local drive.

11. Set the strReviewTemplate to the review template name created using eSubmission review portal

12. Set the strInitiatorEmail to the email address of the initiator.

13. Hit the Ok button.

14. The strReviewID should contain a valid id if the review has started successfully (ex. R-20090818-084018-234-8920). A new folder with the same name should be created in the review zone.

Now, you have created the process that can initiate a RCA process. You can use eSubmissions Review Portal to track the progress of the process. But, what if you want to automate some task let’s email notification, on process completion or say stage completion. Here begins the phase 2.

Phase 2 – Using RCA events to track the review completion and perform some post process completion chores.

RCA has the capability to throw the events at various pre-defined check points like at start stage, at stage completion, on task assignment, on task completion, on review complete etc. For a complete list of events and the respective event schema, please refer to RCA technical guide. You can also see the list of available RCA events displayed under the Events view or from the Event option from the toolbar in workbench.

By default RCA, throws only ReviewCompleteEvent (on RCA process completion). If you want RCA to throw other events as well, you can do the following:
  1. Login to LiveCycle adminui
  2. Navigate to Services -> Applications & Services -> Service Management
  3. Search for “RCACore” service. Click on the service name.
  4. Select Throw LC Events check box and Click on save button.
You can also set the above configuration using workbench as follows:

1. Open the Component view in Workbench.
Note: The view might not be visible in Workbench. Go under Windows/Show View/Component to add the Component view to the Workbench interface.
2. Expand the list of components and expand RCACore.
3. Expand Active Services and right click on RCACore:1.0 and select Edit Configuration …
4. Make sure the Throw LC Events checkbox is checked.

Using this event mechanism, you can do various things like sending email/sms notifications, archive the review documents after every stage, trigger any other workflow post review completion etc.
You can create a LiveCycle process that listen for the particular RCA event and then perform the required task. In this exercise, I will show how you can modify the process created in phase 1, so that it waits till the review process completes.

Modifying the process

  1. Select the InitiateReview process (created in phase 1) from the processes view in workbench.
  2. Right click and select properties from the menu. Go to advanced tab and change the type drop-down to long-lived. (As it would be waiting for the events, so this has to be long lived process now).
  3. Add another process variable named revision of type int.
  4. Add another process variable names reviewStatus of type string.
  5. Open the process for edit. Drag the Event option from the toolbar on the process and choose Select an event.
  6. In the Find area type review.
  7. Select ReviewCompleteEvent and select Ok. Select the event behavior as Receive.
  8. Select the event Filter tab (if not already selected) in event properties.
  9. Expand the ReviewCompleteEventData in the Filter Keys Data Set text area.
  10. Double click on reviewId from the Filter Keys Data Set text area and equate it to /process_data/@strReviewID in the Event Data Name field and click Add. This will set the filter, so that it only receive events for the review initiated by this process.
  11. Now, go to the Callback – Process Data Map tab. Here, you can retrieve the values from the event payload and set it in process variables.
  12. Expand the ReviewCompleteEventData in the Source Data Set text area.
  13. Double click on revision from the Source Data Set text area and equate it to /process_data/@revision in the Process Data Name field and click Add.
  14. Double click on status from the Source Data Set text area and equate it to /process_data/@reviewStatus in the Process Data Name field and click Add.
  15. Now the event configuration is complete. Connect initiateReview operation to ReviewCompleteEvent operation.

The process is now ready to initiate a review and wait for review complete event. You can add any operation after ReviewCompleteEvent opration to do any post processing. In this exercise, I will show you how to retrieve the review context once the process is completed.

What is a review context
Review context is a structure in XML form, to hold the runtime context of the RCA process. When a RCA process is initiated, review template (with additional information like initiator) is passed in as review context, then as the RCA process takes its course, review context keeps growing.
XML Schema for review template and review context is same. At any point of time, review context of a particular RCA process gives the snapshot of that process. During the course of review and approval process, RCA adds information like task completion time, task assign time, reviewer status, approver status etc to the context.
Review Context is stored in review zone and can be retrieved any time, using RCACore api.

To retrieve the review context.

  1. Add getReviewContext operation from RCACore service within the BB-Review Commenting and Approval categ
  2. Add another variable named “reviewContext” of type xml.
  3. Set Review Id property to strReviewID variable.
  4. Set revision property to revision variable.
  5. Set Review Context property to reviewContext variable. 

You can now retrieve various information like number of stages etc from the review context. Then you can use various RCACore operations to retrieve original review document (the one with which the review was initiated), stage review documents etc from review zone.

To enable Acrobat shared commenting for review stage, RCA injects javascript into the review document and create a review enabled document. If comments are not shared across stages (this option should be selected while creating review template), every stage has its own copy of review enabled document. This is what I have referred as stage review document.

In this article, you have learnt how to create a custom process, how to work with RCA events. You have also got some information about concepts like Review Template, Review Zone, Review Context.

eSubmissions review portal also uses the same approach. It invokes a process called ReviewDocumentManager within Review Commenting And Approval -UI category, which in turn invokes RCACore initiateReview operation. You can explore the same process also, to see use of some more RCACore apis. ReviewDocumentManager also waits for ReviewCompleteEvent and do post completion activities that can also serve as an example.

I am attaching the final process created in this exercise for reference

Review Commenting and Approval Building Block

This series of articles provides you with tips, tricks and all you wanted to know about the Review Commenting and Approval Building Block.

Following new entries have been added:
Create custom process to initiate a RCA process