Reset global variables with 'resetVariable' if AutoConfig filters fail

Gunbot's AutoConfig feature allows for dynamic state management using global variables, typically modified by the setVariable action when job filters pass. However, there's often a need to alter these variables or revert them to a default state if the primary conditions of a job are not met. This is where the resetVariable action object comes into play, providing a mechanism for conditional state changes when filters fail.

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.

setVariable vs. resetVariable

In a typical AutoConfig job that processes pairs:

• setVariable: This action block is executed if the job's filters (and filters2, etc.) are successfully passed by at least one pair. The global variables defined here are set or updated.
• resetVariable: This action block is executed if the job runs but no pairs pass the defined filters. It allows you to define a different set of global variable changes for this "failure" scenario.

For jobs that don't iterate pairs but might use a global filter (e.g., a custom filter checking this.variables), setVariable would apply on true, and resetVariable on false.

This dual mechanism allows a single job to manage a global variable's state based on whether its primary conditions are met or not.

Configuration Example

Consider an AutoConfig job that tries to detect a "strong buy signal" in the market. If detected, it sets a global variable strongBuyActive to true. If not detected during its run, it should ensure this flag is false.

{
  "strongSignalDetector": {
    "enabled": true,
    "type": "manageOverrides", // Type can vary; logic depends on filters, using state data here
    "schedule": "*/5 * * * *",
    "pairs": { 
      "exchange": "binance",
      "include": "USDT-BTC" // Used as index
    },
    "filters": {
      "isStrongBuyConditionMet": { // Complex filter to detect strong buy
        "filterType": "custom",
        "script": "/* ... some logic returning true if strong buy ... */" // Example
      }
    },
    "setVariable": { // Executed if 'isStrongBuyConditionMet' is true for USDT-BTC
      "strongBuyActive": true,
      "lastStrongBuySignalTime": " new Date().toISOString() "
    },
    "resetVariable": { // User setting: Executed if 'isStrongBuyConditionMet' is false for USDT-BTC
      "strongBuyActive": false
      // We might not want to clear 'lastStrongBuySignalTime' here,
      // or set it to null, depending on desired logic.
    }
  }
}

In the strongSignalDetector job:

• If the isStrongBuyConditionMet filter passes for BTC-USDT:
  • The setVariable block executes, setting strongBuyActive to true and updating lastStrongBuySignalTime.
• If the isStrongBuyConditionMet filter fails for BTC-USDT (meaning no pair passed the filters):
  • The resetVariable block executes, setting strongBuyActive to false.

This ensures the strongBuyActive flag accurately reflects the outcome of the latest check.

Dynamic Values in resetVariable

Like setVariable, values in resetVariable can be dynamic JavaScript expressions if the string value begins with a leading space.

"resetVariable": {
  "consecutiveFails": " (this.variables.consecutiveFails || 0) + 1 ",
  "lastFailReason": " 'Signal not strong enough at ' + new Date().toLocaleTimeString() "
}

• " (this.variables.consecutiveFails || 0) + 1 ": Increments a counter specific to filter failures.
• " 'Signal not strong enough at ' + new Date().toLocaleTimeString() ": Sets a descriptive string with a timestamp.

Use Cases for resetVariable

1. Toggling Flags: The most common use is to set a boolean variable to true with setVariable when a condition is met, and to false with resetVariable when it's not.
2. Default States: Ensure variables revert to a known default or "inactive" state if the activating conditions are no longer present.
3. Clearing Transitory Data: If setVariable stores temporary data (e.g., activeOpportunityPair: "USDT-BTC"), resetVariable could clear it (activeOpportunityPair: null or "") when the opportunity is no longer valid.
4. Error or Failure Counters: Increment a specific counter in resetVariable if a job's primary purpose (finding suitable pairs/conditions) fails.
5. Simplified State Management: Keeps the logic for both "on" and "off" states of a global variable within a single, cohesive AutoConfig job.

Important Considerations

• Trigger Condition: resetVariable is tied to the failure of the job's main filter evaluation. If a job has no filters, setVariable would always execute, and resetVariable might not, unless the job type has specific implicit conditions.
• No Pairs vs. Filter Failure: For jobs that iterate pairs, "no pairs passing filters" is the trigger. This means if pairs.include results in an empty list to begin with, the filters technically don't "fail" for any specific pair; the job just has no candidates. The exact behavior of resetVariable in such an edge case (no pairs to even test filters against) might need verification for specific Gunbot versions, but it's generally intended for when pairs are evaluated but don't pass.
• Order of Operations: setVariable and resetVariable are mutually exclusive for a single job run. Only one of them will execute based on the filter outcomes.
• Clarity: While powerful, ensure the logic remains clear. If the conditions for setting and resetting a variable become very complex and distinct, sometimes two separate jobs (one for setting, one for resetting, with inverted filter logic) might be easier to manage and debug.

The resetVariable action provides a convenient and often cleaner way to manage the "off" or "default" states of global AutoConfig variables, ensuring that your system's state accurately reflects the latest evaluation of market conditions or other criteria defined in your jobs.