ioLoop Docs

Appearance

Background Tasks ​

Background Tasks are Cloud Flow modules for server-side functionality that is not exposed as an HTTP Web Hook.

Use a Background Task when a Project needs backend processing that does not require a request/response endpoint, or when several backend modules need shared functions or runtime values.

Background Tasks have no separate trigger or scheduling configuration. Their behavior is defined by the logic inside the module. A Background Task can perform initialization work, implement its own timer for recurring processing, or provide shared helpers through Flow Share. Creating a Background Task does not automatically create a recurring job or schedule.

For request-based backend functionality, see Web Hooks.

When to Use a Background Task ​

Common uses include:

  • Initializing backend helpers or runtime values when a Cloud Flow module loads.
  • Running processing that is initiated or coordinated by the module's own logic.
  • Implementing timer-driven maintenance or data-preparation work.
  • Processing or preparing Database records and files outside a direct Page interaction.
  • Synchronizing data with a configured external service.
  • Providing shared validation, formatting, authorization, or integration helpers to other backend modules.
  • Maintaining small runtime-only values that can be recreated when the backend runtime starts.

Choose the module type based on how the functionality is made available, not simply on whether the processing is short, long, or periodic.

Background Task vs. Web Hook ​

RequirementRecommended Cloud Flow Type
A Page or external caller sends an HTTP request and expects a responseWeb Hook
An external service sends notifications to a Project URLWeb Hook
Backend processing is implemented without an exposed HTTP endpointBackground Task
A module implements its own timer for periodic processingBackground Task
Several backend modules need a shared helper functionBackground Task with Flow Share
A Page needs the result of a protected Database or integration operationUsually a Web Hook

For more guidance, see Cloud Flow Types.

How Background Tasks Run ​

A Background Task is a backend module loaded into the Cloud Flow runtime. The module's own logic determines the work it performs.

For example, its logic may:

  1. Initialize a helper and make it available through Flow Share.
  2. Perform a backend operation during module initialization.
  3. Establish a timer that executes processing periodically.
  4. Maintain runtime-only state used by other backend modules.

These patterns can also be combined. A Background Task might initialize shared helpers and establish a timer within the same module.

No Separate Scheduling Settings ​

Creating a Background Task does not involve specifying a schedule, selecting a trigger type, or configuring a periodic job in the Cloud Flow module settings.

If recurring work is required, implement the timing behavior within the Background Task's own logic. The timing mechanism and the work it initiates are part of the implementation, not a separate ioLoop scheduling feature.

Likewise, Load Order controls when modules are loaded relative to one another. It does not set the execution frequency of a Background Task or act as a scheduler.

Runtime Lifecycle ​

Background Task logic operates within the Cloud Flow runtime. Plan for the possibility that the runtime may stop and restart.

In particular:

  • Runtime-only variables and Flow Share values must be recreated after a restart.
  • A timer established in the runtime should not be treated as a durable scheduling record.
  • Work that must not be performed twice needs appropriate checks against persistent data or another trusted mechanism.
  • Work that must resume after interruption needs durable progress information rather than relying only on an in-memory variable.

For the runtime and available JavaScript libraries, see Node.js Runtime and SDK Libraries.

Creating a Background Task ​

To add a Background Task:

  1. Open Backend → Cloud Flow in the Project Editor.
  2. Choose New Cloud Flow.
  3. Select Background Task.
  4. Enter a meaningful module name.
  5. Save the module.
  6. Select it and choose Edit Flow.
  7. Add the visual blocks or custom code that implement its behavior.
  8. Save the Cloud Flow logic and test it using the Cloud Flow test runtime.

A Background Task's module Settings provides its name. It does not provide Web Hook request settings, a scheduling interface, or a separate trigger configuration.

From the Cloud Flow list, you can also manage its enabled state, load order, and other supported module actions. Background Tasks are internal backend modules and do not require the Web Hook Access (Security) configuration.

For module-management actions, see Managing Cloud Flow.

Pattern 1: Shared Backend Helpers ​

A Background Task can serve as a shared backend module without implementing periodic processing.

