Document how to create cron jobs

By providing default configuration, see simplenews as an example.

You're welcome to update the documentation with patches.

Do you have any plans about hook_cronapi()?

In my case I need to create few cron jobs in one module so hook_cron is bad option.

Config of ultimate_cron.job can be implemented.

Example is in simplenews/config/optional/ultimate_cron.job.simplenews_job.yml

Added documentation in the api file.

Fixed the character limit.

Think it would be useful to document the process for creating the config items and importing those something along the lines of:

• In your custom module at module_name/config/optional add a file in the format ultimate_cron.job.cron_job_name.yml
• Create a config file in line with the code example below.
• Clear your sites caches and import your config.
• If the cron job is not showing up in the cron list after hitting 'Discover Jobs' try either importing the config item by copy/paste under 'Configuration Synchronization' and hitting 'Discover Jobs' again.

Code Example (lives at 'modules/custom/module_name/config/optional')

langcode: en
status: true
dependencies:
  module:
    - your_module_name
title: 'Your Admin Vanity Title'
id: your_unique_cron_job_id
weight: 0
module: your_module_name
callback: your_function_name_in_your_dot_module_file
scheduler:
  id: simple
launcher:
  id: serial
logger:
  id: database

If ultimate_cron/ultimate_cron.api.php is not valid anymore it would be good to remove it together with the readme update

First off, i want to thank the people who ported this awesome module from D7 to D8, great job! Now to make it easier for people to start using the 8.x version, the information how to get it working, needs to be updated as well. Currently the only way to get it to work is either analyze the source code or through this issue. But this process should be much simpler and the work done here is pointing in the right direction.

We should update the informational parts in the code (the readme and cronapi part) as done in here, but also the module overview page should reflect how to use the D8 version, currently the infomration there is about the D7 version so it can be misleading for people using D8 and cause them to think that the module does not work.

I added the readme update from batigolix to the readme file of the D8 version as well and kept the hint added by Ginovski in ultimate_cron.api.php as thats another place people would look for information. I am not sure wheter INSTALL.txt should be updated as well.

I hope that this issue gets resolved soon, as it might cause people to think that the awesome D8 version does not work, when in fact it just needs a little bit of configuration that is a bit tricky to find at first currenly.

PS! This is only my second time uploading patches, so i do apologize if i got something wrong. Looking forward to the feedback.

Hi @ainarend.

Thanks for the patch, looks like the testbot doesn't like it, seems to be created from the UI.

Maybe https://www.drupal.org/node/707484 can help with creating a working patch.

Hey @Berdir.

Yes, I understand now what i did wrong, I am still new to the workflows in DO. Here goes my new attempt with a patch created using git, thanks for the link :) Hopefully i got it right, sorry for the inconvenience.

No other differences from #13.

Don't forget to set the status to needs review when uploading a patch.

Note that the default hook_cron() hooks are still supported automatically, it's only when you want to provide different configuration by default or multiple/additional cron jobs in a module that you need to add the configuration.

Also, the easiest approach IMHO is to configure one the automatically created cron jobs in the UI to be like you want it, then export that and change the callback.

Also a bit unsure about adding a whole config example in there, changes are that will get out of date, but I guess it doesn't hurt.

Thank you for the feedback, updated to include your notes as well.

I was thinking about wheter to keep the link to simplenews git and the config example, but i think they add a lot the the DX so, i think we should keep them for now.

I see that i still havent gotten the patching right. I made some additional wording improvments and gave this another go from scratch. It applied cleanly to my local checkout, so hopefully this time i got it right. Sorry for all the failures.

Even with these changes to the module files in the 8x branch, I still think that the module overview page should reflect some information on how to properly use it for D8, as everything there seems to be about D7 branch. This module is too good to allow people to get the idea that it might not work with D8.

Yeah, the project page could certainly use some improvements. You could create an issue and make a suggestion, will need to be discussed with the maintainers of the 7.x branch. In our projects, we often focus on Drupal 8 on top, as most new projects and new users that need to learn about it probably use Drupal 8 now.

