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

Gunbot's AutoConfig jobs are typically executed based on a cron schedule you define. However, there are scenarios where you might want a particular job to run immediately once Gunbot starts, in addition to its regular schedule, or perhaps only on startup. This is achievable using the onStart parameter within the job's 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 value (true or false) that you can include in the definition of any AutoConfig job. Its purpose is to trigger a one-time execution of the job as soon as Gunbot has finished its startup procedures and loaded the AutoConfig jobs.

• "onStart": true: The job will execute once immediately after Gunbot starts. If the job also has a schedule defined, it will subsequently run according to that schedule as well.
• "onStart": false (or if the parameter is omitted): The job will only run based on its schedule. It will not execute automatically at startup.

How to Configure onStart

You place the onStart parameter at the top level of the specific job's configuration within your autoconfig.json file.

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 valuable in several situations:

1. Initial State Setup: If you have AutoConfig jobs that set global variables (setVariable) or per-pair variables (setPairVariable) to establish a baseline state, running these jobs onStart ensures your system begins with the correct variable values.
2. Immediate Pair Scanning: For addPairs jobs, using onStart can populate your trading pairs immediately after a restart, rather than waiting for the first scheduled run. This is useful if Gunbot was down for a while and you want to catch up on potential new pairs quickly.
3. Applying Default Configurations: A manageOverrides job with onStart: true can ensure that all your active pairs have a specific set of baseline overrides applied as soon as Gunbot starts.
4. Data Collection Priming: If a collectData job is set with onStart: true, it can fetch an initial set of ticker data immediately, which might be useful for other jobs or for ensuring data continuity after a restart.
5. "Run-Once" Jobs: If you need a job to perform a task only a single time (e.g., a one-off configuration cleanup or a specific variable initialization that shouldn't repeat), you can set onStart: true and give it a schedule that is very infrequent or effectively in the past (e.g., 0 0 1 1 * for January 1st at midnight, if that date has passed for the year, or a cron for a specific past date). However, ensure the enabled flag is managed if it's truly a one-time task you don't want running even on the infrequent schedule. More robustly, for a true run-once-ever task, manual execution or a script might be better, but onStart can serve for "run-once-per-startup."

onStart vs. schedule

It's important to 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 (e.g., 0 0 1 1 0 for a specific past Sunday). Be cautious with this approach, as a very old cron might eventually re-trigger in a future year if not specific enough. A more common pattern for "run at startup then on a normal schedule" is simply using onStart: true with your regular cron.
• To run on startup and on a regular schedule: Set onStart: true and define your desired cron expression in schedule.

The onStart parameter provides a convenient way to ensure specific AutoConfig tasks are executed promptly when Gunbot initializes. This helps in establishing a consistent operational state, performing timely initial actions, and ensuring your automated strategies are primed and ready without delay. When designing your AutoConfig jobs, consider which tasks would benefit from an immediate execution at startup and utilize the onStart parameter accordingly.