Importing a workflow from another builder
L2M can import a workflow exported from another visual workflow builder. The export format it understands has top-level nodes[], connections{}, settings and pinData. The import converts every node it can into an L2M node, rebuilds the edges, carries positions and sticky notes over, and hands back a report that tells you exactly what needs a human look before the flow runs.
The converter is pure: it never contacts the source system and never reads credential values. What you get is an ordinary L2M workflow (schemaVersion 1.0.0) that passes graph validation, plus the report.
In the Studio
- Open the import dialog from any of these places:
- Import… on the Home page.
- Import from another builder… in the editor's ⋯ menu.
- The command palette (
⌘KorCtrl+K). - Dropping the
.jsonexport straight onto the canvas.
- Drop the file, choose it, or paste the JSON. The Studio converts it with a dry run and shows a preview: how many nodes mapped, were approximated or became placeholders, the reason for each, and what you will need to fix afterwards. Nothing is saved yet.
- Adjust the workflow name if you like and press Import workflow. The workflow is stored in the active project and opens in the editor.
- A checklist docks on the canvas. It lists the credentials to link, variables to fill in, expressions to rewrite and placeholder nodes to replace. Items tick themselves off as you fix them. Clicking a node name selects it on the canvas.
- Link credentials: pick a stored secret from the list. Every node that used that credential is pointed at it.
- Tidy layout re-flows the imported graph into stages.
- Validate saves pending edits and runs graph validation, listing any issues with links to the nodes involved.
The checklist stays with the workflow in your browser until you dismiss it, so you can leave for the Secrets or Variables page and come back. The Import JSON entry also recognises these exports and routes them through the same preview, while L2M's own exports import directly.
Endpoint
POST /api/workflows/import/externalRequires the builder role or above, and workflow:write in the target project.
| Field | Type | Meaning |
|---|---|---|
source | object | The export JSON as an object. |
sourceText | string | The export JSON as a string (for drag-and-drop uploads). Used when source is absent. |
projectId | string | Target project. Defaults to the folder's project, else default. |
folderId | string | Target folder. Must exist and belong to the target project. |
name | string | Overrides the workflow name from the export. |
dryRun | boolean | When true, converts and validates but stores nothing. |
The response is { workflow, report }. With dryRun: true the workflow is the converted document and nothing is written; otherwise it is the stored workflow (with its final id, project and folder) and the import is recorded in the audit log as workflow.import_external.
A malformed export returns 400 with a message naming what is missing, for example a top-level nodes array or a node without a type.
curl -X POST http://localhost:4000/api/workflows/import/external \
-H "content-type: application/json" \
--cookie "ao_session=..." \
-d '{ "sourceText": "<contents of the export file>", "dryRun": true }'Run it once with dryRun: true, read the report, then run it again without the flag when you are happy with the mapping.
The three node statuses
Every source node appears exactly once in report.nodes with one of three statuses and a reason:
| Status | Meaning |
|---|---|
mapped | The node has a direct L2M equivalent and its settings were carried over. |
approximated | The node was converted, but something was simplified. The reason says what, for example "only the first sort field was imported". |
unsupported | There is no L2M equivalent yet. The node becomes a placeholder (see below). |
report.summary holds the counts, and report.warnings lists workflow-level issues such as dropped connections or an invalid timezone.
Placeholders for unsupported nodes
An unsupported node is imported as a disabled noop_node named after the original node, labelled Unsupported: <short type>, the last segment of the source type. Its config keeps the original parameters under importedFrom (parameters, type, version, notes, and the names of any credentials) so nothing is lost when you replace it by hand.
Because the placeholder is a pass-through, the edges into and out of it are kept and the rest of the flow still loads, validates and runs. Attachments that cannot be honoured, for example a tool sub-node with no L2M equivalent, are dropped and listed in report.warnings.
App nodes
Nodes for Slack, GitHub, Google Sheets, Postgres, Notion, Jira, Airtable, HubSpot, Salesforce, Stripe, AWS S3, Telegram and Discord are converted onto L2M's connector nodes. The source builder expresses these as a resource and an operation, so the converter dispatches on that pair:
- A pair L2M covers is
mapped, for example posting a Slack message, commenting on a GitHub issue, searching Airtable records or creating a Stripe customer. - A pair that is close but loses settings is
approximated, and the reason names each dropped setting: a Sheets "append or update" becomes a plain append, a HubSpot "create or update" becomes a create, Slack attachments and message options are dropped, a Postgres select is rewritten as SQL. - Any other pair becomes a disabled placeholder whose reason names the resource and operation, so you can see at a glance what to rebuild.
Ids are read from the source's resource pickers: ids are kept, URLs for spreadsheets, Notion databases, Airtable bases and Slack channels are parsed down to the id, and anything referenced only by name is flagged for review. Every string parameter goes through the same expression translation as core nodes.
Triggers (Slack, GitHub, Sheets, Postgres, Stripe, Telegram, Discord) map onto the L2M trigger nodes. The webhook-style ones get a fresh path named after the node and a signing-secret placeholder; the reason tells you to point the external subscription at the new path, and lists any event filters the L2M trigger cannot apply.
Connection details that live inside a source credential rather than on the node, such as a Postgres host, a Jira site URL, a Salesforce instance URL, a Discord webhook URL or an AWS region, are not part of the export. Those nodes import as approximated with empty fields to fill in, and the credential itself still appears in the secrets checklist under a name that says what to provide, for example "Postgres password" or "Slack bot token". A trigger's signing secret and a send node's token get separate entries even when the export lists one credential for both.
Expression translation
The common expression subset is translated into L2M template syntax. Translated references resolve against results, which exposes the output of every completed node by id.
{{ $json.x }} or {{ $input.item.json.x }} -> {{results.<previous node id>.x}}
{{ $('Name').item.json.x }} or {{ $node["Name"].json.x }}
-> {{results.<id of Name>.x}}
{{ $env.KEY }} or {{ $vars.KEY }} -> {{vars.KEY}} (plus an empty workflow variable KEY to fill in)
{{ $now }} or {{ $now.toISO() }} -> {{ $now.toISOString() }}
{{ $workflow.name }} / {{ $execution.id }} -> {{workflow.name}} / {{execution.id}}IF, Switch and Filter conditions are compiled into L2M expressions; IF outputs become the true and false handles, Switch outputs become case handles with the extra fallback output on default.
JavaScript code nodes are wrapped in a small compatibility shim that provides $json, $input, $('Name') and item-list return values, so most code runs unchanged. Python code is kept verbatim and marked approximated.
Anything the translator does not understand is left verbatim and listed in report.unresolvedExpressions with the node id, the config path, the original expression and the reason, for example an unknown node name or a date helper with no equivalent. Those templates will render empty until you rewrite them, so treat the list as a checklist.
Secrets checklist
Credential references in the export become secretRef placeholders. The import never stores or echoes a credential value: report.secretsToResolve lists each placeholder's secretId, the credential type, the credential name from the export, and the node ids that use it.
After importing:
- Create the secret under Secrets if it does not exist yet, then link it from the import checklist in the editor. Through the API, replace the placeholder
secretIdin each listed node's config with the stored secret's id. - Fill in connection details that lived inside the source credential rather than the node, such as an IMAP host or an Azure OpenAI endpoint. The node's report reason says when this applies.
- Set the workflow variables listed in
report.variablesToSet.
Coverage
The table below is generated from the converter's registration table. Regenerate it after changing the converter:
pnpm --filter @ai-orchestrator/workflow-engine gen:import-coverageTriggers
| Source node type | L2M node | Notes |
|---|---|---|
n8n-nodes-base.manualTrigger | manual_trigger | Direct mapping. |
n8n-nodes-base.webhook | webhook_input | Header auth becomes bearer_token on the authorization header; other auth modes are dropped. |
n8n-nodes-base.scheduleTrigger | schedule_trigger | Interval rules become cron; only the first rule is kept; second-level intervals become every minute. |
n8n-nodes-base.cron | schedule_trigger | Legacy trigger times become cron; only the first entry is kept. |
n8n-nodes-base.interval | schedule_trigger | Defaults to hourly when no interval can be read. |
@n8n/n8n-nodes-langchain.chatTrigger | chat_trigger | Direct mapping. |
n8n-nodes-base.errorTrigger | error_trigger | Direct mapping. |
n8n-nodes-base.formTrigger | form_trigger | File fields become text fields. |
n8n-nodes-base.rssFeedReadTrigger | rss_trigger | Poll times become a poll interval in seconds. |
n8n-nodes-base.emailReadImap | imap_email_trigger | Host, port and user live in the credential and must be filled in after import. |
Core nodes
| Source node type | L2M node | Notes |
|---|---|---|
n8n-nodes-base.httpRequest | http_request | Query parameters are appended to the URL; binary responses become text; auth becomes a secretRef placeholder. |
n8n-nodes-base.code | code_node | JavaScript is wrapped in a compatibility shim; Python is kept verbatim. |
n8n-nodes-base.function | code_node | Legacy function code is wrapped in the same compatibility shim. |
n8n-nodes-base.set | set_node | 'Keep only set fields' is not supported; other fields pass through. |
n8n-nodes-base.if | if_node | Conditions compile to one expression; outputs 0 and 1 become the true and false handles. |
n8n-nodes-base.switch | switch_node | Same-field equality rules become cases; other rule sets compile to a routing expression. |
n8n-nodes-base.merge | merge_node | Combine-by-fields keeps the first match field; SQL and position combines become append. |
n8n-nodes-base.splitOut | split_out_node | Only the first field to split out is kept. |
n8n-nodes-base.itemLists | split_out_node | Legacy item list node treated as split out. |
n8n-nodes-base.aggregate | aggregate_node | Collecting values into an array is approximated with the concatenate operation. |
n8n-nodes-base.filter | filter_node | Field-path conditions map directly; expression conditions need review. |
n8n-nodes-base.sort | sort_node | Only the first sort field is kept; custom sort code needs review. |
n8n-nodes-base.limit | limit_node | Direct mapping. |
n8n-nodes-base.wait | wait_node | Timer, webhook and specific-time resumes are supported; form resume is approximated as a timer. |
n8n-nodes-base.noOp | noop_node | Direct mapping. |
n8n-nodes-base.stopAndError | stop_and_error | Error objects are reduced to message and errorCode. |
n8n-nodes-base.executeWorkflow | execute_workflow | The workflow id refers to the source system and must be repointed; per-item mode becomes a single call. |
n8n-nodes-base.stickyNote | sticky_note | Direct mapping. |
AI nodes
| Source node type | L2M node | Notes |
|---|---|---|
@n8n/n8n-nodes-langchain.lmChatOpenAi | openai_chat_model | Direct mapping. |
@n8n/n8n-nodes-langchain.lmOpenAi | openai_chat_model | Completion model approximated as a chat model. |
@n8n/n8n-nodes-langchain.lmChatAnthropic | anthropic_chat_model | Direct mapping. |
@n8n/n8n-nodes-langchain.lmChatGoogleGemini | google_gemini_chat_model | Direct mapping. |
@n8n/n8n-nodes-langchain.lmChatOllama | ollama_chat_model | Base URL defaults to the local Ollama endpoint. |
@n8n/n8n-nodes-langchain.lmOllama | ollama_chat_model | Base URL defaults to the local Ollama endpoint. |
@n8n/n8n-nodes-langchain.lmChatAzureOpenAi | azure_openai_chat_model | The endpoint lives in the credential and must be set after import. |
@n8n/n8n-nodes-langchain.lmChatOpenRouter | openai_compatible_chat_model | OpenAI-compatible endpoint with the provider's public base URL. |
@n8n/n8n-nodes-langchain.lmChatGroq | openai_compatible_chat_model | OpenAI-compatible endpoint with the provider's public base URL. |
@n8n/n8n-nodes-langchain.lmChatMistralCloud | openai_compatible_chat_model | OpenAI-compatible endpoint with the provider's public base URL. |
@n8n/n8n-nodes-langchain.lmChatDeepSeek | openai_compatible_chat_model | OpenAI-compatible endpoint with the provider's public base URL. |
@n8n/n8n-nodes-langchain.lmChatXAiGrok | openai_compatible_chat_model | OpenAI-compatible endpoint with the provider's public base URL. |
@n8n/n8n-nodes-langchain.agent | agent_orchestrator | Model, memory and tool sub-nodes become attachment edges; an attached output parser becomes the next step. |
@n8n/n8n-nodes-langchain.memoryBufferWindow | local_memory | Direct mapping. |
@n8n/n8n-nodes-langchain.memoryPostgresChat | local_memory | External memory stores are approximated with the local Simple Memory store. |
@n8n/n8n-nodes-langchain.memoryRedisChat | local_memory | External memory stores are approximated with the local Simple Memory store. |
@n8n/n8n-nodes-langchain.memoryMongoDbChat | local_memory | External memory stores are approximated with the local Simple Memory store. |
@n8n/n8n-nodes-langchain.memoryZep | local_memory | External memory stores are approximated with the local Simple Memory store. |
@n8n/n8n-nodes-langchain.memoryMotorhead | local_memory | External memory stores are approximated with the local Simple Memory store. |
@n8n/n8n-nodes-langchain.memoryXata | local_memory | External memory stores are approximated with the local Simple Memory store. |
@n8n/n8n-nodes-langchain.mcpClientTool | mcp_tool | SSE transport becomes HTTP streamable; tool exclusion lists are not supported. |
@n8n/n8n-nodes-langchain.outputParserStructured | output_parser | Runs as a step after the agent; schemas are inferred from example output when no manual schema is given. |
@n8n/n8n-nodes-langchain.lmChat* | openai_compatible_chat_model | Any other chat model type is approximated as an OpenAI-compatible endpoint with a placeholder base URL. |
App nodes
| Source node type | L2M node | Notes |
|---|---|---|
n8n-nodes-base.slack | slack_send_message | Message posting maps to a bot-token send; attachments and most message options are dropped; other resources and operations become placeholders. |
n8n-nodes-base.slackTrigger | slack_trigger | Event and channel filters are not supported; the signing secret becomes a placeholder. |
n8n-nodes-base.telegram | telegram_send_message | Text messages map directly; keyboards and most options are dropped; other resources and operations become placeholders. |
n8n-nodes-base.telegramTrigger | telegram_trigger | Update filters are not supported; the webhook secret token becomes a placeholder. |
n8n-nodes-base.discord | discord_send_message | Webhook sends map with content, username and embeds; bot-token sends and other operations become placeholders. |
n8n-nodes-base.discordTrigger | discord_trigger | Event filters are not supported; the application public key must be set after import. |
n8n-nodes-base.github | github_action | Issue create/comment/close, file get/create/edit and repository issue listing map to github_action operations; labels, assignees and filters are dropped; other operations become placeholders. |
n8n-nodes-base.githubTrigger | github_webhook_trigger | Event filters are not supported; the webhook must be created on the repository by hand. |
n8n-nodes-base.jira | jira_create_issue | Issue creation and JQL search map; the site URL and email live in the credential; other operations become placeholders. |
n8n-nodes-base.notion | notion_create_page | Database page creation and querying map; simple property types are translated, manual filters and content blocks are dropped; other operations become placeholders. |
n8n-nodes-base.googleSheets | google_sheets_read | Read, append, append-or-update and update map to the Sheets nodes; row filters and header matching are dropped; sheets picked by gid need the range set; other operations become placeholders. |
n8n-nodes-base.googleSheetsTrigger | google_sheets_trigger | Polls the sheet for new rows; row-update events are approximated. |
n8n-nodes-base.postgres | postgres_query | Execute-query and select map to a query; the connection details live in the credential; insert, update, upsert and delete become placeholders. |
n8n-nodes-base.postgresTrigger | postgres_trigger | Table and LISTEN triggers are approximated as a polling query. |
n8n-nodes-base.airtable | airtable_list_records | Search, create and update map to the Airtable nodes; auto-mapped fields are dropped; get, upsert and delete become placeholders. |
n8n-nodes-base.awsS3 | aws_s3_get_object | File download, upload and listing map to the S3 nodes; the region lives in the credential; binary uploads need the body set; bucket and folder operations become placeholders. |
n8n-nodes-base.hubspot | hubspot_create_contact | Contact create-or-update becomes a create and contact get maps directly; other resources and operations become placeholders. |
n8n-nodes-base.salesforce | salesforce_create_record | Record creation and SOQL search map; list operations become SOQL; the instance URL lives in the credential; other operations become placeholders. |
n8n-nodes-base.stripe | stripe_create_customer | Customer and charge creation map with metadata; addresses, shipping and payment sources are dropped; other resources and operations become placeholders. |
n8n-nodes-base.stripeTrigger | stripe_webhook_trigger | Event filters are not supported; the signing secret becomes a placeholder. |
Any other source node type is imported as a disabled noop_node placeholder that keeps the original parameters, so the workflow still loads and validates.