Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit f1b3a85

Browse files
andrewnicolsandrewnicols
authoredJul 20, 2022
Merge pull request #308 from andrewnicols/migrateTasksApi
[docs] Document the Task API
2 parents e12f557 + f3c33e6 commit f1b3a85

File tree

13 files changed

+553
-2
lines changed

13 files changed

+553
-2
lines changed
 

‎data/migratedPages.yml

+3
Original file line numberDiff line numberDiff line change
@@ -1551,6 +1551,9 @@ Subject_Access_Request_FAQ:
15511551
Table_of_locales:
15521552
- filePath: "/general/development/process/translation/langpack/locales.md"
15531553
slug: "/general/development/process/translation/langpack/locales"
1554+
Task_API:
1555+
- filePath: "/docs/apis/subsystems/task/index.md"
1556+
slug: "/docs/apis/subsystems/task/"
15541557
Templates:
15551558
- filePath: "/docs/guides/templates/index.md"
15561559
slug: "/docs/guides/templates/"

‎docs/apis.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ The [Tag API](https://docs.moodle.org/dev/Tag_API) allows you to store tags (and
189189

190190
### Task API (task)
191191

192-
The [Task API](https://docs.moodle.org/dev/Task_API) lets you run jobs in the background. Either once off, or on a regular schedule.
192+
The [Task API](./apis/subsystems/task/index.md) lets you run jobs in the background. Either once off, or on a regular schedule.
193193

194194
### Time API (time)
195195

‎docs/apis/_files/db-tasks-example.php

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
$tasks = [
2+
[
3+
'classname' => 'mod_example\task\do_something',
4+
'blocking' => 0,
5+
'minute' => '30',
6+
'hour' => '17',
7+
'day' => '*',
8+
'month' => '1,7',
9+
'dayofweek' => '0',
10+
],
11+
];

‎docs/apis/_files/db-tasks-php.mdx

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!-- markdownlint-disable first-line-heading -->
2+
3+
The `db/tasks.php` file contains the initial schedule configuration for each of your plugins _scheduled_ tasks. Adhoc tasks are not run on a regular schedule and therefore are not described in this file.
4+
5+
:::caution Editing the schedule for an existing task
6+
7+
If an existing task is edited, it will only be updated in the database if the administrator has not customised the schedule of that task in any way.
8+
9+
:::
10+
11+
The following fields also accept a value of `R`, which indicates that Moodle should choose a random value for that field:
12+
13+
- minute
14+
- hour
15+
- dayofweek
16+
- day
17+
18+
See [db/tasks.php](../commonfiles/db-tasks.php/index.md) for full details of the file format.

‎docs/apis/_files/db-tasks-php.tsx

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/**
2+
* Copyright (c) Moodle Pty Ltd.
3+
*
4+
* Moodle is free software: you can redistribute it and/or modify
5+
* it under the terms of the GNU General Public License as published by
6+
* the Free Software Foundation, either version 3 of the License, or
7+
* (at your option) any later version.
8+
*
9+
* Moodle is distributed in the hope that it will be useful,
10+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
11+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12+
* GNU General Public License for more details.
13+
*
14+
* You should have received a copy of the GNU General Public License
15+
* along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16+
*/
17+
import React from 'react';
18+
import { ComponentFileSummary, type ComponentFileSummaryProps } from '../../_utils';
19+
import DefaultDescription from './db-tasks-php.mdx';
20+
// eslint-disable-next-line import/no-webpack-loader-syntax, import/no-unresolved
21+
import DefaultExample from '!!raw-loader!./db-tasks-example.php';
22+
23+
export default (initialProps: ComponentFileSummaryProps): JSX.Element => (
24+
<ComponentFileSummary
25+
defaultDescription={DefaultDescription}
26+
defaultExample={DefaultExample}
27+
filepath="/db/tasks.php"
28+
summary="Task schedule configuration"
29+
examplePurpose="Task schedule configuration"
30+
refreshedDuringUpgrade
31+
{...initialProps}
32+
/>
33+
);

‎docs/apis/_files/index.tsx

+2
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import DbMessagesPHP from './db-messages-php';
2828
import DbMobilePHP from './db-mobile-php';
2929
import DbRenamedclassesPHP from './db-renamedclasses-php';
3030
import DbServicesPHP from './db-services-php';
31+
import DbTasksPHP from './db-tasks-php';
3132
import DbUninstallPHP from './db-uninstall-php';
3233
import DbUpgradePHP from './db-upgrade-php';
3334
import EnvironmentXML from './environment-xml';
@@ -58,6 +59,7 @@ export {
5859
DbMobilePHP,
5960
DbRenamedclassesPHP,
6061
DbServicesPHP,
62+
DbTasksPHP,
6163
DbUninstallPHP,
6264
EnvironmentXML,
6365
Lang,

‎docs/apis/commonfiles/db-tasks.php/index.md

+148
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: db/tasks.php
3+
tags:
4+
- Plugins
5+
- Common files
6+
- Scheduled tasks
7+
description: A description of the plugin scheduled task configuration file
8+
---
9+
10+
import { LanguageProperty, Since } from '@site/src/components';
11+
12+
If a plugin wants to configure scheduled task, two items are required:
13+
14+
- a class extending the `\core\task\scheduled_task` class; and
15+
- the `db/tasks.php` file containing its initial configuration.
16+
17+
The general format of the file is as follows:
18+
19+
```php
20+
$tasks = [
21+
// First task configuration.
22+
[ ... ],
23+
24+
// Second task configuration.
25+
[ ... ],
26+
];
27+
```
28+
29+
Each task configuration entry has a number of possible properties, described below.
30+
31+
## Task configuration entries
32+
33+
### Classname
34+
35+
<LanguageProperty
36+
required
37+
types={["string"]}
38+
/>
39+
40+
The `classname` contains the fully-qualified class name where the scheduled task is located.
41+
42+
```php
43+
$tasks = [
44+
[
45+
'classname' => 'mod_example\task\do_something',
46+
// ...
47+
]
48+
]
49+
```
50+
51+
### Blocking
52+
53+
<LanguageProperty
54+
types={["integer"]}
55+
/>
56+
57+
Tasks can be configured to block the execution of all other tasks by setting the `blocking` property to a truthy value.
58+
59+
:::caution
60+
61+
Whilst this feature is available its use is _strongly_ discouraged and *will not* be accepted in Moodle core.
62+
63+
:::
64+
65+
```php
66+
$tasks = [
67+
[
68+
'classname' => 'mod_example\task\do_something',
69+
'blocking' => 1,
70+
// ...
71+
],
72+
];
73+
```
74+
75+
### Date and time fields
76+
77+
<LanguageProperty
78+
types={["string"]}
79+
/>
80+
81+
The following date and time fields are available:
82+
83+
- month
84+
- day
85+
- dayofweek
86+
- hour
87+
- month
88+
89+
Each of these fields accepts one, or more values, and the format for each field is described as:
90+
91+
```
92+
<fieldlist> := <range>(/<step>)(,<fieldlist>)
93+
<step> := int
94+
<range> := <any>|<int>|<min-max>|<random>
95+
<any> := *
96+
<min-max> := int-int
97+
<random> := R
98+
```
99+
100+
:::info Random values
101+
102+
A fixed random value can be selected by using a value of `R`. By specifying this option, a random day or time is chosen when the task is installed or updated. The same value will be used each time the task is scheduled.
103+
104+
:::
105+
106+
If no value is specified then the following defaults are used:
107+
108+
- Month: `*` (Every month)
109+
- Day: `*` (Every day)
110+
- Day of the week: `*` (Every day of the week)
111+
- Hour: `*` (Every hour)
112+
- Minute: `*` (Every minute)
113+
114+
:::info Day and Day of the week
115+
116+
If either field is set to `*` then use the other field, otherwise the soonest value is used.
117+
118+
:::
119+
120+
#### Examples
121+
122+
```php title="Run at a fixed time each day, randomised during installation of the task"
123+
$tasks = [
124+
[
125+
'classname' => 'mod_example\task\do_something',
126+
127+
// Every month.
128+
'month' => '*',
129+
// Every day.
130+
'day' => '*',
131+
132+
// A fixed random hour and minute.
133+
'hour' => 'R',
134+
'month' => 'R',
135+
],
136+
];
137+
```
138+
139+
```php title="Specifying multiple times in an hour"
140+
$tasks = [
141+
[
142+
'classname' => 'mod_example\task\do_something',
143+
144+
// At two intervals in the hour.
145+
'minute' => '5, 35',
146+
],
147+
];
148+
```

‎docs/apis/commonfiles/index.mdx

+5
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
DbMessagesPHP,
2020
DbRenamedclassesPHP,
2121
DbServicesPHP,
22+
DbTasksPHP,
2223
DbUninstallPHP,
2324
DbUpgradePHP,
2425
EnvironmentXML,
@@ -90,6 +91,10 @@ import extraLangDescription from '../_files/lang-extra.md';
9091

9192
<DbServicesPHP />
9293

94+
### db/tasks.php
95+
96+
<DbTasksPHP />
97+
9398
### db/renamedclasses.php
9499

95100
<DbRenamedclassesPHP />

0 commit comments

Comments
 (0)