Step 4: Associate Actions [web|gui]
This part of the tutorial steps you through the process of assigning actions to the two workflows created in Step 3 of the tutorial. As you will see, Metis actions enable the partial automation of work in response to incoming events. Actions can download files, create users, dynamically bind roles, send e-mail, and more. Most actions take parameters; the values for these parameters can be specified statically, or they can reference the attributes of events to receive values at run-time.
Editing the admin-workflow
Unlike the Web-based version of Metis, the Metis GUI Workflow Editor incorporates the functionality of Web-based Metis Action Editor. The buttons above the tree view in the GUI Workflow Editor can be used to add and delete actions as well as change the sequence of their execution using the Up and Down buttons. However, in order to edit the properties of an individual action, it is necessary to have a separate interface. Double clicking an action node pops up an Action Editor window and it is here that the properties of an action can be edited.
1. Load the admin-workflow workflow into the Metis GUI Workflow Editor.
2. Select the submissionReceived event. You will notice that the Action button and its associated pop-up list will be enabled. This list contains all of the actions supported by Metis (see below).
3. Select Send Email Notification from the drop-down list, and click the Action button. The action node will be added as a child of the submissionReceived event. Once you have added an action to an event, you need to edit the action to configure its parameters.
4. Double click the sendEmail action node. A new window displaying the Action Editor will appear showing four separate panels. The upper left panel hosts the controls and buttons that can be used to associate users, roles and groups to this action. The sendEmail action will send an e-mail message to each of its associated users.
5. Select the admin role from the list of Metis users and click the Add User button. The page will refresh and indicate that the admin role is associated with this action.
6. Click the Save button to finish editing this action and to return to the Workflow Editor.
7. Select Retrieve Contents of URL from the Actions list and click the Action button. This action will be used to download the submission so it can be processed by the administrator.
8. Double click the downloadURL action node. This action has two parameters, namely destination and url. The destination parameter needs the absolute path to a directory to download the contents of the URL. The url parameter needs either a specific URL to be entered, or it needs the name of an attribute of the submissionReceived event that will contain a valid URL at run-time. We shall use the latter approach, since the submissionReceived event has a url attribute that supplies the required information.
9. Enter the absolute path name of a destination directory for the downloaded URL in the destination parameter. This directory needs to be writeable by the Tomcat servlet engine executing Metis. An example of an absolute path on a Unix-based platform is: </Users/kena/downloads/>.
10. In the url parameter, enter the string :url. This demonstrates the way to access the values of an event's attributes. At run-time, the string :url tells the Metis execution engine to supply the value of the submissionReceived event's url attribute to the url parameter of the downloadURL action.
11. Click the Save button to return to the Workflow Editor.
12. With the submissionReceived event node still selected in the workflow tree, select Bind Role to User Or Group from the Actions list and click the Action button. The bindRole action will select the correct subcommittee to review the submission based on the submissionReceived event's area attribute. This attribute will contain one of four values based on the web form that is created in Step 5 of the tutorial: physics, chemistry, geology, or biology.
13. The bindRole action initially has two parameters: Attribute and Role. The Role parameter specifies the role that will be dynamically bound by this action. The Attribute parameter specifies which attribute of the submissionReceived event will be used to determine the binding.
14. Set the Role parameter to subcommittee. We want this action to bind the subcommittee role to the correct subcommittee group. The means for selecting the correct group will be specified next.
15. Set the Attribute parameter to area. We want the value of this attribute to specify the correct subcommittee. To do this, we now must create four mappings that map particular values of this attribute to particular Metis groups.
16. Click the Add Mapping button. The Details pane updates to contain a new field for the mapping.1 parameter. Click the Add Mapping button three more times to create four mapping parameters in total.
17. Enter physics for mapping.1, chemistry for mapping.2, geology for mapping.3, and biology for mapping.4.
18. Select subcommitteeA for mapping.1, subcommitteeB for mapping.2, subcommitteeC for mapping.3, and subcommitteeD for mapping.4.
19. Click the Save button to return to the Workflow Editor. The actions for the first event in this workflow are now complete. When a submissionReceived event occurs, we will send an e-mail to the administrator, download the submission, and bind the subcommittee role to the appropriate subcommittee group.
20. Select the submissionProcessed event. Select Send Email Notification from the Actions list and click the Action button. Associate the subcommittee role with the new sendEmail action. Save the action and then click on the Save Repository button in the Workflow Editor to save the admin-workflow. This last edit ensures that the appropriate subcommittee is notified when the new submission is ready to be reviewed.
Editing the review-workflow
Before editing the review-workflow in the action editor, you need to create three templates for the sendFormattedEmail action, that will be used by the last three events. Templates are simple text files that are stored in the following directory: <$CATALINA_HOME/webapps/metis/WEB-INF/template/>. Each template can contain fields whose specific values are determined at run-time. Fields are indicated in templates using an @ symbol. Create the following three templates and place them in the template directory before performing the steps below.
Template: success.txt
Dear @FIRSTNAME@,
We are pleased to inform you that your submission has been accepted
into our digital library. Your paper and its reviews can be found at:
<@URL@>
Congratulations!
The Digital Library
Template: reject.txt
Dear @FIRSTNAME@,
We have completed the first review of your submission to our digital library. We
are sorry to inform you that we cannot accept your submission into our
collection at this time.
You paper and its reviews can be found at:
<@URL@>
Contact your Action Editor for additional feedback.
The Digital Library
Template: revise.txt
Dear @FIRSTNAME@,
We have completed the first review of your submission to our digital library. The
reviewers have identified some issues that need to be addressed before
your submission can be accepted for publication in our collection.
You paper and its reviews can be found at:
<@URL@>
Contact your Action Editor for instructions on how to proceed.
The Digital Library
1. Select the review-workflow from the GUI Workflow Editor's List.
2. Using the table below, add actions to the events of the review-workflow.
| Event | Action | Parameters | Comments |
|---|---|---|---|
| submissionReceived | bindRole | Attribute: area Role: subcommittee Mapping.1: physics/subcommitteeA Mapping.2: chemistry/subcommitteeB Mapping.3: geology/subcommitteeC Mapping.4: biology/subcommitteeD |
This bindRole action mimics the one found in the admin-workflow. |
| sendEmail | Associate User: subcommittee | Send e-mail to the subcommittee to give them a "heads-up". | |
| createUser | userEmail: contactEmail userName: contactName |
Create a new Metis user based on the contact author's information. | |
| bindRole | Attribute: contactEmail Role: author |
Bind the author role to the new user created in the previous action. When the specified attribute is an e-mail address, no mappings are needed. Instead, the e-mail address is used to identify the Metis user to be bound to the specified role. | |
| submissionProcessed | No Actions! | The admin workflow takes care of sending an e-mail notification to the committee for the submissionProcessed event. | |
| actionEditorAssigned | bindRole | Attribute: editorEmail Role: editor |
Bind the editor role to the editor's e-mail address contained in the event. |
| sendEmail | Associate User: editor | Send e-mail to the editor to make the review assignment official. | |
| reviewerAssigned | createUser | userEmail: reviewerEmail userName: reviewerName |
Create a new Metis user based on the reviewer's contact information. Note: if the reviewer is already a Metis user, the existing user is used; the create user action will not blindly create duplicate users. |
| bindRole | Attribute: reviewerEmail Role: reviewer |
Bind the reviewer role to the user created (or reused) in the previous action. | |
| sendEmail | Associate User: reviewer | Send e-mail to the reviewer to make the review assignment official. | |
| deadlineAssigned | setTimer | Name: review Deadline: deadline Event: deadlinePassed attribute.id: :id |
Edit this action in the following manner. Type review in the Name parameter. Select deadlinePassed for the Event parameter. The GUI will reconfigure itself dynamically to reflect the correct number of attributes of the deadlinePassed event. Type :id in the attribute.id parameter. Select the From Attribute radio button and select deadline in the pop-up menu. Click on the Save button. This action sets a timer named "review" in the execution engine. The event parameter stores the name of the event that the timer will publish when the deadline has passed. The attribute parameters allow the user to specify the values of the generated event's attributes. |
| sendEmail | Associate User: reviewer | Send e-mail to the reviewer to inform them of the deadline. | |
| deadlinePassed | sendEmail | Associate User: editor | Send e-mail to the editor to inform him or her that the deadline for the review has passed. |
| reviewComplete | cancelTimer | Name: review | Just in case the reviewComplete event comes in before the deadlinePassed event, we can cancel the review timer and move on. |
| sendEmail | Associate User: editor | Send e-mail to the editor to inform him or her that the review is now finished. | |
| authorNotifiedOfSuccess | sendFormattedEmail | Subject: Review Result Template: success.txt field.FIRSTNAME: firstname field.URL: url Associate User: author |
Edit this action in the following manner. Type Review Result for the subject parameter. Associate the author user with the action. Select success.txt from the template pop-up menu. The GUI will update itself to reflect the correct number of fields in the chosen template. Select firstname for the field.FIRSTNAME parameter. Select url for the field.URL parameter. Click the Save button. |
| authorNotifiedOfRejection | sendFormattedEmail | Subject: Review Result Template: reject.txt field.FIRSTNAME: firstname field.URL: url Associate User: author |
Edit this action in the following manner. Type Review Result for the subject parameter. Associate the author user with the action. Select reject.txt from the template pop-up menu. The GUI will update itself to reflect the correct number of fields in the chosen template. Select firstname for the field.FIRSTNAME parameter. Select url for the field.URL parameter. Click the Save button. |
| authorNotifiedOfRequiredRevision | sendFormattedEmail | Subject: Review Result Template: revise.txt field.FIRSTNAME: firstname field.URL: url Associate User: author |
Edit this action in the following manner. Type Review Result for the subject parameter. Associate the author user with the action. Select revise.txt from the template pop-up menu. The GUI will update itself to reflect the correct number of fields in the chosen template. Select firstname for the field.FIRSTNAME parameter. Select url for the field.URL parameter. Click the Save button. |
3. Click the Save Repository button.
Congratulations, you have now finished creating the peer review process in Metis. In Step 5, we create a web form to submit the required data for the submissionReceived event and then, in Step 6, we step through the process of executing both workflows in the workflow monitor.