Async You Later

Async You Later is a fun and flexible utility for running long or complex operations asynchronously in OutSystems using Fire-and-Forget patterns.

It is ideal for scenarios such as:

• Large PDF generation

• Data export/import tasks

• Long-running integrations

• Any process that shouldn’t block the user interface

With Async You Later, you can launch a process directly from the screen, immediately return control to the user, and then listen for results (or feedback) in a clean, modular way.

Why Async You Later?

• Non‑blocking UX: Launch from a screen and return control immediately to the user.

• Composable: Clean extension point via a single switch action (AsyncYouLaterSwitch) keyed by a Type parameter.

• Modular customizations: Keep scenario‑specific logic separate in your own customization modules.

• Simple result handling: Poll or subscribe for status/feedback without coupling UI to background logic.

• No REST APIs are used between modules: The fire and Foget is done using Service Actions only for better security and to save AOs

Getting Started

Async You Later is split into multiple modules, each with a specific responsibility:

• Async You Later (Core)
  The foundation. Contains the logic to trigger async processes in a Fire-and-Forget manner.
  You should never put business logic here. Instead, it delegates work to the customization modules.
  Forge: https://www.outsystems.com/forge/component-overview/21911/async-you-later-o11

• Async You Later – Customizations (Template)
  A clonable template where you define your own async processes. Extend the CustomParameters structure, configure process types, and implement your long-running logic inside the provided AsyncYouLaterSwitch service action.
  You can create multiple clones of this template for different business areas or use cases.
  Forge: https://www.outsystems.com/forge/component-overview/22068/async-you-later-customizations-o11

• PDF You Later – Customizations (Template)
  A specialized customization template with accelerators for PDF generation. It demonstrates how to build async PDF workflows that generate documents and return results or error events.
  Forge: https://www.outsystems.com/forge/component-overview/22069/pdf-you-later-customizations-o11

Important

When setting up Async You Later, make sure you download both the Core module and at least one Customization Template.

• The Core alone is not enough to run async jobs—it needs a Customization module to define the actual work.

• You can have multiple Customization modules (clones) side by side, each handling different async scenarios.

Step by Step Setup

1. Download the Core App
   Install Async You Later (Core) from Forge. This provides the engine for fire‑and‑forget async execution.

2. Download the right Template for your use case

   • Use Async You Later – Customizations for generic async tasks.

   • Use PDF You Later – Customizations if your use case involves generating PDFs.

3. Clone the Template Module

   • Create a clone of the customization template for your project or feature area.

   • Each clone is independent and contains its own logic.

4. Define Types

   • In the customization module, open the AsyncProcessType entity.

   • Add a record for each async process you want to support.

   • For PDF scenarios, make sure to also set the PDF path.

5. Customize Logic

   • In the generic template, implement your business logic inside the AsyncYouLaterSwitch service action, branching per Type.

   • In the PDF template, the default logic already generates PDFs. You only need to customize if you want to extend or override special cases.

6. Extend Structures

   • Extend the CustomParameters structure to pass additional attributes specific to your process needs.

Architecture

• Consumer modules should always trigger processes from the Customization Module (e.g., call Services.AsyncYouLater).

• The Customization Module then calls the Core Module (AsyncYouLater_CS → CS_AsyncUtils.AsyncYouLater_Start).

• The Core Module immediately invokes the Customization’s AsyncYouLaterSwitch service action as a fire‑and‑forget call.

• Long‑running work executes in the Customization Module.

For examples, check the Demo apps included.

Handling Processes

The Core module ships with UI helpers under the CW module:

• AsyncYouLater_Checker

  • Listens for the completion of a single process.

  • Inputs: the process identifier, a boolean flag to start/stop listening, and a periodicity (seconds).

  • It periodically calls a server action to check if the process is complete. Use carefully to avoid over‑polling.

• AsyncYouLater_FloatingQueue

  • Listens for multiple processes and displays progress in a floating widget at the bottom‑right of the screen.

  • When a process completes, it triggers an event you can customize.

  • Requires client actions to add processes to the queue.

  • Supports navigation across pages while keeping track of running processes.

Advanced Scenarios

In the AsyncProcessType static entity of your customization module, you can configure advanced attributes:

• isUserBased

  • If true, each user can trigger their own instance of the process.

  • If false, processes are shared and restart every time a new user triggers them.

  • Cannot be started as Anonymous when true.

• CanHaveMultipleRuns

  • If true, multiple instances can run with the same parameters (new GUID/unique key required).

  • If false, triggering again will restart the same process rather than create a new instance.

• ErrorRetries

  • Defines how many times the process should retry before failing and invoking the error callback.

Process Uniqueness

Every process is stored in the database. Whether it creates a new instance or reuses/restarts depends on:

• Process type settings (isUserBased, CanHaveMultipleRuns, ErrorRetries).

• ExtraInfo and CustomParameters passed at start. Different values produce unique processes.

Example

• If you start a process with a filter parameter in CustomParameters, changing the filter will start a new process.

• For PDF generation, you can also include a FriendlyLabel (e.g., a unique filename). This ensures that listeners wait for the correct PDF completion event.

