ioLoop Docs

Appearance

Flow Share ​

Flow Share lets ioLoop flows share named runtime values, objects, and functions. In Cloud Flow, it is useful when one backend module needs to make a helper or other runtime value available to another module without duplicating its implementation.

This guide focuses on Flow Share in the Cloud Flow backend runtime, where Background Tasks, Web Hooks, and supported AI Agent modules can use shared values. Flow Share is also available in frontend Page Flow and Form Page Flow, but sharing within a frontend flow is a separate runtime context; it does not automatically provide access to Cloud Flow's backend values.

Flow Share is runtime sharing, not persistent Project storage. Use it for values that can be initialized again when the Cloud Flow runner starts.

When to Use Flow Share ​

Use Flow Share when several backend modules need common behavior or runtime state, such as:

  • Validation or normalization helper functions.
  • Common formatting functions.
  • Reusable Database lookup or integration helper functions.
  • Small configuration or lookup objects prepared at runtime.
  • Callbacks used by multiple backend modules.
  • Temporary caches whose contents can be rebuilt.

For example, a Background Task can make an order-code normalization helper available through Flow Share. Several Web Hooks can then retrieve and call that helper rather than maintaining separate copies.

You do not need Flow Share when a value or function is used only within one Cloud Flow module. Keep module-local logic local unless there is a clear reason to share it.

How Flow Share Works ​

A module sets a value under a name. Another supported module gets that value using the same name.

PartResponsibility
Provider moduleDefines and stores a shared value or helper function.
Flow Share nameIdentifies the value for other modules.
Consumer moduleRetrieves the value and uses it in its own logic.
Cloud Flow runtimeHolds the shared value while the relevant runtime is active.

A typical arrangement is:

text
Background Task: SharedOrderHelpers
  Define normalization helper
  Set Flow Share value: orderHelpers.normalizeCode
                 |
                 v
Web Hook: CreateOrder
  Get Flow Share value: orderHelpers.normalizeCode
  Validate request and call helper
  Continue with authorized order processing

This is a conceptual module arrangement, not a required Cloud Flow block sequence.

Sharing a helper does not automatically execute it. The consumer must retrieve the helper and call it where needed. A helper also does not automatically receive the calling module's request or AI Agent context; provide required inputs explicitly.

Where Flow Share Is Available ​

Flow Share can be used with these supported Cloud Flow module contexts:

ContextTypical Use
Background TaskInitialize shared helpers or runtime values; consume helpers from other modules.
Web HookRetrieve shared helpers while processing requests, or share runtime values for other backend modules.
AI Agent moduleUse shared backend helpers in supported AI Agent workflows.
Cloud Flow Custom CodeSet and retrieve values directly with the ioLoop Server API.

Background Tasks are particularly suitable for common helpers because ioLoop loads them before Web Hooks and AI Agent modules.

Flow Share in Page Flow or Form Page Flow belongs to frontend execution. Do not assume a value set in the browser is visible to Cloud Flow, or that a backend Flow Share value is automatically available to custom frontend JavaScript. Pass data through the appropriate supported frontend-to-backend interface when crossing that boundary.

Setting and Retrieving Shared Values ​

Cloud Flow supports Flow Share blocks and the following documented Server APIs:

APIPurpose
$io.system.setFlowShareData(name, value)Stores a named runtime value, object, or function.
$io.system.getFlowShareData(name)Retrieves the value associated with a name.

The name is a string, and the value can be a supported value, object, or function. The set function does not return a value. The get function returns the shared value, or null if that name does not exist.

Example: Share a Helper Function ​

In a Background Task, use a Custom Code block to define and register a helper:

js
function normalizeOrderCode(value) {
  return String(value ?? '').trim().toUpperCase();
}

$io.system.setFlowShareData(
  'orderHelpers.normalizeCode',
  normalizeOrderCode
);

In a Web Hook or another backend module, retrieve the helper before using it:

js
const normalizeCode = $io.system.getFlowShareData(
  'orderHelpers.normalizeCode'
);

if (typeof normalizeCode !== 'function') {
  throw new Error('Shared order-code helper is unavailable');
}

const normalizedCode = normalizeCode(' ab-123 ');
// normalizedCode is "AB-123".

