In this article, we will explore the Quartz task scheduler and its integration with OSWorkflow. We will also give a tutorial with Quartz sending events and actions to OSWorkflow. This gives OSWorkflow temporal capabilities found in some business domains, such as call centers or customer care services.

Task Scheduling with Quartz

Both people-oriented and system-oriented BPM systems need a mechanism to execute tasks within an event or temporal constraint, for example, every time a state change occurs or every two weeks. BPM suites address these requirements with a job-scheduling component responsible for executing tasks at a given time. OSWorkflow, the core of our open-source BPM solution, doesn't include these temporal capabilities by default. Thus, we can enhance OSWorkflow by adding the features present in the Quartz open-source project.

What is Quartz?

Installing

Basic Concepts

Task Scheduling with Quartz

Integration with OSWorkflow

Creating a Custom Job

     public void execute(JobExecutionContext context) throws 
                                                               JobExecutionException;

The JobDataMap is very similar to a Java map but provides strongly typed put and get methods. This JobDataMap is set in the JobDetail file before scheduling the job and can be retrieved later during the execution of the job via the JobExecutionContext's getJobDetail().getJobDataMap() method.

Trigger Functions

trigger-functions are a special type of OSWorkflow function designed specifically for job scheduling and external triggering. These functions are executed when the Quartz trigger fires, thus the name. trigger-functions are not associated with an action and they have a unique ID. You shouldn't execute a trigger-function in your code.

To define a trigger-function in the definition, put the trigger-functions declaration before the initial-actions element.

     ... 
     <trigger-functions> 
       <trigger-function id="10"> 
          <function type="beanshell"> 
            <arg name="script"> 
            propertySet.setString("triggered", "true"); 
            </arg> 
          </function> 
       </trigger-function> 
    </trigger-functions> 
    <initial-actions> 
    ...

This XML definition fragment declares a trigger-function (having an ID of 10), which executes a beanshell script. This script will put a named property inside the PropertySet of the instance but you can define a trigger-function just like any other Java- or BeanShell-based function.

To invoke this trigger-function, you will need an OSWorkflow built-in function provider to execute trigger-functions and to schedule a custom job—the ScheduleJob FunctionProvider.

More about Triggers

Quartz's triggers are of two types—the SimpleTrigger and the CronTrigger. The former, as its name implies, serves for very simple purposes while the latter is more complex and powerful; it allows for unlimited flexibility for specifying time periods.

SimpleTrigger

SimpleTrigger is more suited for job firing at specific points in time, such as Saturday 1st at 3.00 PM, or at an exact point in time repeating the triggering at fixed intervals. The properties for this trigger are the shown in the following table:

CronTrigger

A CronExpression is made of seven parts, each representing a time component:

Each number represents a time part:

• 1 represents seconds
• 2 represents minutes
• 3 represents hours
• 4 represents the day-of-month
• 5 represents month
• 6 represents the day-of-week
• 7 represents year (optional field)

0 0 6 ? * MON: This CronExpression means "Every Monday at 6 AM".

0 0 6 * *: This CronExpression mans "Every day at 6 am".

For more information about CronExpressions refer to the following website:

http://www.opensymphony.com/quartz/wikidocs/CronTriggers Tutorial.html.

Scheduling a Job

We will get a first taste of Quartz, by executing a very simple job. The following snippet of code shows how easy it is to schedule a job.

    SchedulerFactory schedFact = new 
                                            org.quartz.impl.StdSchedulerFactory(); 
    Scheduler sched = schedFact.getScheduler(); 
    sched.start(); 
       JobDetail jobDetail = new JobDetail("myJob", null, HelloJob.class); 
       Trigger trigger = TriggerUtils.makeHourlyTrigger(); 
                                                      // fire every hour 
       trigger.setStartTime(TriggerUtils.getEvenHourDate(new Date())); 
                                                    // start on the next even hour 
       trigger.setName("myTrigger"); 
       sched.scheduleJob(jobDetail, trigger);