Suppose several Web Hooks need the same validation logic. Rather than copying it into every Web Hook:

  1. Create a Background Task, such as SharedOrderHelpers.
  2. Define a focused helper for the common validation.
  3. Expose the helper through Flow Share.
  4. Ensure the Background Task loads before the Web Hooks that need the helper.
  5. Read the shared helper from each consuming Web Hook.
  6. Test the Web Hooks using their actual request paths.

A conceptual structure is:

text
Background Task: SharedOrderHelpers
  Define reusable validation helper
  Publish helper through Flow Share

Web Hook: CreateOrder
  Read helper from Flow Share
  Validate request
  Apply business rules
  Return response

Web Hook: UpdateOrder
  Read the same helper
  Validate request
  Apply business rules
  Return response

This illustrates module responsibilities, not specific Cloud Flow block syntax.

Load Order for Shared Helpers ​

ioLoop loads Cloud Flow modules by type in this order:

  1. Background Tasks
  2. Web Hooks
  3. AI Agent modules

Within each type, lower load-order values load before higher ones.

If one Background Task publishes helpers used by another Background Task, arrange the provider before the consumer using Load Order - and Load Order + in the Cloud Flow list.

Load order establishes initialization order; do not assume it completes an asynchronous setup operation before another module uses the shared value. Make any required readiness or error handling explicit in the implementation.

For the supported Flow Share operations and examples, see Flow Share.

Pattern 2: Timer-Driven Processing ​

A Background Task can implement its own timer when the Project needs processing at intervals.

For example, the Project might periodically look for pending records and process those that qualify.

A conceptual workflow is:

text
Background Task: ProcessPendingRequests
  Initialize task state
  Establish timer in task logic

  When timer executes:
    Check whether work should proceed
    Retrieve pending records
    Process the permitted records
    Record progress and failures

The timer and processing steps must be implemented in the module's blocks or server-side JavaScript. This is not a built-in scheduling configuration.

Preventing Overlapping and Duplicate Work ​

When implementing timer-driven logic, consider these questions:

  • Can a new interval begin before the previous operation finishes?
  • Could initialization or a runtime restart cause the same operation to be attempted again?
  • Could more than one runtime execution path attempt to process the same record?
  • What happens if a Database operation succeeds but a later integration call fails?
  • How does processing resume after an interruption?

Use persistent status fields, suitable record-selection rules, and trusted checks when work must be coordinated across executions. An in-memory flag may help avoid overlap within one running instance, but it is not a substitute for durable coordination when repeated or concurrent processing matters.

If timing must survive runtime interruptions, do not rely on a timer alone to represent work that is due. Store necessary state or progress in the appropriate persistent Project capability.

Working with Database Records and Files ​

Background Tasks can use supported Cloud Flow blocks and the ioLoop Server API for Project data and file operations.

Examples include:

  • Finding records that meet a condition.
  • Updating statuses after backend processing.
  • Preparing summary or derived records.
  • Generating documents and associating them with records.
  • Processing files submitted through application workflows.
  • Synchronizing permitted Project data with an external system.

For Database operations, use the Using Database guide and the Server $io.db API.

For files, see Using Files.

The Server API provides broader Database capabilities than the browser-side Client API. Use its documented methods when implementing server-side operations; do not assume that Client and Server API methods have identical coverage or signatures.

Using Connections ​

Background Tasks can call configured Connections for external service operations.

Examples include syncing records with a CRM, sending a notification through an email service, or processing data with another supported provider.

Use Connections for credentials and provider configuration. Avoid embedding API keys, access tokens, or private credentials directly in the task's code.

External calls can fail or partially complete. Handle timeouts, rejected requests, retries, and duplicate side effects deliberately. For details, see Using Connections.

Flow Share vs. Durable Storage ​

Flow Share provides runtime sharing of helpers and values. It is not permanent storage.

NeedUse
Shared validation or formatting functionFlow Share
Small runtime value that can be recreatedFlow Share
Persistent processing statusDatabase
Application records or audit historyDatabase
Generated documents or uploaded filesProject file storage
Provider credentialsConnections

For example, a Background Task can publish a helper that looks up pending requests. The request records and their processing status should still live in the Database, not in Flow Share.

Security and Access ​

