Creating a Job

Creating a Job is easy. First, create a PHP file named in the standard concrete5 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.

The Job class name should be a StudlyCapsed version of the filename exactly. (Note: unlike other concrete5 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 concrete5 SuperStats Package, you'll need to add this code.