How to make an AutoConfig job run once when Gunbot starts?

Gunbot's AutoConfig jobs usually run on a cron schedule. If you want a job to run immediately when Gunbot starts (in addition to its schedule, or only on startup), use the onStart parameter in the job configuration.

Use the AutoConfig wizard

Nearly every option that follows can be set without editing files by hand.
Click the ⋮ (three-dots) menu ➜ AutoConfig, step through the wizard, and press Save; it will write a correct autoconfig.json for you.

The onStart Parameter Explained

The onStart parameter is a boolean (true or false) you can include in any AutoConfig job definition. It triggers a one-time execution of the job as soon as Gunbot finishes startup and loads AutoConfig jobs.

• "onStart": true: The job runs once immediately after Gunbot starts. If the job also has a schedule, it will then continue on that schedule.
• "onStart": false (or omitted): The job only runs on its schedule, not at startup.

How to Configure onStart

Place onStart at the top level of the job configuration in autoconfig.json.

Here is an example:

{
  "initialPairScan": {
    "enabled": true,
    "type": "addPairs",
    "onStart": true, // User setting: This job will run when Gunbot starts
    "schedule": "0 0 * * *", // Also runs daily at midnight
    "pairs": {
      "exchange": "kraken",
      "include": "-EUR"
    },
    "filters": {
      "minDailyVolume": {
        "filterType": "minVolume24h",
        "minVolume": 50000
      }
    },
    "strategy": "spotgriddynamic"
  },
  "regularOverridesUpdate": {
    "enabled": true,
    "type": "manageOverrides",
    "onStart": false, // This job will NOT run on startup, only on schedule
    "schedule": "*/15 * * * *", // Runs every 15 minutes
    "pairs": {
      "exchange": "kraken",
      "include": "-EUR"
    },
    // ... other settings
  }
}

In this setup:

• initialPairScan: Because "onStart": true, this job will execute as soon as Gunbot is ready. It will perform an initial scan for EUR pairs on Kraken meeting the volume criteria. After this initial run, it will also run daily at midnight as per its schedule.
• regularOverridesUpdate: With "onStart": false, this job will not run at startup. Its first execution will be at the next 15-minute interval according to its schedule.

Use Cases for onStart

The onStart functionality is useful in several situations:

1. Initial state setup: Use setVariable or setPairVariable jobs with onStart to establish baseline values at startup.
2. Immediate pair scanning: For addPairs, use onStart to populate pairs immediately after restart rather than waiting for the first scheduled run.
3. Applying default configurations: A manageOverrides job with onStart: true can apply baseline overrides as soon as Gunbot starts.
4. Data collection priming: A collectData job with onStart: true can fetch initial ticker data to seed other jobs.
5. "Run-once" jobs: For a one-off task, set onStart: true and use a very infrequent schedule (for example, 0 0 1 1 * for January 1st at midnight if that date has passed). If it must never run again, manage the enabled flag or use manual execution.

onStart vs. schedule

Remember that onStart triggers an additional run if a schedule is also active.

• To run only on startup and never again automatically: Set onStart: true and use a schedule that will not trigger frequently or is for a past time (for example, 0 0 1 1 0 for a specific past Sunday). Be cautious, as an old cron might re-trigger in a future year if it is not specific enough. A more common pattern is "run at startup and on a normal schedule" by using onStart: true with your regular cron.
• To run on startup and on a regular schedule: Set onStart: true and define the cron expression in schedule.

The onStart parameter ensures AutoConfig tasks execute promptly when Gunbot initializes, helping establish a consistent state and timely initial actions. Consider which jobs benefit from immediate execution and use onStart accordingly.