Sample process with Aperte Modeler - bluesoft-rnd/aperte-workflow-core GitHub Wiki

The goal of this article is to sum up all required steps for creating and deploying Aperte Workflow process with Aperte Modeler. Everything here was split into consistent, logical chunks with a short preface. That way each time a section is completed, something new and meaningful is added to the process diagram.

To keep the tutorial clear we decided on using a very, very simple and short business process definition. On one hand, this is enough to bring up essential features of the Aperte Modeler, and on another allows to keep the focus on the tool itself. Diving deep into business case and its requirements is not in scope of this article.

Scenario

We want to provide Liferay Users ability to submit their favorite quote, along with its author, and allow Liferay Administrators to review those submissions before deciding on further processing. If the quote is accepted is going to be displayed in the process log. If it's rejected the creator is going to have to provide necessary changes and submit it again.

Prerequisites

This tutorial assumes that one have already installed and configured Aperte Workflow runtime environment with Aperte Modeler. At least two different users account are going to be necessary. One should be a simple User and second one should have Administrator credentials. All this can be easily achieved by downloading preconfigured DEMO bundle, as described in quick start guide and in fact this article was prepared by using that kind of bundle.

Authenticating

  1. Navigate to the Aperte Modeler webpage, e.g. http://localhost:8080/apertemodeler.
  2. If asked for credentials, provide them from the underlying Liferay Portal installation, e.g.
    • User Name: joebloggs
    • Password: test frame

Setting up workspace

To keep the modeler workspace organized one should use folders. This article assumes that a separate folder is going to be created to store entire work performed later.

  1. From the Explorer menu select New > Folder. frame
  2. When asked about the directory name, type in my-modeler-sample and press OK.
  3. Navigate to the folder by either using the tree on the left or double clicking its icon.

Creating new BPMN 2.0 process diagram

This section addresses creating the process diagram and preserving it under the workspace. Actual development is going to happen later. Before you begin, make sure that in Explorer you are inside the directory created in the previous step or otherwise your diagram is not going to be saved there.

  1. From the Explorer menu select New > Business Process Diagram (BPMN 2.0) for Aperte Workflow.
  2. Now new tab or window with process Editor is going to be opened. This may vary depending on your web browser type and settings. If it didn't happen, please make sure that your web browser is not blocking popup windows.
  3. Although the diagram is still fresh and empty save it by clicking the save icon from the Editor top menu. frame
  4. Provide the process diagram name my-process-diagram and suitable description frame

Warning: Process title should not contains any special characters like: @#$%^&, newline or any whitespaces!

  1. Go back to Explorer window and navigate to my-modeler-sample folder. You should see a new file entitled my-process-diagram. If during that you are asked by a popup to refresh the view, confirm. Otherwise manual refresh may be required to see your changes. frame

Creating basic process structure

This part shows how to set up simple process model using the BPMN 2.0 notation. The example is pretty easy and consist only of few basic elements and does not introduce any Aperte Workflow specific settings, which are going to be addressed later.

  1. From the Editor Shape Repository palette drag and drop Start Event element.
  2. Name it start. This can be done either by double-clicking the element or by editing element attributes.
  3. Using newly created start event element shortcut menu create new Task. Name it input-data.

Warning: Task name should not contains any special characters like: @#$%^&, newline or any whitespaces! If one of them occure, modeler automaticly will remove it or, if it is whitespace, will change it to: "_"! Additionally every name must be unique.

  1. Name the Sequence Flow between those two elements to input. Your process diagram should look like that now: frame

  2. Add additional elements and connect them together to create the following model. Make sure that every used Sequence Flow is named. If you need to change its shape use dockers. frame

    • Task with name review-data
    • Task with name echo-data
    • End Event with name end

  3. Make sure to save the process diagram.

Defining task assignment

