Mediation Flows - Transform, Route and Connect Systems

Audience: Low-code Engineers

Skill Prerequisites: Workflows, Actions, Tokens, APIs

A mediation flow sits between systems. It receives a message from one system, changes it into the shape another system expects, decides where it should go, and sends it there. The systems don't need to know about each other.

In Plant an App, a mediation flow is a workflow or an action list. It's started by an API endpoint, an Automation job or a form. Its actions do the work. This page shows the building blocks and three complete examples:

1. Transform a message and forward it
2. Route messages by their content
3. Send one event to several systems, with error handling

Building Blocks

Step	What it does	Features
Receive	Starts the flow when another system calls in, on a schedule, or when data changes.	API endpoints (REST, secured with API keys, JWT or OAuth scopes. The request body is in [RawInput]), Automation jobs with time, database and app triggers, Email Sync (IMAP), form events
Read	Turns the incoming message into tokens.	Parse JSON Into Tokens, Parse XML Into JSON Tokens, Create List from JSON, Create List from SQL
Transform	Renames, maps, calculates, formats and rebuilds data.	Remap List, List to JSON, Create JSON Object, Create/Update Tokens, Regex Replace, date and string tokens, Execute Javascript (Server), Execute Razor
Route	Picks the path based on the data.	Exclusive Gateway, the Condition of any action, calling another workflow (Execute [Name of Workflow]), Contracts (Enterprise)
Repeat	Processes every item of a list, or retries.	Execute Actions for each List Entry, Repeat, Wait
Connect	Sends data to other systems.	Server Request (any REST or SOAP API over HTTPS), Run SQL Query (other databases, including Oracle and Db2, see Connecting to Oracle, Db2 and Other Databases), Import List into Database (bulk load into SQL Server), Send Email, Upload to FTP, add-ons such as Slack, Salesforce and Dynamics CRM
Handle errors	Catches failures, retries, logs and answers the caller.	Execute Actions with On Error, per-action On Error, Throw Exception, Log Error, Raw Response, New Object as JSON
Run in parallel	Runs branches at the same time and waits for all of them.	Parallel Gateway (Start / End Parallelization in the workflow editor, Enterprise)

tip

Put the mediation logic in a workflow and call it from the API endpoint or Automation job. The same workflow can then be reused by other triggers and tested on its own. A workflow runs in an isolated scope: it only sees its Input Parameters and only returns its Output Parameters. See Workflows Overview.

Example 1: Transform an order and forward it

A web shop sends new orders as JSON. The ERP expects a different format: other field names, a date without time, and the total as a number. The flow receives the order, reshapes it and forwards it to the ERP.

Start: an API endpoint orders, method POST, access with an API key. The caller sends Content-Type: application/json.

Workflow Transform Order, with the input parameter Payload. The API endpoint calls it with Payload = [RawInput].

#	Action	Settings	Result
1	Parse JSON Into Tokens	JSON String [Payload], Base Token Name In	[In:orderNo], [In:customer.email], [In:createdAt] …
2	Create List from JSON	JSON [In:lines], List Name Lines	The order lines as a list
3	Remap List	Source List Lines, a mapping list sku → ItemCode, qty → Quantity, price → UnitPrice, Result List Name ErpLines	Lines with the ERP's field names
4	List to JSON	List ErpLines, Output Token Name ErpLinesJson	The lines as a JSON array
5	Create JSON Object	DocumentNo (String) = [In:orderNo] DocumentDate (String) = the date part of [In:createdAt], with a date token CustomerEmail (String) = [In:customer.email] Total (Number) = [In:total] Lines (JSONArray) = [ErpLinesJson] Output Token Name ErpBody	The ERP request body
6	Server Request	Method POST, URL of the ERP API, Header Content-Type: application/json, Header Authorization: Bearer [ErpToken], Data [ErpBody], Output Token Name ErpResponse	The ERP's answer

Output parameter: Result = [ErpResponse]. The API endpoint returns it to the caller with Raw Response, HTTP code 200.

XML instead of JSON. If the shop sends XML, replace step 1 with Parse XML Into JSON Tokens. The rest of the flow stays the same. To send XML to the target system, build the body with a text template in Create/Update Tokens or Execute Razor, and set the Content-Type header of the Server Request to application/xml.

More complex mapping. When the mapping needs logic that's hard to express with actions, use Execute Javascript (Server) (see its example Keep only a few fields from a JSON response).

