Iterator Process Tool

Introduction

The Iterator Process Tool is a plugin that enables iteration through records or assignments to execute another process tool within a specific context. When iterating, each record or assignment is set as the context, allowing you to use hash variables appropriately. This plugin includes two versions to cater to different use cases:

• Iterator Process Tool (Record)
• Iterator Process Tool (Assignment)

For activity instances, use the Iterator Process Tool (Assignment).

Additionally, the plugin includes a utility called Database Query Process Tool for loading records.

Get started

Where to get the plugin

You can download the Iterator Process Tool plugin from JogetOSS GitHub.

How to install

1. Download the plugin JAR file from the releases page.
2. Go to Settings > Manage Plugins > Upload Plugin.
3.  Once uploaded, the plugin will be available in your Joget environment.

How to use it 

Example: Send Daily Reminders on Upcoming Meetings within 2 days

1. In this example, we use the Scheduler plugin to trigger the plugin at 7 am daily. Set the plugin to the Iterator Process Tool (Record).
   
2. You can use the Database Query Process Tool to retrieve the records later. First, we will need to prepare the SQL to retrieve bookings that occur within 2 days of the job running.

   SELECT id, c_subject, c_name, c_room, c_date_from, c_date_from FROM app_fd_mrb_booking 
   WHERE c_date_from > NOW() AND DATE(c_date_from) < DATE_ADD(NOW(), INTERVAL 2 DAY)
   /*pick up bookings happening within 2 days from now to send reminder*/

   
   Note that it is important that we return the id column, as it will be used to set the record context for the hash variable to work.

3. This is the complete configurations.
   
   
   
   
   
4. Choose Process Tool, followed by Database Query Process Tool.
5. Set id in Record ID for the reason explained above.
6. In Execute Process Tool, choose Email Tool.
7. The email tool will be triggered once per record it iterates through.

8. Observe the server log or check emails to verify.

   

   INFO  15 Mar 2022 18:19:00 org.joget.marketplace.IteratorProcessToolRecord - Executing Iterator
   INFO  15 Mar 2022 18:19:00 org.joget.marketplace.DatabaseQueryProcessTool - Query: SELECT id, c_subject, c_name, c_room, c_date_from, c_date_from FROM app_fd_mrb_booking  _WHERE c_date_from > NOW() AND DATE(c_date_from) < DATE_ADD(NOW(), INTERVAL 2 DAY)_/*pick up bookings happening within 2 days from now to send reminder*/
   INFO  15 Mar 2022 18:19:00 org.joget.marketplace.DatabaseQueryProcessTool - Rows returned: [{c_subject=Product Discussion, c_room=44cefb42-289f-46db-b90c-6430224e8506, c_date_from=2022-03-16 09:00, c_name=Hugo, id=2960b356-161d-451a-8c2d-85fdebf2e111}, {c_subject=Project Debrief, c_room=44cefb42-289f-46db-b90c-6430224e8506, c_date_from=2022-03-17 09:00, c_name=Alexa, id=2960b356-161d-451a-8c2d-85fdebf2e121}]
   INFO  15 Mar 2022 18:19:00 org.joget.marketplace.IteratorProcessToolRecord - Iterator returned: 2 items: [{c_subject=Product Discussion, c_room=44cefb42-289f-46db-b90c-6430224e8506, c_date_from=2022-03-16 09:00, c_name=Hugo, id=2960b356-161d-451a-8c2d-85fdebf2e111}, {c_subject=Project Debrief, c_room=44cefb42-289f-46db-b90c-6430224e8506, c_date_from=2022-03-17 09:00, c_name=Alexa, id=2960b356-161d-451a-8c2d-85fdebf2e121}]
   INFO  15 Mar 2022 18:19:00 org.joget.marketplace.IteratorProcessToolRecord - Iterating item: 1 - Record: 2960b356-161d-451a-8c2d-85fdebf2e111
   INFO  15 Mar 2022 18:19:00 org.joget.marketplace.IteratorProcessToolRecord$1 - Executing tool: executeProcessTool - org.joget.apps.app.lib.EmailTool
   INFO  15 Mar 2022 18:19:00 org.joget.marketplace.IteratorProcessToolRecord$1 - Executed tool: executeProcessTool - org.joget.apps.app.lib.EmailTool
   INFO  15 Mar 2022 18:19:00 org.joget.apps.app.lib.EmailTool - EmailTool: Sending email from=hugolim@outlook.com, to=hugo@joget.org, cc=, bcc=, subject=Booking Product Discussion
   INFO  15 Mar 2022 18:19:02 org.joget.apps.app.lib.EmailTool - EmailTool: Sending email completed for subject=Booking Product Discussion
   INFO  15 Mar 2022 18:19:05 org.joget.marketplace.IteratorProcessToolRecord - Finished item 1 - Record: 2960b356-161d-451a-8c2d-85fdebf2e111
   INFO  15 Mar 2022 18:19:05 org.joget.marketplace.IteratorProcessToolRecord - Iterating item: 2 - Record: 2960b356-161d-451a-8c2d-85fdebf2e121
   INFO  15 Mar 2022 18:19:05 org.joget.marketplace.IteratorProcessToolRecord$1 - Executing tool: executeProcessTool - org.joget.apps.app.lib.EmailTool
   INFO  15 Mar 2022 18:19:05 org.joget.marketplace.IteratorProcessToolRecord$1 - Executed tool: executeProcessTool - org.joget.apps.app.lib.EmailTool
   INFO  15 Mar 2022 18:19:05 org.joget.apps.app.lib.EmailTool - EmailTool: Sending email from=hugolim@outlook.com, to=hugo@joget.org, cc=, bcc=, subject=Booking Project Debrief
   INFO  15 Mar 2022 18:19:06 org.joget.apps.app.lib.EmailTool - EmailTool: Sending email completed for subject=Booking Project Debrief
   INFO  15 Mar 2022 18:19:10 org.joget.marketplace.IteratorProcessToolRecord - Finished item 2 - Record: 2960b356-161d-451a-8c2d-85fdebf2e121
   