These examples demonstrate the documented Flow Share API calls. They do not define a Web Hook's request or response handling, which must be configured separately.

A shared object can be stored and retrieved in the same way:

js
$io.system.setFlowShareData('orderHelpers.settings', {
  defaultStatus: 'New',
  displayCurrency: 'USD'
});

Choose names that describe ownership and purpose. For example, orderHelpers.normalizeCode is clearer than helper1 or data. Coordinate names across modules to avoid accidental conflicts.

For exact API descriptions, see $io.system.setFlowShareData and $io.system.getFlowShareData.

Creating a Shared Background Task Module ​

A common implementation pattern is to use a Background Task to provide helpers for other backend modules.

  1. Open Backend → Cloud Flow in the Project Editor.
  2. Create a Background Task with a name that identifies its shared purpose, such as SharedOrderHelpers.
  3. Select the module and choose Edit Flow.
  4. Define the reusable helper or value using supported blocks or Custom Code.
  5. Store it with a meaningful Flow Share name.
  6. Save the module.
  7. Confirm that the module is enabled and loads before any consumer that expects its values during initialization.
  8. Retrieve the helper in the consuming Background Task, Web Hook, or supported AI Agent module.
  9. Start the Cloud Flow test runtime where applicable, exercise the actual consumer, and review the logs.

Background Tasks have no separate trigger or scheduling configuration. Any timers, recurring processing, or other execution behavior are defined by the task's own logic. A shared-helper Background Task does not need to create a timer just to expose functions during runtime initialization.

For module creation and actions, see Managing Cloud Flow. For Background Task execution patterns, see Background Tasks.

Load Order and Initialization ​

Load order matters when one module expects another module to make shared values available first.

ioLoop loads Cloud Flow module types in this order:

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

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

Use Load Order - and Load Order + in the Cloud Flow module list to adjust module ordering. For example, if SharedOrderHelpers exports values consumed by another Background Task, place the provider earlier in the Background Task load order.

Module Loading Is Not the Same as Async Completion ​

Load order determines the sequence in which modules are loaded. It does not guarantee that a delayed operation, timer callback, external request, or other asynchronous initialization inside a provider has completed before a consumer runs.

For helpers needed immediately, initialize them as part of the provider's module initialization logic. If a shared value is prepared asynchronously, design the consumer to check for readiness and handle an unavailable value instead of assuming load order alone guarantees it exists.

A dependency that is initialized late can cause intermittent errors even when the modules are arranged in the correct load order.

Sharing Functions and Passing Context ​

A shared helper can be called from multiple Web Hooks or AI Agent modules, but the data available to one invocation should not be assumed to exist in another.

For a reusable helper:

  • Define the inputs it needs rather than relying on the provider module's local variables.
  • Pass the current request, record identifier, or other relevant information from the consumer.
  • Validate values supplied by external callers or the browser.
  • Perform authorization using trustworthy context appropriate to the current operation.
  • Return a clear value or result for the consumer to handle.

For example, a helper that checks whether an order may be changed should receive the relevant order and caller context from the current Web Hook or AI Agent workflow. Merely placing an authorization-related function in Flow Share does not enforce access control or make untrusted input safe.

For protected operations, see Access Security.

Flow Share, Runtime State, and Persistence ​

Flow Share values exist within the relevant runtime. They are not durable records and must be treated as replaceable runtime state.

InformationRecommended Place
Reusable validation functionFlow Share
Small runtime lookup object that can be rebuiltFlow Share
Temporary cache that can be repopulatedFlow Share, with appropriate fallback logic
Customer or order recordsProject Database
Audit history and transaction stateDurable Database or other appropriate persistent storage
Uploaded or generated filesAppropriate Project file storage
Credentials and service secretsConfigured Connections or supported protected configuration

After a Cloud Flow runner restart or other runtime reinitialization, shared helpers and values need to be established again. Do not assume that Flow Share is a backup, a durable cache, or a mechanism for synchronizing state between separate runtime environments.

Similarly, do not assume a value populated in a test runtime is present in the published runtime. Test and live execution should initialize their required shared values independently.

Avoid Using Shared State for Request-Specific Data ​

