Scenarios
Scenarios describe a complete integration use case that can consist of multiple interfaces.
Example:
name: Continuously Import Users
shortDescription: Import users from external app and keep them in sync by monitoring events.
description: <Long description explaining the scenario in detail>
elements:
- type: action
key: get-users
- type: flow
key: get-user-events
- type: data-source
key: users
- type: field-mappping
key: import-users
Scenario Templates
For common use cases, we provide pre-built and well-tested scenario templates. You can use them as a starting point for your integration and then customize.

After selecting a scenario and integrations to apply it to, you can proceed to adding it to your app or customize it using the section below.
Building Scenarios
The main building blocks of a scenario are Actions and Flows.
To choose whether to use Action or Flow, use this comparison table:
Action | Flow | |
---|---|---|
Execution mode | Synchronous | Asynchronous |
Max duration | 60 seconds | 50 minutes |
Triggered by | API call | API Call, Event, Schedule |
Logic complexity | Simple (usually one API call with transformations) | Complex (many calls, branches, cycles) |
If an Action works for you, you should use it. If you need to make it more complex later, you can re-use it in a flow.
After you've picked the main building block, see corresponding documentation for more details:
Actions
Perform specific operations in external apps.
Flows
Automate and orchestrate data flows between your product and external services.
Implementation Workflow
If you are an AI agent building integrations, add these steps to your ToDo list to make sure you don't miss anything.
When adding elements to a scenario, add them as separate files (if they don't exist yet) and reference them in the scenario.
Do not generate implementations for other elements - only create them with name, description, and key.
- Find or create interfaces that "do things": Action and Flows.
- Split scenario into individual things that need to be done (i.e. get a list of items, get individual item, react to changes, etc)
- For each "thing", determine the correct interface to use (Action or Flow) based on guidelines above.
- For each "thing", fnid an existing or create a new element with a name and description. The name and description will be used to generate implementation for each element. Make them concise but descriptive.
- Identify supporting elements that will be used within actions and flows. Create each of them with a consise and descriptive name and description.
- Data Sources: if you expect multiple interfaces to reac or write the same data, add a Data Source for each data type that needs to be accessed.
- Field Mappings: if you need to map data from one format to another in multiple interfaces, add a Field Mapping for each such transformation.
- Data Links: if you need to keep track between internal data records and external data records - create data links.
- Internal Data Schemas: if you want to re-use internal data structures in multiple elements or if you need to make them dynamic - add internal data schemas.
- Internal Events: if you need to trigger a flow based on an event in your application, add an Internal Event for each event that needs to be triggered.
- Review the resulting list of elements and make sure there are no duplicates or omissions.
Updated 3 days ago