9.  Once verified working, it is advisable to turn off the debug mode.

Configure iterator process tool properties

Fields to configure:

Load records

• Iterator Method: 
  • Method to load the dataset.
  • Choose to load records either by using a Process Tool or from  Datalist.
• List: 
  • Choose a list to retrieve the dataset from.
  • This option is needed when the Iterator Method is set to List.
• Iterator Process Tool: 
  • Choose a process tool to retrieve the dataset from.
  • Process Tool must return a collection of the maps as a dataset.
    

    import org.joget.commons.util.LogUtil;
    import java.util.Collection;
    import java.util.Map;
     
    Collection col = new ArrayList();
     
    Map map = new HashMap();
    map.put("id", "1");
    map.put("name", "Alice");
    col.add(map);
     
    map = new HashMap();
    map.put("id", "2");
    map.put("name", "George");
    col.add(map);
     
    return col;

  • You may use the Database Query Process Tool bundled with this plugin to enter an SQL query string.
  • This option is needed when the Iterator Method is set to Process Tool.
• Record ID: Specify which column to use as the dataset's record ID / primary key.

  For example: id

Execute process tool

• Process Tool: 
  • With the dataset loaded, the plugin will iterate through each record, set the record or assignment as the context, and execute the process tool defined here.
  • In the plugin configuration, when using the hash variable, instead of using # to encapsulate, please replace # with $$ in your plugin for parsing to take place in the correct context.
    For example:
    
    • In assignment mode, use $$form.request.name$$.
      Example: $$form.request.name$$
    • Record mode, use $$form.request.name[@recordId@]$$.
      Example: $$form.request.name[@recordId@]$$.
    • Retrieve values from the iterator's dataset, using {columnName}.
      Example: {id}
      Example: {name}

Advanced

• Debug Mode: Enable this to log debug information.
• Delay Between Execution: Add a 1-second delay between records. This is useful for tasks like sending emails where rate limits apply.

Download Plugin

• Iterator Process Tool - Releases.