Archive for August, 2009

Create a custom process that initiates a new review process

Objective

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

Overview

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
Orchestration.

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).
process.JPG

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.
RCAConfiguration.JPG
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.
    eventview.JPG
  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.

process2.JPG
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
    ory.
  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
InitiateReview.1.0.xml

Announcing the release of the Government Benefits and Services Delivery Solution Accelerator for LiveCycle ES

The solution accelerator team is pleased to announce the release of the Government Benefits and Services Delivery Solution Accelerator. The solution accelerator is designed to be extended and customized by partners leading to reduced development time and increased quality. The accelerator is packaged with a set of production ready building blocks that consist of re-usable components and technical guides. The building blocks may be used within the context of a solution accelerator or form the basis for developing new solutions.

With the universal Adobe Reader and Flash Player, Adobe solutions have been critical in helping government agencies provide electronic channels for citizen and business services enrollment. With Adobe LiveCycle ES and the Adobe Benefits and Services Delivery solution accelerator, you can simplify citizen and business services enrollment, increase productivity by streamlining data collection and sharing across agencies and service providers, and ensure compliant correspondence on services eligibility and determination. This solution accelerator includes a set of Flex components and sample LiveCycle forms which can help you deliver Section 508 accessibility compliant portals for finding, selecting and applying for services such as health and human services, grants, child welfare, unemployment and business registration.

Connect presentation:http://my.adobe.acrobat.com/BenefitsAndServicesDelivery
Solution Guide: http://www.adobe.com/government/pdfs/adobe_benefits_services_delivery_portfolio.pdf
Further details: http://www.adobe.com/devnet/livecycle/solutions/gov_benefits.html

For further information including referencing the technical documentation or to download these new releases, please visit http://www.adobe.com/devnet/livecycle/solution_accelerators.html. Your feedback, suggestions, and questions are greatly appreciated.

Ashish Agrawal
Group Product Manager

Loni Kao
Group Solutions Manager, Government Solutions

Design a Document review & approval workflow using eSubmissions – Part 2

In the first article, we discussed how to create a review commenting and approval template. In this article, we will talk about “how to initiate a Review Commenting and Approval process

Initiating a Review Commenting and Approval process
To initiate a RCA process, you can log in to eSubmissions’ review portal using your credentials. Review Portal is a one step portal for authoring, initiating and tracking review, commenting and approval (referred as RCA hereafter in this document) workflow.

Once you log in to review portal, navigate to “Initiate Review” tab. You would see a list of all the active templates.

To initiate a RCA process, please select desired review template.

Selecting a template
review-template9.JPG

Once you select a template, initiate wizard would start.

Defining the Review Title and Description

review-initiate1.JPG

Provide a title for the Review Title and description and click next. Please note that regulation value can not be changed here, values entered at RCA template creation level can not be edited or modified while initiating the RCA process.

Stages and Timelines
Next screen would display the list of stages and speculated timelines for each participant in every stage. In case of serial review/approval stage, total duration of stage would be equally divided in all the participant. Please note that this is not the actual time line, only speculated time based on the total duration of the stage.

In a serial review/approval, if a participant consumes most of the time allotted to that stage, then moderator/initiator can use review dashboard and increase the duration of the stage on need basis.

review-initiate2.JPG

Adding Participants
You can add more reviewers/approvers/moderators by clicking “Add Participant” button on the above screen.
review-initiate3.JPG

Please note that you can not remove/modify the participants added template creation level.

Supporting Documents
You can add supporting documents at the time of initiation, to read more about supporting documents. Please read part1 of this series.

review-initiate4.JPG

After adding supporting document, click next to go to next step.

Adding Content for Review Commenting and Approval
The final step is to add main content that is to be reviewed and/or approved. You can browse and add multiple documents on this screen, those documents will be converted to pdf. And, combined into a single document. That final master document will be passed to RCA workflow.

Please note that for PDF conversion to work, necessary LiveCycle components should be installed on server.
review-initiate5.JPG

Once you click finish button, RCA workflow would be triggered. Required participants in RCA process would receive email notifications from time to time about the progress of the process.
Upon initiation, stages would execute in sequence. First the reviewer/approvers in the first stage would be assigned the tasks. To see the task, user would have to login to LiveCycle Workspace. To see the progress of RCA process, you can use eSubmissions Dashboard. Dashboard applications is just another tab within review portal.

In coming articles, we would try some more advanced options while creating RCA template.

Design a Document review & approval workflow using eSubmissions- Part 1

Electronic Submissions Solution Accelerator enables the rapid delivery of managed and auditable review, commenting and approval solutions.

In this article (first in its series), I will explain how to design a multi-user and multi-stage review and approval workflow.

First Step
First Step in defining a review and approval workflow is to define a review template.

Review Template
A review template can be considered as a logical grouping of the review attributes and is identified with a user friendly name, for example, Floor Plan Review Template.

The review administrator will define multiple such review templates. These templates can be modified or deleted if needed.

