Requirements

Prerequisite knowledge

LiveCycle services and process creation in Workbench and HTML; through understanding of the Managed Review and Approval Solution Accelerator.

 

Additional Requirements:

Solution Accelerators 9.5

User level

Intermediate

The Managed Review & Approval Solution Accelerator 9.5 adds a whole new level of efficiency to the review and approval workflow. The tracking capability of this tool is probably its most useful feature. If review tracking were done manually it would be near impossible to keep all records accurate and up-to-date. The solution accelerator is able to recognize when unique events occur and send notifications via e-mail to the respective recipients. This feature allows Managed Review & Approval to surpass manual systems.

However, due to the construction of the processes, when more than one recipient should be receiving and e-mail notification for a specific event the system will serially send out the e-mail to each individual. That individual as a result will not be able to see the other participants involved unless they access the Review Portal. The basis behind this customization is to allow recipients of an e-mail to see who else has received it. This will prevent the certain people from receiving a collection of unnecessary forwarded e-mails.

This article shows how to customize the process to allow recipients of an e-mail to see who else has received it.

Create the processes required to find participants

The AssignTasktoReviewer and AssignTaskToApprover (see Figure 1) processes is where a customization of this nature could be implemented. This is because the Reviewer Task is assigned to Workspace in the process and thus the customization should take place directly preceding the Task Assignment.

The existing variables don't allow us to reach into the proper Review Context to access the list of participants. As a result a new process is required to get this needed information. Since this function will have a separate functionality to the task assigning processes it would be best practice to separate the functions into different processes and then integrate the sub-function into the main process.

To parse the review context XML the way we would like, it is most efficient to write a quick custom component in Java and install its service. Please refer to the Programming with LiveCycle ES2.5–Developing Componentsto find more detailed documentation on how custom components are configured and should be installed.

First we must define the the interface for our service. I named mine ParseService.

package com.adobe.livecycle.participantsService; import org.w3c.dom.Document; public interface ParseService { /** * @param Document context - the REVIEW CONTEXT * */ public int numberOfReviewers(Document context) ; public int numberOfApprovers(Document context) ; }

The next step is to include the ParseServiceImple.java class which will have the implementations of all the necessary functions.

