Skip to main content

Set or update global AutoConfig variables as a job action

· 7 min read

Global variables in Gunbot's AutoConfig allow for stateful automation, where jobs can react to conditions set by other jobs or persist information across runs. The primary way to create or modify these global variables is by using the setVariable object as an action within an AutoConfig job definition. This action is performed if the job's filters (if any) are passed.

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 setVariable Action Object​

The setVariable object is a powerful tool within an AutoConfig job that allows you to directly manipulate the global state accessible by all AutoConfig components. When a job runs and its filter conditions (if any are defined) are met by at least one pair (for pair-processing jobs) or globally (for jobs not iterating pairs), the setVariable block is executed.

Inside the setVariable object, you define key-value pairs:

  • Key: The name of the global variable you wish to create or modify (e.g., marketCondition, lastEthPrice).
  • Value: The new value for this variable. This can be a string, number, or boolean.

These global variables are persisted in the autoconfig-variables.json file in your Gunbot user directory, making them available across Gunbot restarts and to other AutoConfig jobs and custom filters (via this.variables).

Configuration Example​

Here's how setVariable can be used in an AutoConfig job. This example job type is manageOverrides but setVariable can be part of many job types.

{
  "marketAnalystJob": {
    "enabled": true,
    "type": "manageOverrides2", // Changed to manageOverrides2 as minSlopePctInterval uses ticker data
    "schedule": "*/30 * * * *", // Runs every 30 minutes
    "pairs": { // This job might analyze a specific index pair like USDT-BTC
      "exchange": "binance",
      "include": "USDT-BTC"
    },
    "filters": {
      "btcIsTrendingUp": { // A filter to determine if BTC is in an uptrend
        "filterType": "minSlopePctInterval", // Example filter
        "minSlope": 0.5,
        "lastSnapshots": 12 // Based on 12 snapshots (e.g., 1 hour if job runs every 5 mins & snapshots are frequent)
      }
    },
    "setVariable": { // User setting: Action to set global variables
      "overallMarketSentiment": "bullish",
      "btcTrendStrength": 7, // Assign a numerical strength
      "lastSentimentUpdate": " new Date().toLocaleString() " // Dynamic value
    }
    // No 'overrides' needed if this job only sets variables
  }
}

In the marketAnalystJob:

  • If the USDT-BTC pair on binance passes the btcIsTrendingUp filter (meaning its price slope is positive).
  • The setVariable action will:
    • Set (or update) the global variable overallMarketSentiment to the string "bullish".
    • Set (or update) btcTrendStrength to the number 7.
    • Set (or update) lastSentimentUpdate to a string representing the current date and time. The leading space in " new Date().toLocaleString() " causes it to be evaluated as JavaScript.

Other AutoConfig jobs can then use filters like variableExact or custom scripts reading this.variables.overallMarketSentiment to react to this state.

Dynamic Values in setVariable​

Just like with the overrides object, the values provided in setVariable can be dynamic JavaScript expressions if the string value starts with a leading space. This allows for powerful state manipulations, such as incrementing counters or calculating values based on existing variables or context.

Example: Incrementing a Counter

"setVariable": {
  "pairsAddedToday": " (this.variables.pairsAddedToday || 0) + 1 "
}
  • This retrieves the current value of pairsAddedToday (or defaults to 0 if it doesn't exist), increments it by 1, and saves the new value.
  • Note: The availability of context like this.pair within the evaluated string in setVariable depends on the job type and when setVariable is processed. this.variables is generally always available. For job types like addPairs or manageOverrides, if setVariable is processed after iterating through pairs that passed filters, context related to the last processed pair might be available, but this can be nuanced. Simpler dynamic values based on this.variables or date/time are more common.

resetVariable: Conditional Setting When Filters Fail​

Closely related to setVariable is resetVariable. This block is typically executed if the AutoConfig job runs but no pairs pass its main filters (or if the job type is one that explicitly uses resetVariable logic, like some filter-less utility jobs).

{
  "marketAnalystJob": {
    // ... (as above) ...
    "filters": { /* ... */ },
    "setVariable": {
      "overallMarketSentiment": "bullish",
      "activeSignal": true
    },
    "resetVariable": { // Executed if 'btcIsTrendingUp' filter FAILS for USDT-BTC
      "overallMarketSentiment": "neutral",
      "activeSignal": false
    }
  }
}

If btcIsTrendingUp fails, overallMarketSentiment becomes "neutral" and activeSignal becomes false. This is useful for resetting flags or states when a condition is no longer met.

Use Cases​

  1. Global State Management: Maintain overall system states like "trading_active", "maintenance_mode", "market_condition".
  2. Counters and Tallies: Track how many times certain events occur (e.g., number of pairs added, number of errors encountered by a specific logic).
  3. Timestamping: Record when certain global conditions were last met or updated.
  4. Inter-Job Signaling: One job detects a condition and sets a variable; other jobs read this variable to alter their behavior.
  5. Storing Calculated Values: A complex analysis job calculates a score or indicator and stores it in a global variable for simpler access by other filters or jobs.

Key Considerations​

  • Execution Point: setVariable actions are typically performed after the primary action of a job (like adding pairs or applying overrides) for the pairs that passed filters. If no pairs pass, resetVariable might be triggered instead.
  • Data Types: You can set string, number, or boolean values. Ensure consistency if other parts of your system expect a certain type.
  • Initialization: If a variable might be used in a dynamic expression within setVariable itself (like the counter example), ensure it's initialized or provide a default (e.g., (this.variables.myCounter || 0)).
  • File I/O: Each time setVariable or resetVariable modifies variables, Gunbot writes to autoconfig-variables.json. Frequent writes by many jobs could theoretically lead to increased disk I/O, but this is rarely an issue in practice.

The setVariable (and resetVariable) actions are fundamental to creating advanced, stateful automations with AutoConfig, transforming it from a simple filter-and-act tool into a more dynamic system that can learn and adapt based on its own operations and your defined logic.