Background Tasks are backend modules and are not publicly callable Web Hooks. ioLoop secures them without requiring the Web Hook Access (Security) settings.

Nevertheless, the logic must enforce the application's requirements whenever it performs protected work or processes data originating from users or external services.

  • Validate data before writing records or calling external services.
  • Apply authorization and business rules appropriate to the operation.
  • Avoid exposing protected information through shared results or logs.
  • Store credentials in Connections or the appropriate protected configuration.
  • Give shared helper functions clear inputs; do not assume a helper automatically inherits another module's request or user context.

For security considerations in request-facing modules, see Access and Security.

Testing Background Tasks ​

Use Start Test from the Cloud Flow area to run the development test runtime, and Logs to inspect backend activity. Use Stop Test when the test session is complete.

Test Background Tasks according to what their own logic does. A shared-helper module, a task that runs during initialization, and a timer-driven task have different outcomes to verify.

TestWhat to Verify
InitializationThe module establishes the expected behavior and shared values.
Timer-driven processingWork runs under the intended conditions and handles repeated execution.
Shared helpersDependent modules can read and use exported helpers.
Empty dataNo matching records is handled safely.
Database failureErrors do not leave processing silently incomplete.
Integration failureRetries and error handling avoid unintended duplicate side effects.
Runtime restartNeeded runtime values can be recreated and durable work is not lost.
LoggingMessages are sufficient to diagnose failures without revealing secrets.
Disabled moduleRequired dependent workflows do not assume a disabled module is available.

When testing a Page that interacts with Cloud Flow, built-in Database operations during Preview use the Project's development database. External Connections may still reach real provider environments depending on their configuration. Verify the environment before testing workflows with side effects.

For broader guidance, see Testing and Logs.

Troubleshooting ​

IssueWhat to Check
Task does not perform expected workEnabled state, saved logic, whether the test runtime is running, and the task's own execution conditions.
Timer-driven work does not repeatTimer initialization, runtime lifecycle, errors in callbacks, and whether the task is still running.
Shared helper is missingFlow Share name, module enabled state, load order, and helper initialization.
Repeated records are processedDuplicate-prevention checks, persistent status, and concurrency handling.
Processing stops after an errorError handling, logging, and whether the module continues after failure.
Data differs from expectationsDevelopment versus production environment, query inputs, and actual records.
Integration call failsConnection configuration, credentials, provider response, and network or service failures.
Changes are not liveWhether the module was saved and the Project was subsequently published.

Good Practices ​

  • Make the purpose clear. Name each Background Task according to the backend responsibility it performs.
  • Keep scheduling inside the logic. If periodic work is needed, implement it in the task; there is no separate trigger or scheduling configuration.
  • Use Flow Share for reusable helpers. Avoid copying shared backend logic into multiple modules.
  • Arrange load order intentionally. Shared helper providers must initialize before consumers need them.
  • Treat restarts and repeated execution as normal design considerations. Make important work recoverable and avoid duplicate side effects.
  • Persist durable data. Use Database or files for records and progress that must survive runtime restarts.
  • Protect credentials and data. Use Connections and trusted validation.
  • Log meaningful outcomes. Capture enough diagnostic information without recording secrets.
  • Test the intended behavior. Exercise shared helpers, initialization, and timer-driven processing through suitable test paths.

Common Mistakes ​

Avoid these patterns:

  • Assuming a Background Task has a separate scheduler or trigger setting.
  • Assuming that creating a Background Task automatically starts periodic processing.
  • Using a Background Task when a Page or external system needs an HTTP request/response endpoint.
  • Confusing module load order with execution frequency.
  • Assuming runtime-only values or timers persist across a restart.
  • Using Flow Share for permanent application data.
  • Exporting a helper without checking that consumers can retrieve it.
  • Ignoring overlapping executions, retries, or duplicate operations.
  • Performing protected operations without validating the relevant inputs or authorization.
  • Logging credentials or sensitive record contents.
  • Testing only with ideal data and no failure conditions.

Background Tasks are most effective when their own logic clearly defines their work, dependencies, and error handling—whether they perform processing, implement timers, or supply shared backend functionality.

Technical Reference ​