Creating a Job

To create a Job that will be triggered as a result of end-user activity:

1. Open your existing code.

2. Isolate the part of the code that should be executed as a job.
   This code should be a viable script that performs some sort of action that can be run at a later time without disturbing the general functionality (such as sending an e-mail, confirming a credit card etc.).

3. Put the code into a file and name the file. The location and the name of the file will become the value of the URL parameter therefore always provide descriptive names and place job files in the same location.

4. In the original code, replace the code you removed with a call to the Job Queue function createHttpJob.

5. In the function, pass additional GET parameters in the job's URL query string, to handle different data.

6. Publish the fixed code to your webserver.

The next time the code is used the job will be triggered inside the code. To find out how the job ran go to Monitor | Jobs.

To see what jobs are currently running go to Monitor | Queue Statistics.

For additional information on handling jobs see Managing Jobs.

Example:

The following example shows what the original code looks like. How it will look like using the Job Queue API, and what the new Job file looks like.

Before converting to a job:

<?php
function validate_credit_card_number($string)
{
    if(preg_match('/^([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{2,4})$/', $string))
    {
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}
// here we call the function to validate the credit card validate_credit_card_number($_POST['credit_code']);

Instead of calling the function from inside the script we will create a job that will be executed when we specify it to run. The script will be replaced with a call to the Job Queue API as follows:

The application script after modification:

<?php


$cc = $_POST['credit_card'];


$q = new ZendJobQueue();


$ts = date('Y-m-d H:i:s', time()+10);


$id=$q->createHttpJob('/jobs/validate_credit_card.php',array('credit_card'=>$cc),array('name'=>'Credit


card validation using a single job execution scheduled to run after 10 seconds','schedule_time'=>$ts));


if(!$id){


exit(1);



The new job script:

The job script:
<?php
function validate_credit_card_number($string)
{
    if(preg_match('/^([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{2,4})$/', $string))
    {
        return ZendJobQueue::setCurrentJobStatus(ZendJobQueue::OK);
    }
    else
    {
        return ZendJobQueue::setCurrentJobStatus(ZendJobQueue::FAILED);
    }
}

$params = ZendJobQueue::getCurrentJobParams();

validate_credit_card_number($params['credit_card']);
?>

To create a recurring job:

1. Follow the instructions in Queued Jobs to create an createHttpJob job using the API.

2. Pass the schedule option as part of the options parameter to describe the recurrance schedule.

The schedule option is a CRON-like expression that consists of string with 5 fields separated by spaces. The fields define the minute, hour, day of month, month and day of week (in this order) in which the job will run.

Example:

The following example represents a job that will run every day at 3:15am:

$job = $jq->createHttpJob('http://localhost/jobs/feed/405', null, array(

'schedule' => '15 3 * * *'

Field

Range

Comments

Minute

0 - 59

Hour

0 - 23

In 24 hour format, where 0 is midnight

Day of Month

1 - 31

29,30 and 31 will only work for months of that length

Month

1 - 12

Day of Week

0 - 7

Sunday is either 0 or 7

To create a time deferred task:

1. Follow the instructions in Queued Jobs to create an createHttpJob job using the API.

2. Pass a date/time string as the schedule_time option, as part of the options array passed as the 3rd parameter to createHttpJob().

Note

The format used in date() to pass the execution time – this is an SQL-like ‘YYYY-MM-DD hh:mm:ss’format (e.g. “2009-06-25 23:45:00” for June 25th 2009 at 45 minutes past 11pm).

Zend Job Queue is not designed to execute jobs exactly on the specified time. For example, if the queue is limited to execute 10 jobs concurrently (more on that later on), and 1,000 jobs are scheduled for the exact same time – jobs will have to wait until other jobs finish. You should consider the schedule_time option as a request not to run a job before this time.

Example:

The following example shows a time-deferred task that has been scheduled to run a process at 2:00am.

$options = array(

'schedule_time' => date('Y-m-d h:i:s', strtotime('tomorrow 2am'))

);

$jq->createHttpJob('http://localhost/jobs/formproc.php', $_POST, $options);

Note:

the format used in date() to pass the execution time – this is an SQL-like ‘YYYY-MM-DD hh:mm:ss’ format (e.g. "2009-.6-25 23:45:00" for June 25th 2009 at 45 minutes past 11pm).

To create a recurring job:

1. In the administration Interface go to Rule Management | Recurring Jobs

2. Click to open the New Scheduling Rule page.

3. Enter the following rule related information:

   1. URL - the path indicating to where the code is for the job to execute and the server on which to run it.

   2. Name - Optional, a name describing the job

   3. Application - Optional, the name of the application the job is related to. This information can be used for grouping jobs.

4. Define when the job should run by using the time options (Hourly, Daily, Weekly or Monthly). Selecting an option will change the parameters displayed. For example selecting daily will display hour and minute options whereas, weekly will display the days of the week.
   When all the settings are properly defined, the "Create Rule" button will change from Grey to Blue.

5. Click to save the changes.

As soon as the new Recurring Job is saved, it will be put in the Job Queue at the time specified in the Rule.

To find out how the job ran go to Monitor | Jobs.

To see what jobs are currently running go to Monitor | Queue Statistics.

For additional information on handling jobs see Managing Jobs.

Note:

The Jobs and Queues Statistics pages display information about all the Jobs in your system, including Jobs triggered by the Job Queue API.

Related Links:

Filtering Jobs

Jobs