Defining a Review Template
To create a review template, you can log in to eSubmissions’ review portal using your credentials. Review Portal is a one step portal for authoring, initiating and tracking review, commenting and approval (referred as RCA hereafter in this document) workflow.

Once you log in to review portal, navigate to Templates tab. It will show you all the existing templates. To define a new template, click on new. Clicking on new would start the following wizard that would guide you through creating a review template.

Template Definition

review-template1.JPG

Enter Template Name say “Demo Template” and description on the “Template Definition” screen and click next.

If you do not want this template to be used for initiating RCA processes. You can uncheck “Active” checkbox, this would keep the RCA template in kinda of draft state (upon saving). Or in other words, only active templates would be available while initiating a RCA process, So, to avoid your template appearing in the list of available templates under “Initiate Review” tab, you can uncheck the “Active” checkbox.

Leave other fields as it is, we will discuss these in later articles in the series.

Commenting
On the next screen in the wizard, define the comments visibility. For now, you can just click next and let the default value be taken. We will come back to this a little later.
review-template2.jpg

Stage Building
An Enterprise can define multiple stages of review for a kind of review. Each stage may involve one or many reviewers.

For example, a new business plan may require following reviews:

  1. Technical review – to assess the technical feasibility of the business plan
  2. Business review – to assess the business viability of the business plan
  3. Legal review – to assess if the business plan is legally sound in the jurisdiction where the business is supposed to take place

Each stage of review/approval is carried out in sequence. Each stage will have at-least one moderator. Within each stage, there can be one or many reviewers. Each stage may define the review/approval to be sequential or parallel.

review-template3.JPG

Select Stage type as “Parallel Review” from the type drop down.
Provide a name to the stage “Frist Review Stage”.
Click on “create” button. This will take you to next screen to define other stage attributes like duration, pre/post process, reminder configuration etc.

review-template4.JPG

Provide duration for the review, enter number of days. Reminder can be configured additionally if you want. Click on next to go to next step

You can leave pre-review process and post-review process as it is, we will discuss these more advanced options in coming articles in this series.

Next Step is to Add Reviewers

On this screen, you can search for users configured in your LiveCycle Server and add those users as reviewers or moderators. Please note that a stage require at least one moderator and one reviewer to initiate a review. So, you can choose not to select any moderator or reviewer at template creation level, but then you must select at least one moderator and one reviewer at the RCA initiation time. We will again discuss this, when we will talk about initiating a RCA process.

review-template5.JPG

while adding a reviewer, you can select whether the review is mandatory or optional. By default every reviewer is mandatory, you can choose to make some reviewer optional by selecting optional from the drop down.

A review stage is marked as complete only when all the mandatory reviewers have completed their review tasks. If a stage duration is expired, the stage is marked as expired and all tasks assigned to reviewers are pulled back from their queues. if any stage in a RCA process expires, the complete RCA process is marked as expired.

So, this means RCA process would proceed to next stage, when all the mandatory reviewers have completed their review task. If instead, you want RCA process to wait till the full duration of stage, irrespective of whether all the reviewers have completed, you can select “continue review for specified duration regardless of completion” on previous stage definition screen.

After adding the reviewers on this screen, you can click “Add New Stage” button to add another stage.

On the screen add, stage name as “Second Stage-Approval” and select type as “Parallel Approval” from the drop down. Adding an approval stage is almost similar to adding review stage, only some of the terminology changes. Click on create button to take you to the next screen.

review-template6.JPG

In case of approval , you can also define what type of signature is required. We will discuss use of signature in approval in coming articles, for now, we can leave it as “None” and proceed to next screen.

On the next screen you can add and select approvers and moderators for this stage. Please note that a stage require at least one moderator and one approver to initiate a RCA process. So, you can choose not to select any moderator or approver at template creation level, but then you must select at least one moderator and one approver at the RCA initiation time. We will again discuss this, when we will talk about initiating a RCA process. After adding approvers and moderators, you can click next to go to next step in defining template.

Supporting Documents
Supporting documents serves the purpose of reference documents for the main document in the RCA process. Supporting document can be a link also, to support cases, where may be an already existing link on intranet or internet is to be used as supporting document. Alternatively, supporting document can be uploaded from your local system as well.

Supporting documents can be supplied at the template creation level or at the RCA initiation level. Supporting documents, supplied at template creation level, are available to all the RCA processes which are initiated from that template. So, at template creation level, you might want to supply those supporting documents that applies to all RCA processes initiated from that template e.g. any compliance code specification document, any other protocol specification document etc.

review-template7.JPG

After adding supporting documents, click next to reach next step. This screen can be skipped as of now, we will discuss this in coming articles. To skip the screen click next and we reach the final screen.

Audit Levels
You can select any of the existing Audit Levels and click finish to save the template. You can also define your custom audit levels, but that is outside the scope of this article series.
review-template8.JPG

You can verify that newly created template appears on first screen under “Templates” tab in review portal. You can modify/view/delete the template from there.

Now, you have created a RCA template. The next step is to initiate a RCA process using this template. How to initiate a RCA Process will be covered in part 2 of this article.