The following code assumes a HelloJob class exists. It is a very simple class that implements the job interface and just prints a message to the console.

    package packtpub.osw; 
    import org.quartz.Job; 
    import org.quartz.JobExecutionContext; 
    import org.quartz.JobExecutionException; 
    /** 
      * Hello world job. 
      */ 
    public class HelloJob implements Job 
    { 
       public void execute(JobExecutionContext ctx) throws 
                                                              JobExecutionException 
       { 
         System.out.println("Hello Quartz world."); 
       } 
    }

    SchedulerFactory schedFact = new 
                                          org.quartz.impl.StdSchedulerFactory(); 
    Scheduler sched = schedFact.getScheduler(); 
    sched.start();

    JobDetail jobDetail = new JobDetail("myJob", null, HelloJob.class); 
    This JobDetail tells the Scheduler to instantiate a HelloJob object 
    when appropriate, has a null JobGroup, and has a Job name of "myJob". 
    After defining the JobDetail, we must create and define the Trigger, 
    that is, when the Job will be executed and how many times, etc. 
    Trigger trigger = TriggerUtils.makeHourlyTrigger(); 
                                                    // fire every hour 
       trigger.setStartTime(TriggerUtils.getEvenHourDate(new Date())); 
                                                    // start on the next even hour 
       trigger.setName("myTrigger");

Finally, the last line of code associates the trigger with the job and puts them under the control of the Scheduler.

    sched.scheduleJob(jobDetail, trigger);

When the next even hour arrives after this line of code is executed, the Scheduler will fire the trigger and it will execute the job by reading the JobDetail and instantiating the HelloJob.class. This requires that the class implementing the job interface must have a no-arguments constructor.

An alternative method is to use an XML file for declaring the jobs and triggers. This will not be covered in the book, but you can find more information about it in the Quartz documentation.

Scheduling from a Workflow Definition

The ScheduleJob FunctionProvider has two modes of operation, depending on whether you specify the jobClass parameter or not. If you declare the jobClass parameter, ScheduleJob will create a JobDetail with jobClass as the class implementing the job interface.

    <pre-functions> 
       <function type="class"> 
          <arg name="class.name">com.opensymphony.workflow.util.ScheduleJob 
          </arg> 
          <arg name="jobName">Scheduler Test 
          </arg> 
          <arg name="triggerName">SchedulerTestTrigger</arg> 
          <arg name="triggerId">10 
          </arg> 
          <arg name="jobClass">packtpub.osw.SendMailIfActive 
          </arg> 
          <arg name="schedulerStart">true 
         </arg> 
         <arg name="local">true 
         </arg> 
       </function> 
    </pre-functions>

This fragment will schedule a job based on the SendMailIfActive class with the current time as the start time. The ScheduleJob like any FunctionProvider can be declared as a pre or a post function.

On the other hand, if you don't declare the jobClass, ScheduleJob will use the WorkflowJob.class as the class implementing the job interface. This job executes a trigger-function on the instance that scheduled it when fired.

   
    <pre-functions> 
       <function type="class"> 
         <arg name="class.name">com.opensymphony.workflow.util.ScheduleJob 
         </arg> 
         <arg name="jobName">Scheduler Test 
         </arg> 
         <arg name="triggerName">SchedulerTestTrigger 
         </arg> 
         <arg name="triggerId">10 
         </arg> 
         <arg name="schedulerStart">true 
         </arg> 
         <arg name="local">true 
         </arg> 
       </function> 
    </pre-functions>

This definition fragment will execute the trigger-function with ID 10 as soon as possible, because no CronExpression or start time arguments have been specified.

This FunctionProvider has the arguments shown in the following table:

Transactions in Quartz

Excluding a few minor exceptions, Quartz performs the same transactions in a standalone application or inside a full-blown J2EE Container. One of these exceptions is the use of global JTA transactions inside a JTA-complaint container. To enable the creation of a new JTA transaction or to join to an existing JTA transaction, just set the org.quartz.scheduler.wrapJobExecutionInUserTransaction property inside the quartz.properties file to true. Enabling this parameter allows the Quartz job to participate inside a global JTA transaction. This in combination with a JTA workflow implementation puts the workflow step and the temporal task into one transaction, thus assuring the information integrity.

JobStores

The JobStore interface designed in Quartz is responsible for the persistence and retrieval of all job and trigger data. There are two built-in implementations of the JobStore interface, the RamJobStore and the JDBCJobStore.