The input-data task, as starting point in the process, is something naturally assigned to its creator. For the review-data task however, we are going to use a task queue which allows users in particular role to claim and solve tasks.

  1. Open the Aperte Process Editor from the top menu by clicking its icon.
  2. Switch to the Process Queues tab. frame
  3. Create new queue with name quote-review-queue.
  4. Provide meaningful description for the queue, e.g. Submitted Quotes.
  5. Assign only the Administrator role with browsing allowed option selected.
  6. The queue definition should now look like that that. frame
  7. Save your work by pressing the Save button. That also closes the Aperte Process Editor.
  8. Open the Aperte Step Editor on the input-data task.
  9. Switch to Assignment tab.
  10. In the Assignee parameter type the value #{initiator}. This will assign the task to its creator.
  11. Save your work by pressing the Save button. That also closes the Aperte Step Editor.
  12. Open the Aperte Step Editor on the review-data task. frame
  13. Switch to Assignment tab.
  14. In the Candidate-group parameter type the value quote-review-queue. That is the name of the queue that was created in step 3.
  15. Save your work by pressing the Save button. That also closes the Aperte Step Editor.
  16. Make sure to save the process diagram.

Defining the user interface for the human tasks

User tasks require GUI to allow necessary human interaction. This section explains how to construct the GUI with the Aperte Step Editor. Customizing actions with the Aperte Action Editor is going to be explained in next section.

  1. Open the Aperte Step Editor on the input-data task.
  2. If not selected by default, switch to User Interface Definition tab.
  3. Drag new Vertical Layout widget to the widget hierarchy tree.
  4. Drag new Process Data Block and Process Comments widgets to the Vertical Layout added before to create tree structure. The widget hierarchy in the step should now look like that: frame
  5. Click on the Advanced Data Block widget and navigate to the Attributes tab. frame
  6. Provide value for the following attributes:
    • Caption: Provide Quote
    • Comment: Enter quote content and it's author below.
  7. Definition of the widget attribute is created with the Hierarchy Editor tab. The process requires a simple input form when user can type both his first and last name.
  8. Drag FormWidgetElement to the hierarchy tree. Then drag TextAreaWidgetElemen and InputWidgetElement inside it. The result is shown below: frame
  9. For the FormWidgetElement edit the following attributes. Remember to press Commit button below the attributes when done.
    • Is full size: selected
    • Spacing: selected
    • Visible: selected
  10. For the TextAreaWidgetElement edit the following attributes. Remember to press Commit button below the attributes when done.
    • Bind: quote
    • Caption: Quote
    • Max Length: 400
    • Is required: selected
    • Is rich text: selected
    • Visible: selected
    • Visible lines: 4
    • Width: 100%
  11. For the InputWidgetElement edit the following attributes. Remember to press Commit button below the attributes when done.
    • Bind: author
    • Caption: Author
    • Max Length: 120
    • Is required: selected
    • Visible: selected
    • Width: 100%
  12. Switch to Permissions tab in the Process Data Block widget. frame
  13. For all the permissions select the .* role name, granting all the users ability to interact with the widget.
  14. Now when done with Process Data Block widget, click on the Process Comments widget and navigate to the Attributes tab.
  15. Provide value for the following attributes:
    • Caption: Process Comments
    • Comment: This is a place when one can insert own comments.
  16. Switch to Permissions tab for Process Comments widget.
  17. For all the permissions select the .* role name, granting all the users ability to interact with the widget.
  18. You are done with the widgets now, however there is still one more thing to do.
  19. Switch to State definition tab and provide following values frame
    • Description: Submit Quote
    • Commentary: Provide your personal favorite quote.
  20. Save your work by pressing the editor Save button. You work is done for the input-data task GUI definition. frame
  21. Open the Aperte Step Editor on the review-data task.
  22. Defining exactly the same GUI as earlier in input-data user task. In this step only minor modifications are going to be introduced:
    • In both TextAreaWidgetElement nad InputWidgetElements inside Advanced Data Block widget make sure that Is read only attribute is selected.
    • For every used widget on the Permission tab select only the Administrator role.
  23. Switch to State definition tab and provide following values
    • Description: Review submitted quotes
    • Commentary: Provide the review for the user submitted quotes
  24. Save your work by pressing the editor Save button. You work is done for the review-data task GUI definition.
  25. Make sure to save the process diagram.

Finishing the user interface with actions