package com.adobe.livecycle.participantsService; /*Alexandra Phillips - Summer 2011 * participantService Custom Component */ import org.w3c.dom.Document; import org.w3c.dom.Element; import org.w3c.dom.Node; import org.w3c.dom.NodeList; public class ParseServiceImpl implements ParseService { /* * This custom component was created to traverse the review context XML file and return the number * of reviewers or approvers in the current stage. */ // NUMBER OF REVIEWERS public int numberOfReviewers(Document context) { int result = -1; NodeList stageList = context.getElementsByTagName("stage"); NodeList currentValue = context.getElementsByTagName("current_stage"); Node tempNode = currentValue.item(0); Integer currentStageNum = Integer.parseInt(tempNode.getTextContent()) -1 ; //Current Stage Node Node currentStage = stageList.item(currentStageNum); if(currentStage.getNodeType() == Node.ELEMENT_NODE){ Element eElement = (Element) currentStage; NodeList reviewers = eElement.getElementsByTagName("reviewer"); result = reviewers.getLength();} return result; } // NUMBER OF APPROVERS public int numberOfApprovers(Document context) { int result = -1; NodeList stageList = context.getElementsByTagName("stage"); NodeList currentValue = context.getElementsByTagName("current_stage"); Node tempNode = currentValue.item(0); Integer currentStageNum = Integer.parseInt(tempNode.getTextContent()) -1 ; //Current Stage Node Node currentStage = stageList.item(currentStageNum); if(currentStage.getNodeType() == Node.ELEMENT_NODE){ Element eElement = (Element) currentStage; NodeList approvers = eElement.getElementsByTagName("approver"); result = approvers.getLength(); } return result; } }

For the final classes, we must create a LivecycleImple and BootStrapImpl classes.

The LivecycleImpl.java class:

package com.adobe.livecycle.participantsService; import java.util.logging.Level; import com.adobe.idp.dsc.component.ComponentContext; import com.adobe.idp.dsc.component.LifeCycle; import com.adobe.logging.AdobeLogger; public class LifeCycleImpl implements LifeCycle { private static final AdobeLogger logger = AdobeLogger.getAdobeLogger(LifeCycleImpl.class); private ComponentContext m_ctx; //Sets the component's context public void setComponentContext(ComponentContext aContext) { if (logger.isLoggable(Level.FINE)) { logger.log(Level.FINE, "setComponentContext: " + aContext.getComponent().getComponentId()); } m_ctx = aContext; } //Invoked when the component is started public void onStart() { logger.log(Level.INFO, "Called onStart: " + m_ctx.getComponent().getComponentId()); } //Invoked when the component is stopped public void onStop() { logger.log(Level.INFO, "Called onStop: " + m_ctx.getComponent().getComponentId()); } }

Here is the BootstrapImpl.java class:

package com.adobe.livecycle.participantsService; import java.util.logging.Level; import com.adobe.idp.dsc.component.Bootstrap; import com.adobe.idp.dsc.component.BootstrapContext; import com.adobe.logging.AdobeLogger; public class BootstrapImpl implements Bootstrap{ private static final AdobeLogger logger = AdobeLogger.getAdobeLogger(BootstrapImpl.class); private BootstrapContext m_ctx; public void setBootstrapContext(BootstrapContext aCtx) { logger.log(Level.INFO, "Set bootstrap context: " + aCtx.getComponent().getComponentId()); m_ctx = aCtx; } //Invoked when the component is uninstalled public void onUnInstall() { logger.log(Level.INFO, "Called onUnInstall: " + m_ctx.getComponent().getComponentId()); } //Invoked when the component is installed public void onInstall() { logger.log(Level.INFO, "Called onInstall: " + m_ctx.getComponent().getComponentId()); } }

As the last step you must also confirgure the components.xml file.

<component xmlns="http://adobe.com/idp/dsc/component/document"> <!-- Unique id identifying this component --> <component-id>com.adobe.livecycle.participantsService</component-id> <!-- Version --> <version>1.0</version> <!-- bootstrap implementation class --> <bootstrap-class>com.adobe.livecycle.participantsService.BootstrapImpl</bootstrap-class> <!-- lifecycle implementation class --> <lifecycle-class>com.adobe.livecycle.participantsService.LifeCycleImpl</lifecycle-class> <!-- Start of the Service definition --> <services> <!-- Unique name for service descriptor. The value is used as the default name for deployed services --> <service name="AlexParticipantsService"> <!-- service implementation class definition --> <implementation-class>com.adobe.livecycle.participantsService.ParseServiceImpl</implementation-class> <!-- description --> <description>Allows you to parse the review context XML file to and find how many participants are in this current stage in MRA implementation.</description> <!-- automatically deploys the service and starts it after installation --> <auto-deploy service-id="AlexParticipantsService" /> <operations> <!-- method name in the interface--> <operation name="numberOfReviewers"> <!-- input parameters to the "numberOfReviewers" method --> <input-parameter name="reviewContextXML" title="Review Context XML" type="org.w3c.dom.Document"> <hint>The review context XML file.</hint> </input-parameter> <output-parameter name="reviewerCount" title="Number of Reviewers" type="java.lang.Integer"> <hint>The count of reviewers in the review context file</hint> </output-parameter> <hint>Counts the number of reviewers in an MRA comments RSS file</hint> </operation> <operation name="numberOfApprovers"> <!-- input parameters to the "numberOfReviewers" method --> <input-parameter name="reviewContextXML" title="Review Context XML" type="org.w3c.dom.Document"> <hint>The review context XML file.</hint> </input-parameter> <output-parameter name="approverCount" title="Number of Approvers" type="java.lang.Integer"> <hint>The count of approvers in the review context file at the current stage</hint> </output-parameter> <hint>Counts the number of approvers in the current stage</hint> </operation> </operations> </service> </services> </component>

The structure should looks similar to this (see Figure 2).

To deploy the custom component into Workbench follow the steps below:

  1. Once your strcuture looks similar to this (see Figure 2), export this project to a jar file. Select-> Export.
  2. Choose Jar file and select Next.
  3. Make sure all files are included in the Jar and select Finish.
  4. To install your new component, open LiveCycle ES2.5 Workbench and log in to your LiveCycle server using proper credentials (see Figure 3).
  1. Select Window -> Show View -> Components.
  2. Right-Click the root Components folder and select Install Component.
  3. In the navigator window find your new jar with your custom component and click Open.
  4. Expand the Components folder, find your new Service and right-click Start Component.

Create GetReviewers/ GetApprovers Processes

Both processes are the same with the exception of naming conventions and the placement of either a numberOfReviewers service or nuberOfApprovers service. Use the following steps to create the processes.

  1. Select Window -> Show View -> Application.
  2. Choose the ReviewCommentingApproval Component and expand.
  3. Expand the application version you would like to use and navigate to processes/core.
  4. Right click on core and select New->Process... you can name this whatever you would like, for simplicity I named the process GetReviewers/GetApprovers.
  5. The first activity we must pick is getReviewContext under ReviewCommentingAndApproval Core. Do this by dragging the Activity Picker on the to workspace and navigating through the dialog box. You will want to drag two Set Values blocks and two Decision Point blocks as well.
  • List of Variables you will need to create
    • currentStage: int – The current stage number.
    • participantNum: output, int – The number of reviewers in the current stage.
    • reviewerCount/approverCount: int – A counter for an internal loop.
    • participants: string, output – The string to display participants.
    • reviewID: input, string – The review ID to search for the review context.
    • reviewContextXML: xml – The review context.
    • revisionNo: input, int – The current revision of the review.
  1. To create this process set up your blocks in the formation below and following there will be details for how to configure each (see Figure 4).
  1. Startpoint: Use a default startpoint.
  2. Get Review Context XML is a getReviewContext service.
    1. Input: ReviewID = reviewID input variable.
    2. Input: Revision = revisionNo input variable.
    3. Output: Review Context Document = reviewContextXML.
  3. Get Number of Reviewers is the custom component called numberOfReviewers or numberOfApprovers.
    1. Input: Review Context XML = reviewContextXML variable.
    2. Output: Number of Reviewers = participantNum output variable.
  4. Get Stages is a Set Value.
    1. Mapping: /process_data/@currentStage -> /process_data/reviewContextXML/review_context/current_stage
    2. Mapping: /process_data/@reviewerCount -> 1 OR /process_data/@approverCount -> 1
  5. Place a Decision Point that will evaluation the route with a condition first.
    1. Condition Route: /process_data/@reviewerCount <= /process_data/@participantNum
    2. Second Route to No-Op will have no condition
  6. Place a Decision Point for No-Op which has no mappings or operations.
  7. Load to List is a Set Value .
    1. Mapping: /process_data/participantList[/process_data/@reviewerCount] ->
/process_data/reviewContextXML/review_context/stages[/process_data/reviewContextXML/review_context/current_stage]/stage/reviewers/reviewer[/process_data/@reviewerCount + 0]/@name
    1. Mapping: /process_data/@participantString ->
concat(/process_data/@participantString, " <br /> ",/process_data/reviewContextXML/review_context/stages[/process_data/reviewContextXML/review_context/current_stage]/stage/reviewers/reviewer[/process_data/@reviewerCount + 0]/@name )
    1. Mapping: /process_data/@reviewerCount ->
/process_data/@reviewerCount +1 | /process_data/@approverCount -> /process_data/@approverCount +1

Ensure to test this process individually by simply invoking it with a review ID and revision number from a existing review.

Integrating with the Assign Tasks processes

Finally we have to integrate our new processes into the full Assign Task processes. The steps are the same for both AssignTaskToReviewer and AssignTaskToApprover processes. We must insert the custom processes GetReviewers and GetApprovers that we just made into the workflow as well as two Set Value processes. Use the figure below to place it in the correct location (see Figure 5).

Here is the list variables to add:

  • Revision: int—The current revision number.
  • participantString: string—The string form of all participants to be inserted in the HTML e-mail message.
  • participantNum: int—The number of participants to be inserted into the HTML e-mail message.
  1. Place the Set Value after the NoOp Decision Point and the Get Reviewers processes following. Connect it to the Review Task without any conditional connections.
  2. Get Revision Number is a Set Value process.
    1. Mapping: /process_data/@revision -> /process_data/participantTO/object/reviewContext/revision
  3. Get Reviewers is the custom process GetReviewers.
    1. Input: reviewID = reviewId input variable
    2. Input: revisionNo = revision variable
    3. Output: participantNum = numOfParticipants
    4. Output: participantString = participantString
  4. Select the ReviewerTask and remove any filter applied to the Process Properties by selecting All (see Figure 6).
  1. Expand the Custom E-mail Template header and select Edit E-mail Template (see Figure 7).
  1. To edit ensure that the Body tab is selected and insert the following block of HTML to show the message:

There are {$/process_data/@numOfParticipants$} participant(s) in this stage, including you.

{$/process_data/@participantString$}

HTML

  • <p>There are <b>{$/process_data/@numOfParticipants$}</b> participant(s) in this stage, including you. </p>
  • {$/process_data/@participantString$}
  1. Repeat steps 1-6 for the 'useReplyToComplete =true' workflow as well.
  2. Repeat steps 1-7 for AssignTaskToApprover process. Interchange GetReviewers with Get Approvers.

Where to go from here

For more information, refer to the following documentation: