Scheduled Tasks
The four endpoints that list scheduled tasks, switch them and run them by hand.
Overview
A scheduled task is the definition of work an installation does by itself: issuing invoices, suspending services, sending notices. These four endpoints list the tasks, show their jobs, switch them on and off and run them by hand.
A task and a job are not the same. A task is a rule, and every run of it leaves one or more jobs in the queue. The counts in the task list describe that rule's jobs.
Some tasks run in two stages: one that works out what to do, and one that carries out what was found. The counts and the filters respect that split.
Reference
Listing the Tasks
Returns every scheduled task on the installation with its state.
minute, hour, day, month, unknown.curl 'https://panel.example.com/api/v1/admin/automation/tasks' \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://panel.example.com/api/v1/admin/automation/tasks', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const broken = data.filter((t) => ! t.registered);$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// SWITCHED OFF and NO HANDLER are different things: the second points at a gap in setup.
$tasks = Api::Automation()->GetAutomationTasks()['data'];
$broken = array_filter($tasks, fn ($t) => ! $t['registered']);Listing a Task's Jobs
Returns the queue jobs belonging to one task.
curl 'https://panel.example.com/api/v1/admin/automation/tasks/invoice-create/jobs?limit=50' \
-H "Authorization: Bearer $API_KEY"const url = new URL(`https://panel.example.com/api/v1/admin/automation/tasks/${task}/jobs`);
url.searchParams.set('limit', '50');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
// Sonraki sayfa: url.searchParams.set('after_id', data.next_after)$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks/' . $task . '/jobs?' . http_build_query(['limit' => 50]));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// This endpoint walks FORWARD while the general feed walks back. Do not mix the two.
$page = Api::Automation()->GetAutomationTaskJobs(['task' => $task], ['limit' => 50])['data'];
$next = Api::Automation()->GetAutomationTaskJobs(['task' => $task], [
'after_id' => $page['next_after'],
]);Switching a Task On and Off
Decides whether a task runs at all.
curl -X PUT 'https://panel.example.com/api/v1/admin/automation/tasks/invoice-create/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":0}'const res = await fetch(`https://panel.example.com/api/v1/admin/automation/tasks/${task}/status`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: 0 }),
});
const body = await res.json();$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks/' . $task . '/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => 0]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// Switching off does not clear the QUEUE: what waits is picked up once it comes back on.
Api::Automation()->UpdateAutomationTaskStatus(['task' => $task, 'enabled' => 0]);Running a Task Now
Queues a task without waiting for its time.
service-server-terminate: the installation came from 3.x and its automation settings are not confirmed yet. Confirm them first, see Confirming Delete From Server. From 5.0-beta.4.curl -X POST 'https://panel.example.com/api/v1/admin/automation/tasks/invoice-create/run' \
-H "Authorization: Bearer $API_KEY"const res = await fetch(`https://panel.example.com/api/v1/admin/automation/tasks/${task}/run`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.job_id);$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks/' . $task . '/run');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// The call QUEUES the task rather than running it; follow the result by the job id.
$jobId = Api::Automation()->RunAutomationTask(['task' => $task])['data']['job_id'];
$job = Api::Automation()->GetAutomationJob(['queue' => 'cron', 'id' => $jobId])['data'];Confirming Delete From Server
Releases the Delete From Server task on an installation upgraded from 3.x. From 5.0-beta.4.
An installation upgraded from 3.x holds this task until an administrator confirms the automation settings. While on hold it selects no service, and manual runs return terminate_hold. This call records the confirmation, like the confirm button on the Automation page. Check the suspension, cancellation and deletion days first (GET /automation/settings). After the confirmation, cancelled services past their delay are removed from their servers for good. When nothing is on hold the call writes nothing and returns already: true.
service-server-terminate.true: the task is no longer on hold.true when nothing was on hold and nothing was written.api:<admin id> from this call, the administrator id from the panel, v3-to-v5-wizard when the wizard carried the 3.x settings across; null when the installation was never on hold.Y-m-d H:i:s).curl -X POST 'https://panel.example.com/api/v1/admin/automation/tasks/service-server-terminate/confirm' \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://panel.example.com/api/v1/admin/automation/tasks/service-server-terminate/confirm', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.already ? 'nothing was on hold' : 'confirmed');$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks/service-server-terminate/confirm');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// Check the hold first; confirm only after the days in the settings were reviewed.
$hold = Api::Automation()->GetAutomationSettings()['data']['terminate_hold'];
if ($hold['active']) Api::Automation()->ConfirmServerTerminate();Pitfalls
A task can be switched off, or it can have no handler at all. The second is not a choice but a gap in the setup: the task sits in the list, never runs, and the run-now call errors. Read the two fields apart when writing monitoring.
The run endpoint puts the task in the queue, and the scheduled worker does the work. By the time the response arrives the job may not have started, so follow the job id that comes back to see the outcome. With a dead worker the job is never picked up and waits quietly.
The task-jobs endpoint pages forward: it fetches what comes after the id you give. The general job feed goes backward. Code using both in one loop and mixing up the cursor fields either never advances or returns the same page.
Switching a task off stops it leaving new jobs and does not clear what already waits. Switch it back on and those older jobs get picked up too, running at a moment you did not expect. For a task going off for a long while, consider cancelling what waits as well.
In the task list the completed count covers today while the failed count covers the whole period the records are kept. Putting the two side by side to work out a success rate gives a wrong answer. For counts over one window, count the task's jobs yourself with the status filter.
Related Articles
¡Gracias por sus comentarios!
Nuestro equipo de soporte está disponible las 24 horas para ayudarle con lo que no encuentre aquí.