The RamJobStore stores the job, trigger, and calendar data in memory, losing its contents after JVM restarts. On the other hand, JDBCJobStore uses the JDBC API to store the same data.

The JDBCJobStore uses a delegate to use specific functions of each database, for example, DB2, PostgreSQL, etc.

The JobStore configuration is located in the quartz.properties file. To set the JobStore, add the following line to the configuration file, if you want to use the RamJobStore:

    org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore

To use local JDBC transactions, you only need to set the following parameters:

    org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreTX
    org.quartz.jobStore.dataSource = jdbc/defaultDS

The datasource is your datasource JNDI name.

To use global JTA transactions, you need the following parameters:

    org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreCMT 
    org.quartz.jobStore.dataSource = jdbc/defaultDS 
    org.quartz.jobStore.nonManagedTXDataSource = jdbc/nonTXDatasource

This differs from the JDBC transaction mode in its use of a non-JTA managed datasource for internal JobStore use.

For both transaction modes you need to set the database delegate appropriate for your database.

    org.quartz.jobStore.driverDelegateClass= 
                                  org.quartz.impl.jdbcjobstore.StdJDBCDelegate

The delegates included with Quartz are as follows:

Example Application—Customer Support

Some customer support requests come from mail or web interfaces. Suppose you have an web application that receives customer support requests. A typical customer support process is as follows:

This is the most simple of processes and the most commonly implemented. While in the pending state, the request can be forwarded to many people to finally reach completion. If the request is stalled in this state, the process doesn't add value to the business and doesn't match customer expectations, thereby downgrading the company image and customer loyalty. So a good approach to the process would be to reduce the percentage of support requests in the pending state. If a support request is in the same state for two hours, an e-mail to the customer support coordinator is send, and if a six hour threshold is exceeded an email is send directly to the customer support manager for notification purposes. These notifications assure the request will never be accidentally forgotten. The decision flow is depicted in the following figure:

To implement this process logic, we need temporal support in our business process.