Example 2: Route messages by their content

A single entry point receives documents from partners. Each document must go to a different system, depending on its type and amount.

Start: an API endpoint documents, method POST. It calls the workflow Route Document with Payload = [RawInput].

Workflow Route Document:

1. Parse JSON Into Tokens, JSON String [Payload], Base Token Name Doc.
2. An Exclusive Gateway with these branches. Conditions are checked in order, and the first one that's true is followed.

Order	Branch condition	Target system	Action
1	[Doc:type] == "invoice"	ERP (REST API)	Server Request POST to the ERP invoices endpoint
2	[Doc:type] == "order" && [Doc:amount] > 10000	Approver (email)	Send Email through an SMTP connector, to the approvers
3	[Doc:type] == "order"	Orders database	Run SQL Query with a Database connector, values passed as Bind Tokens
4	[Doc:type] != "invoice" && [Doc:type] != "order"	Quarantine	Log Error + Run SQL Query that saves the message for manual review

3. Set the output parameter RoutedTo in each branch, for example ERP, Approval, Orders or Quarantine. The API endpoint returns it with New Object as JSON.

note

If no branch condition is true, the Exclusive Gateway throws an exception. Make sure the conditions cover every possible message, as branch 4 does above.

Without a gateway. In an API endpoint or Automation job action list, you can get the same result with the Condition of each action. See Common Parameters.

Routing to a workflow chosen at run time (Enterprise). Workflows that share a Contract have the same inputs and outputs, so the router can choose which one to call based on the message.

Example 3: Send one event to several systems

When a new order is saved, three systems must be updated: the CRM (REST API), the ERP database and the sales team (email). A failure in one system must not stop the others, and it must be recorded.

Start: an Automation job with an On Database Insert trigger on the Orders table. It calls the workflow Order Created with OrderJson = [Row:JsonData]. See Triggers.

Workflow Order Created:

1. Parse JSON Into Tokens, JSON String [OrderJson], Base Token Name Order.
2. CRM. Execute Actions containing:
   • Repeat with up to 3 repetitions while [CrmStatus] != "ok". Inside it, a Server Request POST to the CRM with Ignore Errors on and Output Token Name Crm, then Create/Update Tokens that sets CrmStatus to ok when the call succeeded, otherwise a Wait of 2,000 ms before the next try.
   • On Error: Log Error CRM update failed for order [Order:OrderNo]: [ExceptionMessage] and set CrmStatus to failed.
3. ERP database. Run SQL Query with the ERP Database connector and Bind Tokens. On Error: Log Error and set ErpStatus to failed. Execution continues with the next action.
4. Sales team. Send Email through an SMTP connector, with Ignore Errors on.
5. Audit. Run SQL Query that saves the order number and the status of each system in an audit table.
6. Fail when it matters. Throw Exception with the Condition [CrmStatus] == "failed", if the CRM update is mandatory. The run fails and shows up in the Automation history.

Run the branches at the same time (Enterprise). Put steps 2, 3 and 4 between Start Parallelization and End Parallelization in the workflow editor. The branches run at the same time, and the workflow waits for all of them before the audit step. The tokens from every branch are merged back, and errors from every branch are reported.

Don't wait for a slow system. Execute Actions Asynchronously starts actions in the background and continues at once. Its errors are only logged, so use it only for systems where a missed update can be repaired later.

Considerations

• Licensing. Server Request and Run SQL Query need the Data Integration feature. Regex Replace and the code actions need Scripting. The Parallel Gateway, Contracts and the Client Certificate option of Server Request are Enterprise. Slack, Salesforce, Dynamics CRM and Email Sync are add-ons.
• Security. Protect API endpoints with API keys, JWT or OAuth scopes. See API Overview and JSON Web Token Access. Keep secrets in connectors, not in action parameters. Server Request supports HTTPS and client certificates for mutual TLS.
• Database values. Pass values to SQL with Bind Tokens, not by pasting tokens into the query.
• Repeated messages. Partners can send the same message twice. Save a message ID and skip messages you've already processed.
• Each run is independent. A workflow's tokens exist only during one run. See Execution Context. Keep any state that must last between runs in the database.
• Monitoring. Use Debug mode on API endpoints and Automation jobs while you build. Use the Automation history and logging actions in production.

Revised 11/05/2026