Shared runtime values are not a substitute for passing request data to the code that needs it. Avoid storing sensitive or per-user request information in a commonly named value that other invocations could read or overwrite.

For concurrent or repeated backend operations, use request-local values and persistent storage where appropriate. Do not depend on Flow Share alone for transaction consistency, durable counters, distributed locking, or important record updates.

Updating Shared Helpers ​

A helper may be used by several modules. Before changing it:

  1. Identify the Web Hooks, Background Tasks, and AI Agent modules that retrieve it.
  2. Check whether consumers depend on its name, expected inputs, or return values.
  3. Preserve compatibility where possible or update consumers together.
  4. Save changes and test through each important consuming workflow.
  5. Confirm the helper is reinitialized in the intended test and published runtimes when the changes are deployed.

Renaming a Flow Share key does not automatically update consumers. A consumer that still retrieves the old key may receive null.

Testing Flow Share ​

Test shared values through the module that actually consumes them.

TestWhat to Verify
Provider initializationThe shared name is registered before the consumer needs it.
Consumer retrievalgetFlowShareData returns the expected type and value.
Missing helperThe consumer handles null without continuing incorrectly.
Module load orderRequired providers load before dependent modules.
Async initializationConsumers do not assume a delayed value is immediately ready.
Runtime restartShared values are created again when the Cloud Flow runner starts.
Helper changeAll relevant consumers still work after the shared implementation changes.
AuthorizationThe consumer validates the current request and does not rely on globally shared user context.
PublishingShared helpers work in the published runtime, not only during development testing.

Use Start Test, Stop Test, and Logs from the Cloud Flow area as appropriate. When testing a Web Hook consumer, invoke it through the intended test caller and review logs for both the provider and consumer modules.

For details, see Testing and Logs.

Troubleshooting ​

IssueWhat to Check
Get returns nullFlow Share name, provider enabled state, initialization timing, runtime context, and load order.
Retrieved value is not a functionThe provider may have stored a different type or failed to register the expected helper.
Works after restarting but not consistentlyCheck asynchronous initialization and whether the consumer can run before a value is ready.
A helper changed unexpectedlyReview shared names and other modules that may set the same key.
Works in test but not after publishingConfirm that provider and consumer modules were published and initialized in the published runtime.
The helper uses the wrong user or recordPass current invocation context explicitly; do not reuse request-specific shared state.
A cached value disappearsFlow Share does not persist across runtime restarts. Rebuild or retrieve the value from durable storage.

Keep logs useful for debugging, but avoid logging credentials, private user data, or entire sensitive request objects.

Good Practices ​

  • Name shared values by purpose. Prefer names that make the owning module and the intended behavior clear.
  • Use Background Tasks for reusable helpers. They load before Web Hooks and AI Agent modules.
  • Initialize dependencies deliberately. Load order helps, but asynchronous work needs its own readiness handling.
  • Keep helpers focused. Each shared function should have a clear purpose and explicit inputs.
  • Use Flow Share only for runtime values. Store durable information in Database or files.
  • Pass request context explicitly. Keep user-specific and transaction-specific data out of general shared keys.
  • Manage secrets through Connections. Do not use Flow Share as a credentials vault.
  • Test consumers, not only providers. Exercise real Web Hook and AI Agent workflows after shared changes.

Common Mistakes ​

Avoid these patterns:

  • Treating Flow Share as a permanent database or durable cache.
  • Expecting frontend Page Flow and backend Cloud Flow to share the same runtime values automatically.
  • Calling a helper defined in another module directly by name instead of retrieving it through Flow Share.
  • Using a shared value before its provider initializes it.
  • Assuming module load order waits for asynchronous initialization.
  • Keeping per-user identity, request inputs, or important mutable transaction state in common shared keys.
  • Changing a Flow Share name or helper interface without updating consumers.
  • Using shared authorization helpers without validating the current caller or record.
  • Assuming runtime state will survive restarts or automatically move from test to production.

Flow Share works best as a deliberate way to reuse backend runtime behavior. Keep the shared values small, the dependency order clear, and the business data and security checks in the appropriate persistent or trusted Project capabilities.

Technical Reference ​