+++ b/ultimate_cron.api.php
@@ -11,7 +11,9 @@ use Drupal\ultimate_cron\Entity\CronJob;
 /**
- * Inform Ultimate Cron about cron jobs.
+ * Inform Ultimate Cron about cron jobs. To add additional/multiple cron jobs
+ * from a custom module, provide a default configuration in the module with
+ * the needed settings. Example: ultimate_cron.job.custom_module_cron.yml
  *
  * Note that the result of this hook is cached.

Per coding standards, a description should always start with a single line, then an empty line and then additional paragraphs, so this should move down a bit.

Other than that, looks like a good start on improving the docs to me.

Thanks for the review, I corrected the description.

I will probably have time to create the issue for updating the project page tomorrow, so if any one has time before that, feel free to go ahead and get started on it. Otherwise I will get to it tomorrow.

I didn't have time yesterday, but i created the follow up issue to get the work started for the project page update:
https://www.drupal.org/project/ultimate_cron/issues/2932700

Thanks, committed!

The easiest way to declare a cron job is tu use hook_cron()

.

The doc is wrong, hook_cron() will never be execute, so hook_cron() can't be used to create a cron job.

from #10:

<ul>
  <li>    In your custom module at module_name/config/optional add a file in the format ultimate_cron.job.cron_job_name.yml</li>
  <li>    Create a config file in line with the code example below.</li>
  <li>    Clear your sites caches and import your config.</li>
  <li>    If the cron job is not showing up in the cron list after hitting 'Discover Jobs' try either importing the config item by copy/paste under 'Configuration Synchronization' and hitting 'Discover Jobs' again. </li>
</ul>

it mentions import your config. How do you do that (with drush) when adding to already enabled module? I assume i need to manually import it with CMI UI? Drush cim or cr won't do this. This isnt a very deployable solution.

and in the patch from #22:

+To add a cron job you can use either hook_cron() or use configuration files with custom parameters
+for multiple/additional cron jobs in a module.
+
+The easiest way to declare a cron job is tu use hook_cron()
+and then configure the cron job through the UI and export it, then change the cron jobs callback method.

does this work? How? Same as D7? But it isnt functional on its own, you need to export and then modify through UI? Does that make sense? If you export (not sure what callback is to start with) and then change in UI, when you import again it will be reset.

I feel like in general this module is somewhat backwards from typical modules. It seems like it requires manually creating config files to create config and then importing these. Isn't a more standardized approach to have the UI create cron jobs? Add the callback there. Then, like normal, we'd do cex and this would dump the config file. Just a thought.

the discover jobs seems like a reasonable work around to not having a UI to add cron jobs:
- make module config file
- discover jobs
- cex

except discover jobs doesn't work to find new jobs added to config of an already enabled module - not sure what it does.

This is what i have ended up with:
- add config file to custom/mymodule/config/optional/ultimate_cron.job.cron_job_name.yml
- also add this file to config/sync
- drush cim
- modify in UI if needed
- drush cex

NOTES:
- adding to your config/optional is only for a module which has not yet been enabled; after that it isn't used for anything
- make sure cron_job_name in your yml file name matches the callback function as cex uses that to create the config file. If not named the same then you will now have 2 config files in config/sync for the same cron job and will fail when doing cim

I managed to get it running by:
- uninstall my custom module containing the callback function
- add config file to custom/mymodule/config/optional/ultimate_cron.job.cron_job_name.yml
- re-install my custom module
The cron job appeared in the list of jobs under /admin/config/system/cron/jobs even without triggering "Discover jobs".
- edit job configuration
- drush cex

@kreatIL

"uninstall my custom module containing the callback function" - this is not always (even rarely) possible though.

I am starting to get the sense (although very hard to tell from documentation) that hook_cron() might enable defining new cron tasks. The patch to README here even states: "To add a cron job you can use either hook_cron() "

but sadly it gives no details on how to do this. :(