Obviously this is done by Quartz. The workflow definition is as follows:

    <?xml version="1.0" encoding="UTF-8"?> 
    <!DOCTYPE workflow PUBLIC "-//OpenSymphony Group//DTD OSWorkflow 2.6 
                                               //EN" "http://www.opensymphony.com/ 
                                                   osworkflow/workflow_2_8.dtd"> 
    <workflow> 
       <initial-actions> 
          <action id="100" name="Start Workflow"> 
            <pre-functions> 
              <function type="class"> 
                  <arg name="class.name">packtpub.osw.ScheduleJob 
                  </arg> 
                  <arg name="jobName">TwoHourMail 
                  </arg> 
                  <arg name="jobClass">packtpub.osw.SendMailIfActive 
                  </arg> 
                  <arg name="triggerName">MailIfActive2hTrigger 
                  </arg> 
                  <arg name="triggerId">10 
                  </arg> 
                  <arg name="schedulerStart">false 
                  </arg> 
                  <arg name="local">true 
                  </arg> 
                  <arg name="groupName">CustomerSupportJobs 
                  </arg> 
                  <arg name="cronExpression">0 0 */2 * * ? 
                  </arg> 
                </function> 
                <function type="class"> 
                  <arg name="class.name">packtpub.osw.ScheduleJob 
                  </arg> 
                  <arg name="jobName">SixHourMail 
                  </arg> 
                  <arg name="jobClass">packtpub.osw.SendMailIfActive 
                  </arg> 
                  <arg name="triggerName">MailIfActive6hTrigger 
                  </arg> 
                  <arg name="triggerId">10 
                  </arg> 
                  <arg name="schedulerStart">false 
                  </arg> 
                  <arg name="local">true 
                  </arg> 
                  <arg name="groupName">CustomerSupportJobs 
                  </arg> 
                  <arg name="cronExpression">0 0 */6 * * ? 
                  </arg> 
                </function> 
             </pre-functions> 
             <results> 
                <unconditional-result old-status="Finished" 
                                                  status="Pending" step="1" /> 
             </results> 
          </action> 
        </initial-actions> 
        <steps> 
          <step id="1" name="Pending"> 
             <actions> 
               <action id="1" name="Finish request" finish="true"> 
                 <results> 
                    <unconditional-result old-status="Finished" step="2" 
                                                               status="Finished" /> 
                 </results> 
               </action> 
             </actions> 
          </step> 
        </steps> 
     </workflow>

     dataMap.putAll(args); 

     package packtpub.osw; 
     import java.util.Date; 
     import java.util.Properties; 
     import javax.mail.Message; 
     import javax.mail.Session; 
     import javax.mail.Transport; 
     import javax.mail.internet.InternetAddress; 
     import javax.mail.internet.MimeMessage; 
     import org.quartz.Job; 
     import org.quartz.JobExecutionContext; 
     import org.quartz.JobExecutionException; 
     import org.quartz.SchedulerException; 
     import com.opensymphony.workflow.Workflow; 
     import com.opensymphony.workflow.basic.BasicWorkflow; 
    /** 
      * Quartz job that send an email if the specified workflow is active. 
      */ 
    public class SendMailIfActive implements Job 
    { 
       public void execute(JobExecutionContext ctx) throws 
                                                        JobExecutionException 
       { 
          long wfId = ctx.getJobDetail().getJobDataMap() 
                                                      .getLong("entryId"); 
          String username = ctx.getJobDetail().getJobDataMap() 
                                                      .getString("username"); 
          String to = ctx.getJobDetail().getJobDataMap().getString("to"); 
          String from = ctx.getJobDetail().getJobDataMap() 
                                                      .getString("from"); 
          String subject = ctx.getJobDetail().getJobDataMap() 
                                                      .getString("subject"); 
          String text = ctx.getJobDetail().getJobDataMap() 
                                                      .getString("text"); 
          String smtpHost = ctx.getJobDetail().getJobDataMap() 
                                                      .getString("smtpHost"); 
          String triggerName = ctx.getJobDetail().getJobDataMap() 
                                                   .getString("triggerName"); 
          String groupName = ctx.getJobDetail().getJobDataMap() 
                                                   .getString("groupName"); 
          Workflow workflow = new BasicWorkflow(username); 
          long state = workflow.getEntryState(wfId); 
          System.out.println("State:" + state + " for wf:" + wfId); 
          if(state != 4) 
          { 
             sendMail(smtpHost, from, to, subject, text); 
          } else 
             { 
                try 
                { 
                  ctx.getScheduler().unscheduleJob(triggerName, groupName); 
                } catch (SchedulerException e) 
                  { 
                     e.printStackTrace(); 
                  } 
             } 
       } 
       private void sendMail(String smtpHost, String from, String to, 
                                                     String subject, String text) 
       { 
         Properties props = new Properties(); 
         props.put("mail.smtp.host", smtpHost); 
         Session sendMailSession = Session.getInstance(props, null); 
         try 
         { 
            Transport transport = sendMailSession.getTransport("smtp"); 
            Message message = new MimeMessage(sendMailSession); 
            message.setFrom(new InternetAddress(from)); 
            message.setRecipient(Message.RecipientType.TO, new 
                                                    InternetAddress(to)); 
            message.setSubject(subject); 
            message.setSentDate(new Date()); 
            message.setText(text); 
            message.saveChanges(); 
            transport.connect(); 
            transport.sendMessage(message, message.getAllRecipients()); 
            transport.close(); 
         } catch (Exception e) 
            { 
               e.printStackTrace(); 
            } 
       } 
     }

This completes the proactive workflow solution commonly requested by users.

Summary

In this article, we covered the integration of the Quartz job-scheduling system with OSWorkflow, which provided temporal capabilities to OSWorkflow. We also took a look at the trigger-functions, which are executed when a Quartz trigger fires. We also learned how to schedule a job from a Workflow definition by using ScheduleJob. Finally, we showed the capabilities of the Quartz-OSWorkflow duo with the help of a sample application.

Get your workflow up and running with this step-by-step guide authored by an active developer of the OSWorkflow project with real-world examples. Basics of OSWorkflow Integrating business rules with Drools Task scheduling with Quartz For more information, please visit: http://www.packtpub.com/OSWorkflow-Java-open-source-Business-Process-Management/book