As you may noticed some sequence flows start in user tasks. One needs to provide additional parameters with Aperte Action Editor to make the GUI definition complete.

  1. Open Aperte Action Editor on the to review sequence flow. frame
  2. If not selected by default, switch to the Default button type. frame
  3. For the selected button type provide following attributes:
    • Description: Move to review
    • Label: Submit
    • Priority: 10
  4. You work is done for the to review sequence flow. Save it by pressing the editor Save button.
  5. Open Aperte Action Editor on the to echo sequence flow.
  6. If not selected by default, switch to the Default button type.
  7. For the selected button type provide following attributes:
    • Description: Move to echo
    • Label: Accept data
    • Priority: 10
  8. You work is done for the to echo sequence flow. Save it by pressing the editor Save button.
  9. Open Aperte Action Editor on the back to input sequence flow.
  10. Switch button type to CommentButton frame
  11. For the selected button type provide following attributes:
    • Description: Move back to data input
    • Label: Reject data
    • Priority: 20
  12. You work is done for the back to input sequence flow. Save it by pressing the editor Save button.
  13. Make sure to save the process diagram.

Defining automatic task

So far the process contains only human tasks. This is rarely seen in real world as great amount of work is handled by automated systems. To introduce that kind of automation we are going to use the Log Step plugin which is going to allow to display the submitted quote in the logs.

  1. Click on the echo-data step to select it.
  2. Using attribute palette change the Tasktype attribute to LogStep. frame
  3. Open the Aperte Step Editor on the echo-data step.
  4. Provide Message which will display process attributes. Remember the bind attributes in Advanced Data Block you have supplied when creating the user interface? We are going to use them here, enclosed with ${ and }. frame
    • Message: A new quote was accepted: ${quote} -- ${author}
  5. You work is done for the echo-data sequence flow. Save it by pressing the editor Save button.
  6. Make sure to save the process diagram.

Defining process attributes

The modeling work is actually done at that point. What's left are some finishing touches, needed to make the process distinguishable in Aperte Workflow environment.

  1. If any element is currently selected on the diagram, click somewhere at the white, empty area. This ensures that the attribute palette is displaying process diagram attributes.

  2. Open the attribute palette and provide following attributes:

    • Name: FavoriteQuoteProcess
    • Aperte process filename: favoritequoteprocess
    • Manifest: Bundle-Name: favoritequoteprocess
    • Manifest: Bundle-Description: This is a sample quote submission process, developed with Aperte Modeler and described on the wiki
    • Manifest: ProcessTool-Process-Deployment: org.aperteworkflow.process.favorite.quote

  3. Open the Aperte Process Editor.

  4. Switch to Process Permissions tab.

  5. For all the permissions select the .* role name, granting all the users ability to interact with the process.

  6. Switch to Process Definition tab.

  7. Provide values for Description and Commentary.

    • Description: Favorite Quote Submissions
    • Commentary: Favorite quote submission process, Aperte Modeler sample

  8. Save your work by pressing the Save button. Your work with Aperte Process Editor is done.

  9. Make sure to save the process diagram.

Deploying the process

By this point the process should be fully developed and thus ready for deploying. Let's give it a try.

  1. The finished process should look like shown below. frame
  2. Press the Deploy button in Editor top menu. frame
  3. Wait for the confirmation to appear. frame

Testing the process

To test the process you will need to navigate to Aperte Workflow runtime environment and display Aperte Workflow Activities portlet.

  1. Start new process press: Start Task. frame
  2. Select the process FavoriteQuoteProcess and select the link "Begin task" frame
  3. Fill in the quote and it's author. You may also provide comments by pressing the Add comment button. Press Submit when done.
  4. You should see that new task has appeared in Submitted Quotes. Click on the queue name and claim the task. Do note that you need Liferay Administrator role for that. If you have submitted the quote from normal Liferay User account, you may need to switch accounts and login again. We configured that intentionally in defining task assignment section. frame
  5. If you decide to accept the quote, by pressing the Accept data, open your web server logs (if you use our bundles open the /tomcat-6.0.29/logs/catalina.out file) and search for it there.
  6. If you decide to reject the quote you are going to be asked to provide short comment after pressing Reject data button. The process is going to be redirected to input-data task and assigned to the user who created it.

Epilogue

We hope that now, after completing this tutorial, you are more familiar with Aperte Modeler. We encourage you to experiment with this tool by creating more sophisticated user interface and employing provided automatic steps to integrate [Drools](Drools Step plugin) or [Mule ESB](Mule ESB plugin).