Cron Settings

7 views Markdown

The four endpoints for the automation's configuration, its main switch and its cron secret.

Overview

These four endpoints configure the automation itself: how long records are kept, which hours heavy work runs in, whether the automation is on at all, and the secret guarding the cron address.

The main switch is an emergency stop. With it off no task runs: no invoice is issued, no service renewed, no notice sent. Who switched it off and when stays recorded in the settings.

The secret is the cron address's password and cannot be read; the settings say only whether one is set. Renewing hands it back once and makes the old address invalid.

Reference

Reading the Settings

get/api/v1/admin/automation/settings
Automation/GetAutomationSettings admin

Returns the automation's configuration and the state of its main switch.

Response fields data — 8
cron_enabledboolWhether the automation's main switch is on.
disabled_atstring | nullWhen it was switched off.
disabled_bystring | nullWho switched it off.
time_windowobjectThe window heavy work runs in: its start and its end.
retentionobjectHow long records are kept: separate day counts for completed, cancelled and failed jobs.
secret_setboolWhether the cron secret is set. The secret itself never comes back.
restoreobjectThe restore suspicion: when it arose and how many hours of silence it rests on.
tasksobjectThe task definitions as they stand.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/automation/settings' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/automation/settings', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/settings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The secret NEVER comes back: only a mark saying whether one is set.
$s = Api::Automation()->GetAutomationSettings()['data'];
$ready = $s['cron_enabled'] && $s['secret_set'];

Writing the Settings

put/api/v1/admin/automation/settings
Automation/UpdateAutomationSettings admin

Writes how long records are kept and the window work runs in.

Body 4
completed_daysintHow many days completed jobs are kept. One day at the least.
cancelled_daysintHow many days cancelled jobs are kept.
failed_daysintHow many days failed jobs are kept.
time_windowobjectThe window heavy work runs in: a start and an end time. It has to span at least an hour past the start of the day.
Response fields data — 8
dataobjectThe settings as they now stand. Same shape as the read endpoint.
Errors 3
invalid_window422The window is too short.
config_write_failed422The settings file could not be written.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/automation/settings' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"completed_days":30,"failed_days":30,"time_window":{"start":"00:00","end":"06:00"}}'
const res = await fetch('https://panel.example.com/api/v1/admin/automation/settings', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    completed_days: 30,
    cancelled_days: 7,
    failed_days: 30,
    time_window: { start: '00:00', end: '06:00' },
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/settings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'completed_days' => 30,
        'failed_days'    => 30,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// SHORTENING the retention does not clear the past at once; the clean-up is its own call.
Api::Automation()->UpdateAutomationSettings(['completed_days' => 7]);

Stopping the Automation

put/api/v1/admin/automation/cron-enabled
Automation/ToggleAutomationCron admin stops everything

Switches the automation's main switch on or off.

Body 1
enabledintreqSwitches the automation on, or stops it outright.
Response fields data — 2
cron_enabledboolHow the switch now stands.
changedboolWhether anything moved. False means it already stood that way.
Errors 3
enabled_required422Neither on nor off was given.
blocked_by_gate422A hook refused the switch-off.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/automation/cron-enabled' \
  -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/cron-enabled', {
  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/cron-enabled');
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 stops INVOICING, RENEWALS and notices alike; keep it for maintenance.
Api::Automation()->ToggleAutomationCron(['enabled' => 0]);
// ... maintenance ...
Api::Automation()->ToggleAutomationCron(['enabled' => 1]);

Renewing the Secret

post/api/v1/admin/automation/cron-secret/regenerate
Automation/RegenerateAutomationCronSecret admin breaks the old address

Builds a new secret for the cron address and returns it.

Body —
——No body is needed; send an empty one. This endpoint takes no parameters, so the new secret cannot be chosen.
Response fields data — 1
secretstringThe new secret. It cannot be read again, so write it into the scheduled call on the server at once.
Errors 2
config_write_failed422The settings file could not be written.
insufficient_scope403The key lacks the required scope.
Request 
curl -X POST 'https://panel.example.com/api/v1/admin/automation/cron-secret/regenerate' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.example.com/api/v1/admin/automation/cron-secret/regenerate', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
// data.secret yalnizca burada gorunur
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/cron-secret/regenerate');
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);
// Renewing makes the OLD cron address invalid: nothing runs until the scheduled call on
// the server is updated.
$secret = Api::Automation()->RegenerateAutomationCronSecret()['data']['secret'];

Pitfalls

The main switch stops everything

Switching the automation off stops not one task but all of them: no invoice, no renewal, no suspension, no notice. While it stays off the jobs pile up in the queue, and they all begin running at once when it comes back. When switching off for maintenance, keep the window short.

The new secret shows once

The renew call returns the secret in that response alone, and the settings endpoint never gives it again. Miss it and you cannot update the scheduled call on the server, leaving another renewal as the only way out. A client that logs its responses logs the secret too.

Renewing breaks the old address

The secret is part of the cron address. The moment it changes, the scheduled call on the server keeps using the old one and gets refused, so the automation stops until the address is updated. The outage is quiet: nothing shows as an error, the jobs merely begin piling up.

The window holds heavy work back

The window keeps heavy tasks to certain hours alone. A narrow one can leave the night's work unfinished by morning and the queue a little longer each day. When narrowing it, watch the longest wait on the dashboard; a growing figure says the window is too small.

Shortening the retention does not clear the past

Lowering the retention days changes only what the next clean-up measures by; the older rows stay until it runs. To free space, run the clean-up rather than changing the setting and waiting, and look at the preview first to see what would go.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket

We use cookies to keep you signed in, remember your language and currency, and improve the site. Cookie Policy