Summary

• Install Core + a Template (generic or PDF).

• Clone and customize the template to define types and logic.

• Consumers call the customization’s server action.

• Core handles fire‑and‑forget, triggering the customization’s service action.

• Use UI blocks (Checker / FloatingQueue) to handle process completion.

• Configure advanced attributes for retries, user‑scoping, and uniqueness.

For working examples, explore the Demo apps provided. support (e.g., GeneratePDF, ExportOrders, SyncPartner).

• For PDF template: also set the PDF Path/storage configuration required by your PDF flow.

5. Customize the Switch (generic template)

   • In Service Actions → AsyncYouLaterSwitch, add a branch per Type and implement the work for that Type (call integrations, build files, etc.).

   • For PDF template: this is prewired to generate a PDF by default; customize only if you need special behavior.

6. Extend the Structure

   • Add fields to CustomParameters if your scenarios need extra inputs (IDs, filters, formats, locales, etc.).

Architecture

• Consumers always trigger from your Customization module.
  UI/screens call your Server Action entry point (e.g., Services.AsyncYouLater).

• The Customization module calls the Core (server action) to start the job, passing ProcessInfo + CustomParameters and which Service Action should run.

• The Core immediately fires a Service Action (fire‑and‑forget) back into your Customization module, where the long‑running work executes.

• No REST APIs are used between modules—Service Actions only for better security and to save AOs.

Check the Demo apps (Async You Later — Demo, PDF You Later — Demo) for end‑to‑end examples of wiring and UI patterns.

Handling the Process (Client Widgets)

Inside the Core’s CW module you’ll find two UI blocks:

1) AsyncYouLater_Checker

• Use this block to listen for completion of a single process.

• Inputs: the process reference to monitor, a boolean to start/stop listening, and the poll interval (seconds).

• The block polls by triggering a server action every N seconds to verify completion. Use a sensible interval to avoid load.

2) AsyncYouLater_FloatingQueue

• Monitors multiple processes and shows a floating indicator at the bottom‑right of the screen.

• On completion of each process, it fires an event you can handle to perform custom actions (e.g., show toast, auto‑download).

• Requires using client actions to enqueue the processes you want to track. The queue survives page navigation, so users can browse while progress is tracked.

Advanced Scenarios (Process Type Options)

In your customization module’s AsyncProcessType static entity, you can control behavior with extra attributes:

• isUserBased
  When true, each user has their own instance of a given Type (per user isolation). The same Type triggered by different users does not reuse metadata.
  When false, any user triggering the same Type will reuse the same process metadata, and the sync restarts when retriggered.
  Note: When isUserBased = true, the process cannot start as Anonymous.

• CanHaveMultipleRuns
  When true, multiple concurrent or sequential runs of the same Type (and even same parameters) are allowed. Often combined with isUserBased = true.
  When false, retriggering will restart the existing process instead of creating another instance.
  If using multiple runs, you must provide a unique key / GUID per instance to distinguish them.

• ErrorRetries
  Number of automatic retry attempts before the process is marked as error and error callbacks fire.

Process Uniqueness & Parameters

Each process instance is persisted in the database. Whether a new process is created, an existing one is reused, or an in‑flight one is restarted depends on:

• The Type configuration (isUserBased, CanHaveMultipleRuns).

• The extra parameters you pass when starting, such as ExtraInfo and CustomParameters.

You can access these values later inside the long‑running Service Action to tailor behavior (e.g., filter queries, change formats).
Changing any of these inputs typically changes the uniqueness key and results in a new process instance.

PDF specifics

• Provide a descriptive FriendlyLabel (ideally the target file name) and keep it unique per document. This makes it easy to listen for and disambiguate the correct PDF completion event.

For deeper examples, refer to the Demo apps bundled with the solution.

Async You Later

Async You Later is a fun and flexible utility for running long or complex operations asynchronously in OutSystems using Fire and Forget patterns, ideal for scenarios like large PDF generation, export tasks, or any process that shouldn't block the UI.

It allows you to launch a process from the screen, return control immediately to the user, and then continue listening for a result (or feedback) in a clean, modular way.

Getting Started

To get started:

1. Clone the AsyncYouLater_Customizations module
   This template helps you organize custom logic and actions modularly.

   ✅ This allows you to have multiple customization modules if needed, for different use cases.

2. Update the module reference
   Open the AsyncYouLater_Start action and update the module name reference to match your cloned module.

3. Update the service action name (if changed)
   If you've renamed the service action AsyncYouLaterSwitch, be sure to update that reference as well inside AsyncYouLater_Start.
   

4. Customize parameters
   In the Structures folder, you'll find the CustomParameters structure. Feel free to extend it with any parameters needed for your specific async flows.

5. Implement your logic in AsyncYouLaterSwitch
   This is the core extension point: use it to define your behavior based on different Type values. Each “type” corresponds to a unique async process you want to support.
   

TODO

• Split the Customizations module into a separate app so users can manage multiple async scenarios cleanly

• Improve this documentation with more use cases and patterns

• Enhance the demo to showcase common real-world async flows