layout: default

group: config-guide

subgroup: 12_cron

title: Configure a custom cron job and cron group (tutorial)

menu_title: Configure a custom cron job and cron group (tutorial)

menu_order: 3

menu_node:

version: 2.0

github_link: config-guide/cron/custom-cron-tut.md

This tutorial shows you step-by-step how to create a custom cron job and optionally a cron group in a sample {% glossarytooltip c1e4242b-1f1a-44c3-9d72-1d5b1435e142 %}module{% endglossarytooltip %}. You can use a module you already have or you can use a sample module from our [`magento2-samples` repository](https://github.com/magento/magento2-samples){:target="_blank"}.

Running the cron job results in a row being added to the `cron_schedule` table with the name of the cron job, `custom_cron`.

We also show you how to optionally create a cron group, which you can use to run custom cron jobs with settings other than Magento application defaults.

In this tutorial, we assume the following:

* The Magento application is installed in `/var/www/html/magento2`

* Your Magento database user name and password are both `magento`

* You perform all actions as the [Magento file system owner]({{ page.baseurl }}install-gde/prereq/file-sys-perms-over.html)

To set up a custom cron job, you need a sample module. We suggest the `magento-module-minimal` module.

If you already have a sample module, you can use it; skip this step and the next step and continue with [Step 3: Create a class to run cron](#cron-tut-class).

{% collapsible To get a sample module: %}

1. Log in to your Magento server as, or switch to, the [Magento file system owner]({{ page.baseurl }}install-gde/prereq/file-sys-perms-over.html).

2. Change to a directory that is not in your Magento application root (for example, your home directory).

2. Clone the [`magento2-samples` repository](https://github.com/magento/magento2-samples){:target="_blank"}.

For example,

cd ~

git clone [email protected]:magento/magento2-samples.git

If the command fails with the error `Permission denied (publickey).`, you must [add your SSH public key to github.com](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account){:target="_blank"}.

4. Make a directory to which to copy the sample code:

mkdir -p /var/www/html/magento2/app/code/Magento/SampleMinimal

5. Copy the sample module code:

cp -r ~/magento2-samples/sample-module-minimal/* /var/www/html/magento2/app/code/Magento/SampleMinimal

5. Verify the files copied properly:

ls -al /var/www/html/magento2/app/code/Magento/SampleMinimal

You should see the following result:

drwxrwsr-x. 4 magento_user apache 4096 Oct 30 13:19 .

drwxrwsr-x. 121 magento_user apache 4096 Oct 30 13:19 ..

-rw-rw-r--. 1 magento_user apache 372 Oct 30 13:19 composer.json

drwxrwsr-x. 2 magento_user apache 4096 Oct 30 13:19 etc

-rw-rw-r--. 1 magento_user apache 10376 Oct 30 13:19 LICENSE_AFL.txt

-rw-rw-r--. 1 magento_user apache 10364 Oct 30 13:19 LICENSE.txt

-rw-rw-r--. 1 magento_user apache 1157 Oct 30 13:19 README.md

-rw-rw-r--. 1 magento_user apache 270 Oct 30 13:19 registration.php

drwxrwsr-x. 3 magento_user apache 4096 Oct 30 13:19 Test

6. Update the Magento database and schema:

php /var/www/html/magento2/bin/magento setup:upgrade

{% endcollapsible %}

Before you continue, make sure the sample module is registered and enabled.

{% collapsible To verify the sample module: %}

1. Log in to the Magento Admin as an administrator.

2. Click **Stores** > **Configuration** > ADVANCED > **Advanced**.

3. In the right pane, under Disable Modules Output, look for **Magento_SampleMinimal** as the following figure shows.

{:width="900px"}

If the module doesn't display, review [step 1](#cron-tut-get) carefully. Make sure your code is in the correct directory. Spelling and case are important; if anything is different, the module won't load. Also, don't forget to run `magento setup:upgrade`.

{% endcollapsible %}

This step shows a simple class to create a cron job. The class only writes a row to the `cron_schedule` table that confirms it's set up successfully.

{% collapsible To create a class: %}

1. Create a directory for the class and change to that directory:

mkdir /var/www/html/magento2/app/code/Magento/SampleMinimal/Cron && cd /var/www/html/magento2/app/code/Magento/SampleMinimal/Cron

2. Created a file named `Test.php` in that directory with the following contents:

{% highlight php %}

$this->logger = $logger;

}

/**

* Write to system.log

*

* @return void

*/

public function execute() {

$this->logger->info('Cron Works');

}

}

{% endhighlight %}

{% endcollapsible %}

## Step 4: Create `crontab.xml` {#cron-tut-crontab}

`crontab.xml` sets a schedule to run your custom cron code.

{% collapsible To create crontab.xml: %}

Create `crontab.xml` as follows in the `/var/www/html/magento2/app/code/Magento/SampleMinimal/etc` directory:

{% highlight xml %}

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Cron:etc/crontab.xsd">

<group id="default">

<job name="custom_cronjob" instance="Magento\SampleMinimal\Cron\Test" method="execute">

<schedule>* * * * *</schedule>

</job>

</group>

</config>

{% endhighlight %}

The preceding `crontab.xml` runs the `Magento/SampleMinimal/Cron/Test.php` class once per minute, resulting in a row being added to the `cron_schedule` table.

{% endcollapsible %}

This step shows how to verify the custom cron job successfully using a SQL query on the `cron_schedule` database table.

{% collapsible To verify cron: %}

1. Run Magento cron jobs:

php /var/www/html/magento2/bin/magento cron:run

2. Enter the `magento cron:run` command two or three times.

The first time you enter the command, it queues jobs; subsequently, the cron jobs are run. You must enter the command _at least_ twice.

2. Run the SQL query `SELECT * from cron_schedule WHERE job_code like '%custom%'` as follows:

1. Enter `mysql -u magento -p`

2. At the `mysql>` prompt, enter `use magento;`

3. Enter `SELECT * from cron_schedule WHERE job_code like '%custom%';`

The result should be similar to the following:

+-------------+----------------+---------+----------+---------------------+---------------------+---------------------+---------------------+

| schedule_id | job_code | status | messages | created_at | scheduled_at | executed_at | finished_at |

+-------------+----------------+---------+----------+---------------------+---------------------+---------------------+---------------------+

| 3670 | custom_cronjob | success | NULL | 2016-11-02 09:38:03 | 2016-11-02 09:38:00 | 2016-11-02 09:39:03 | 2016-11-02 09:39:03 |

| 3715 | custom_cronjob | success | NULL | 2016-11-02 09:53:03 | 2016-11-02 09:53:00 | 2016-11-02 09:54:04 | 2016-11-02 09:54:04 |

| 3758 | custom_cronjob | success | NULL | 2016-11-02 10:09:03 | 2016-11-02 10:09:00 | 2016-11-02 10:10:03 | 2016-11-02 10:10:03 |

| 3797 | custom_cronjob | success | NULL | 2016-11-02 10:24:03 | 2016-11-02 10:24:00 | 2016-11-02 10:25:03 | 2016-11-02 10:25:03 |

+-------------+----------------+---------+----------+---------------------+---------------------+---------------------+---------------------+

3. (Optional) Verify messages are written to Magento's system log:

cat /var/www/html/magento2/var/log/system.log

You should see one or more entries like the following:

[2016-11-02 22:17:03] main.INFO: Cron Works [] []

These messages come from the `execute` method in `Test.php`:

public function execute() {

$this->logger->info('Cron Works');

If the SQL command and system log contain no entries, run the `magento cron:run` command a few more times and wait. It can take some time for the database to update.

{% endcollapsible %}

This step shows how to optionally set up a custom cron group. You should set up a custom cron group you want your custom cron job to run on a different schedule than other cron jobs (typically, once per minute) or if you want several custom cron jobs to run with different settings.

{% collapsible To set up a custom cron group: %}

1. Open `crontab.xml` in a text editor.

2. Change `<group id="default">` to `<group id="custom_crongroup">`

3. Exit the text editor.

4. Create `/var/www/html/magento2/app/code/Magento/SampleMinimal/etc/cron_groups.xml` with the following contents:

{% highlight xml %}

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Cron:etc/cron_groups.xsd">

<group id="custom_crongroup">

<schedule_generate_every>1</schedule_generate_every>

<schedule_ahead_for>4</schedule_ahead_for>

<schedule_lifetime>2</schedule_lifetime>

<history_cleanup_every>10</history_cleanup_every>

<history_success_lifetime>60</history_success_lifetime>

<history_failure_lifetime>600</history_failure_lifetime>

</group>

</config>

{% endhighlight %}

For a description of what the options mean, see [Configure custom cron jobs and cron groups reference]({{ page.baseurl }}config-guide/cron/custom-cron-ref.html).

{% endcollapsible %}

This step shows how to verify your custom cron group using the {% glossarytooltip 18b930cf-09cc-47c9-a5e5-905f86c43f81 %}Magento Admin{% endglossarytooltip %}.

{% collapsible To verify your custom cron group: %}

1. Run Magento cron jobs for your custom group:

php /var/www/html/magento2/bin/magento cron:run --group="custom_crongroup"

Run the command at least twice.

2. Clean the Magento cache:

php /var/www/html/magento2/bin/magento cache:clean

2. Log in to the Magento Admin as an administrator.

3. Click **Stores** > **Configuration** > **Advanced** > **System**.

4. In the right pane, expand **Cron**.

Your cron group displays as follows:


{% endcollapsible %}

The Magento 2 sample modules provide a demonstration of many programming techniques, including adding a CLI command using {% glossarytooltip 2be50595-c5c7-4b9d-911c-3bf2cd3f7beb %}dependency injection{% endglossarytooltip %}. Look at the <a href="https://github.com/magento/magento2-samples/tree/master/sample-module-command" target="_blank">`sample-module-command`</a> for an example. The module's <a href="https://github.com/magento/magento2-samples/blob/master/sample-module-command/README.md" target="_blank">README.md</a> discusses how to install it.

<h2 id="cli-autoload">Add CLI commands using the Composer autoloader</h2>

To be added at a later time.

<a href="https://github.com/magento-south/magento2-samples/tree/MAGETWO-55017/sample-external-links">Sample module on github</a>

* <a href="https://github.com/magento/magento2-samples" target="_blank">Sample extensions</a> created by the Magento 2 Core team

Magento has a sample [module-sample-scss](https://github.com/magento/magento2-samples/tree/master/module-sample-scss) {% glossarytooltip c1e4242b-1f1a-44c3-9d72-1d5b1435e142 %}module{% endglossarytooltip %} implementing the {% glossarytooltip 45f1f76d-91cd-4789-a8b5-1e3f321a6280 %}Sass{% endglossarytooltip %} preprocessor.

You can view it as example when adding your custom preprocessor. Or install the module as is if you need to add Sass preprocessing. Installing a module is described in the [repository's Readme file](https://github.com/magento/magento2-samples/blob/master/README.md).

For illustration, see the adapter for Sass in the sample module: [module-sample-scss/Preprocessor/Adapter/Scss/Processor.php](https://github.com/magento/magento2-samples/blob/master/module-sample-scss/Preprocessor/Adapter/Scss/Processor.php)

<div class="bs-callout bs-callout-info" id="info">

<p>If you choose to create a separate dedicated module, you can use the <a href="https://github.com/magento/magento2-samples/tree/master/sample-module-minimal">Magento_SampleMinimal module from the Magento 2 sample modules repository</a> as example of a minimal module you need. If you will copy and use Magento_SampleMinimal, do not forget to enter your vendor and module naming, instead the ones used in the sample, in the <code>&lt;your_module_dir&gt;/etc/module.xml</code>, <code>&lt;your_module_dir>/registration.php</code>, and <code>&lt;your_module_dir>/composer.json</code> files .</p>

<p>If you decide to use the existing module, keep in mind, that theme declaring might be affected when the module is changed.</p>

</div>

../../../v2.0/config-guide/cron/custom-cron-tut.md

To simplify the development of a new payment integration, Magento developed the [Payment sample module](https://github.com/magento/magento2-samples/tree/master/sample-module-payment-gateway).

It contains all required infrastructure and you can use it as starting point.

</table>

You can use the [sample Magento_SamplePaymentGateway module](https://github.com/magento/magento2-samples/tree/master/sample-module-payment-gateway) files as basis for your custom module structure and files.

../../../v2.1/config-guide/cron/custom-cron-tut.md