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
1. Select the Action Editor tool from the list of tools on the Metis home page. The action editor's home page will be loaded and will display a list containing the two workflows created in Step 3 of the tutorial.
2. Select the admin-workflow and click the Edit Workflow button. The action editor loads the workflow and provides tools to associate actions with each event node. In particular, next to each event node is a pop-up menu listing all of the actions supported by Metis (see below).
3. Select Send Email Notification from the pop-up menu next to the submissionReceived event, and click its associated Add button. The action (which appears in green) will be added as a child of the submissionReceived event and its status will indicate that it is Not Ready. Once you have added an action to an event, you need to edit the action to fill out its parameters. Once an action's parameters have been set, the Not Ready status indicator goes away. Note: do not try to activate a workflow that has incomplete action specification. The behavior of Metis is not defined in such situations.
4. Click the Edit button next to the sendEmail action. The parameter page of the sendEmail action is displayed. This action does not require any parameters, so the parameter pane (the upper left portion of the screen) is empty except for save and cancel buttons. The user pane (the upper right portion of the screen) displays a list of users, groups, and roles that can be associated with the current 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 Action button to finish editing this action and to return to the edit page of the Action editor. Note that the sendEmail action no longer has the Not Ready status indicator.
7. Select Retrieve Contents of URL from the pop-up menu next to the submissionReceived event and click its associated Add button. This action will be used to download the submission so it can be processed by the administrator.
8. Click the downloadURL action's Edit button to edit its parameters. This action has two parameters: 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 running 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 Action button to return to the edit page of the action editor.
12. Select Bind Role to User Or Group from the pop-up menu next to the submissionReceived event and click its associated Add button. This 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 created in Step 5 of this tutorial: physics, chemistry, geology, or biology.
13. Click the bindRole action's Edit button to edit its parameters. This 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 New Mapping button. The parameter pane updates to contain a new field for the mapping.1 parameter. Click the New 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 Action button to return to the edit page of the action 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 Send Email Notification from the pop-up menu next to the submissionProcessed event, and click its associated Add button. Associate the subcommittee role with the new sendEmail action by clicking its associated Edit button. Save the action, and then click on the Save Workflow button 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. You 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 and click the Edit Workflow button. The action editor loads the workflow.
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. Click the Update Attributes button. 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 Action 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. Note: there is a bug with the setTimer editor that prevents it from tracking the state of the radio button properly. As such, if you want to get a deadline from the attribute of an event, be sure the From Attribute radio button is checked before clicking the Save Action button. |
| 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. Click the Update Fields button. Select firstname for the field.FIRSTNAME parameter. Select url for the field.URL parameter. Click the Save Action 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. Click the Update Fields button. Select firstname for the field.FIRSTNAME parameter. Select url for the field.URL parameter. Click the Save Action 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. Click the Update Fields button. Select firstname for the field.FIRSTNAME parameter. Select url for the field.URL parameter. Click the Save Action button. |
3. Click the Save Workflow button. Congratulations, you have now finished creating the peer review process in Metis. Next, we create a web form to submit the required data for the submissionReceived event and then we step through the process of executing both workflows in the workflow monitor.