Creating a Job

Creating a Job is easy. First, create a PHP file named in the standard Concrete CMS lowercase manner (with underscores) for whatever you're doing. For example, if you're making job for Summarizing Statistics, for example, you might name it "summarize_statistics.php".

Next, place this file in the application/jobs directory. (If you want to include this job as part of a package, will deal with that later.)

Then, open the file and place a PHP class within this file that matches the name of the filename, and that extends the \Concrete\Core\Job\Job class.

<?php
namespace Application\Job;
use \Concrete\Core\Job\Job as AbstractJob;

class SummarizeStatistics extends AbstractJob
{

    public function getJobName()
    {
        return t("Summarize Statistics.");
    }

    public function getJobDescription()
    {
        return t("Takes all detailed statistics and summarizes them.");
    }

    public function run()
    {
    }
}

The Job class name should be a StudlyCapsed version of the filename exactly. (Note: unlike other Concrete classes, it does not end with what it is extending, e.g. Job.) It exists within the Application\Job namespace. All job classes ought to have a getJobName() and getJobDescription() method. These populate the content as shown on the Jobs Dashboard page. Finally, Jobs get a run() method. It is this method that contains the logic that gets executed when a Job is run. Any special summarizing logic that you need to summarize your statistics would be placed within this run() method.

Results

Any string returned by the run() method will automatically be displayed in the Jobs Dashboard interface. Typically this string contains a detailed success method, including the number of items that were successfully processed by the job.

Error Handling

Job error handling happens by throwing exceptions. Simply throw an exception from within your Job and the Dashboard UI will show that the last run of the Job resulted in an error.

Installing the Job

Any job found within the application/jobs directory still needs to be installed before it can be run. This can easily be done through the Dashboard > System & Settings > Optimization > Jobs Dashboard page. Uninstalled Jobs appear at the bottom of the page.

Including in a Package

Including a custom job that you've written for the Application namespace (and placed in application/jobs) in a Package is easy. Let's say you've got a package named "SuperStats" that you want to place your Summarize Statistics Job In. First, create a jobs directory within your package's directory:

packages/super_stats/jobs/

Then, place the class in the jobs directory so you have packages/super_stats/jobs/summarize_statistics.php

Next, you'll need to modify the namespace of your Job. So

namespace Application\Job;

becomes

namespace Concrete\Package\SuperStats\Job;

Finally, you'll need to install your Job within your package's install() method, rather than through the UI. From within your Concrete SuperStats Package, you'll need to add this code.

public function install()
{
    $pkg = parent::install();
    \Concrete\Core\Job\Job::installByPackage('summarize_statistics', $pkg);
}

This is, of course, in addition to anything else that your package's install() method currently contains.

When uninstalling a package, any jobs that that package has installed are automatically uninstalled. You don't need to write custom code to do it.