Merge pull request #464 from rthouvenin/CRM-21460

CRM-21460 Add job execution hooks

docs/hooks/hook_civicrm_postJob.md

+# hook_civicrm_postJob
+
+## Summary
+
+This hook is called after a scheduled job is executed or was interrupted by an exception.
+
+## Notes
+
+We suspect this hook will be useful for developers who want to monitor the execution time of scheduled jobs or check whether a job is stuck (started but never ends). It can also be used to monitor the execution status of jobs. It is useful in combination with the hook `hook_civicrm_preJob`.
+
+## Definition
+
+```php
+hook_civicrm_postJob($job, $params, $result) 
+```
+
+## Parameters
+
+ - $job - instance of CRM_Core_DAO_Job, the executed job 
+ - $params - array of arguments given to the job
+ - $result - It can be:
+   + the array returned by the API call of the job
+   + the exception that interrupted the execution of the job
+
+## Return
+None
+
+## Example
+
+```php
+function sencivity_civicrm_postJob($job, $params, $result) {
+  if ($result['is_error']) {
+    CRM_Core_Error::debug_log_message("Job $job->name failed!");
+  }
+}
+```

docs/hooks/hook_civicrm_preJob.md

+# hook_civicrm_preJob
+
+## Summary
+
+This hook is called before a scheduled job is executed.
+
+## Notes
+
+This hook does not allow aborting the job execution or modifying its parameters.
+
+We suspect this hook will be useful for developers who want to monitor the execution time of scheduled jobs or check whether a job is stuck (started but never ends). It is useful in combination with the hook `hook_civicrm_postJob`.
+
+## Definition
+
+```php
+hook_civicrm_preJob($job, $params) 
+```
+
+## Parameters
+
+ - $job - instance of CRM_Core_DAO_Job, the job to be executed
+ - $params - array of arguments to be given to the job
+
+## Return
+None

docs/hooks/list.md

@@ -152,6 +152,8 @@ This is an overview list of all available hooks, listed by category.
 * **[hook_civicrm_membershipTypeValues](/hooks/hook_civicrm_membershipTypeValues.md)** - called when composing the array of membership types and their costs during a membership registration (new or renewal).
 * **[hook_civicrm_notePrivacy](/hooks/hook_civicrm_notePrivacy.md)** - provides a way to override the default privacy behavior for notes.
 * **[<del>hook_civicrm_optionValues</del>](/hooks/hook_civicrm_optionValues.md)** - deprecated in 4.7 in favor of [hook_civicrm_fieldOptions](/hooks/hook_civicrm_fieldOptions.md).
+* **[hook_civicrm_preJob](/hooks/hook_civicrm_preJob.md)** - called before executing a scheduled job.
+* **[hook_civicrm_postJob](/hooks/hook_civicrm_postJob.md)** - called after executing a scheduled job.
 * **[hook_civicrm_queryObjects](/hooks/hook_civicrm_queryObjects.md)** - called while building the core search query, allowing you to provide your own query objects which alter or extend the core search.
 * **[hook_civicrm_recent](/hooks/hook_civicrm_recent.md)** - called before storing recently viewed items.
 * **[hook_civicrm_tokens](/hooks/hook_civicrm_tokens.md)** - called to allow custom tokens to be defined.