Integration flows (Vorto)

Not every integration fits a ready-made connector. A customer may want a CSV file on an SFTP server every time a shipment leaves, a retailer may send purchase orders as EDI, or a platform may expect a webhook when an order is put on hold. Boxture handles these with integration flows, built in the integration engine called Vorto.

A flow describes, step by step, what happens to a message: where it comes from, how it is transformed, and where it is delivered. You build flows in the user interface without changing Boxture itself.

Where to find it

Under Admin › Integration (admins only):

• Flows: the list of flows; create and edit them here.
• Messages: every message that went through a flow, with its content at each step.
• Credentials: passwords, keys and tokens that flows use.

The Integration dashboard itself shows Daily messages per flow: the number of messages per flow per day over the last seven days, each count linking to the matching messages, followed by the list of recent messages.

Flows, messages and credentials belong to an account. You only see the ones of the account you are working in.

How a flow works

trigger  →  step 1  →  step 2  →  step 3 ...
            (message)  (message)  (message)

1. Something triggers the flow and a message is created. The message has an envelope (information about the message, such as the content type, file name or HTTP headers) and a payload (the content itself: JSON, XML, CSV, EDI or plain text).
2. The first step processes the message and hands the result to the next step.
3. Each step records what it received and produced, so you can see the message at every stage.
4. When the last step is done, the message is completed. If a step keeps failing, the message is failed.

Triggers

A flow is started in one of three ways.

When something happens in Boxture

Select a Class and an Event on the flow. Each time that event happens to a record of that class, a message is created with the record as JSON payload (content_type: application/json). The JSON is the same as the REST API returns for that record; for orders it also includes the shipments, containers and product details of the order lines.

The flow only runs for records of the flow's account and the accounts below it. A flow set up on a parent account therefore covers all of its customers.

Class	Events you can choose
Order (or a specific order type such as Sales order or Purchase order)	create, update, save, destroy, confirm, confirmed, pending, allocate, unallocate, backorder, picking, pick, unpick, pack, unpack, ship, expect, receive, build, complete, cancel, hold, release
Order line item	allocate, unallocate, backorder, pending, picking, cancel_picking, pick, unpick, pack, unpack, ship, expect, receive, build, retire, cancel
Shipment	create, update, save, destroy, hold, release, pending, label, labelled, ship, shipped, deliver, cancel
Pick list	create, update, save, destroy, assign, unassign, start, pick, unpick, reallocating, reallocate, complete, redo, cancel
Pick list line	create, update, save, destroy
Product, Packing material	create, update, save, destroy, publish, expire, republish
Account	create, update, save, destroy, activate, deactivate, disable
Location	create, update, save, destroy, activate, disable

A flow on the general Order class also runs for every order type. Choose a specific order type to limit it.

On a schedule

Enter one or more cron expressions in Cron (one per line), for example */15 * * * * for every 15 minutes or 0 6 * * 1-5 for 06:00 on weekdays. Boxture checks every minute whether a scheduled time has passed. When it has, the first step of the flow, which must be an inbound connector, collects whatever is waiting: every file on the SFTP server, or the response of an HTTP call. Each file or response becomes its own message.

A flow has either a Class and Event, or a Cron schedule; not both.

When another system calls Boxture

A flow whose first step is an inbound connector with a path option receives calls on that path below /integration. For example, a first step with path: /orders/acme accepts requests on https://oms.example.com/integration/orders/acme. The request body becomes the payload, and the query and form parameters are added to the envelope.

• By default Boxture answers immediately with status 201 and the message ID and state, and processes the message in the background. Set http: { status: 202 } on the first step to use a different status.
• With synchronous: true on the first step, Boxture processes the whole flow first and answers with the final payload, or with status 412 if the flow failed.
• Every response carries the message ID in the X-Vorto-Message-Id header.
• If the flow is disabled, the caller gets 404.

Flows

The flows list

Admin › Integration › Flows lists every flow with its Name, Enabled, Class, Event, Trigger, Status, Metadata and Created at. The Trigger column shows → with the class and event for event flows, ← with the path for inbound HTTP flows, and a sync icon for scheduled flows.

Status is a traffic light based on failed messages in the last 24 hours:

• Red: at least the red threshold failed (15 by default) and the last five messages all failed.
• Orange: at least the orange threshold failed (5 by default).
• Green: otherwise.

The thresholds are the settings Traffic light › Orange and Red for the traffic light model "Vorto".

Creating or editing a flow

1. Go to Admin › Integration › Flows and choose New, or click an existing flow.

2. Fill in the Basic tab:

   Field	Meaning
   Enabled	Only enabled flows create messages. Switch off to pause a flow without losing it.
   Account	The account the flow belongs to. Event flows run for this account and its sub-accounts.
   Name, Description	For your own reference.
   Extract template	A Liquid template whose result is stored with each message as its Extract: a short, searchable summary such as an order number.
   Class and Event	For event-triggered flows (see above). Event is required when Class is set.
   Cron	For scheduled flows. Must be empty when Class is set.
   Metadata yaml	Free YAML for your own notes or configuration.

3. Add steps on the Steps tab (see below).

4. Click Save, or Save and continue editing to stay on the form.

The YAML tab shows the whole flow as YAML, which is convenient for reviewing or copying a flow. The Messages tab lists the messages of this flow.

Steps

Each step has:

Field	Meaning
Kind	Processor (changes the message) or Connector (sends or fetches it).
Name	Which processor or connector (see below).
Extract template	Overrides the flow's extract template for this step.
Options	YAML with the step's settings.
Template	Only for the Liquid processor: the template that produces the new payload.

Steps form a tree. Drag a step onto another to make it a child; use Add child to add one. After a step completes, all its child steps run. Several children of the same step are separate branches, for example one sending a file to SFTP and another calling a webhook.

Options that work on every step:

Option	Meaning
label	A name for the step so another step can jump to it.
comments	A note, shown when the step is collapsed.
credential or credentials	One or more credential keys whose values are added to the options when the step runs.
preprocessor	How to read the incoming payload into structured data: json, xml, xml-simple, yaml, csv (with column_separator), edifact, x12 or form-data. Without it, the format is guessed from the content type.

A step can also redirect the flow: when its output envelope contains goto: some_label, the flow continues at the step with that label instead of the children.

Processors

Processor	What it does
Liquid	Renders the Template with the message as input and makes the output the new payload. Use it to turn Boxture's JSON into the CSV, XML or JSON the other side expects, or the other way round.
Service	Hands the message to a Boxture service, given in class_name. Used for inbound flows that create or update records in Boxture.
Custom	Runs custom processing code, given in class_name.

The Liquid output can start with an envelope between --- lines, for example to set the file name or HTTP method for the next step:

---
file_name: shipment-{{ message.payload.shipment.id }}.csv
content_type: text/csv
---
order;tracking_number
{% for parcel in message.payload.shipment.parcels %}{{ message.payload.shipment.customer_reference_number }};{{ parcel.tracking_number }}
{% endfor %}

To split one message into several (for example one per order line), separate the parts in the output with a line containing only ---, with a blank line before and after it. Each part becomes a child message that continues through the flow on its own.

Connectors

Every connector needs direction: inbound (fetch or receive) or direction: outbound (send).

Connector	Use	Main options
FTP, SFTP	Upload or download files	uri (or host, port, user, password, path), key (SFTP key), search (file pattern when fetching), remove (delete after fetching), overwrite, make_path, temp_path (upload there first, then move into place)
Folder (on server)	Read or write files in a folder on the Boxture server	path, search, remove, overwrite, make_path
HTTP	Call a web service, or receive calls on a path	uri, method (default get), authorization, user and password (basic authentication), oauth_credentials, timeout, failure_status_code_ranges, ssl_verify_none, proxy, client certificate and private_key
AS2	Exchange EDI messages over AS2	certificate, private_key, name, domain, partner_name, partner_certificate, verify_signature, signing_algorithm, encryption_cipher

For outbound files the file name is taken from file_name in the envelope. For HTTP, any response with a 5xx status counts as a failure unless you set failure_status_code_ranges (for example ["..199", "400.."]). Headers come from http.headers in the envelope.

An example of a two-step flow that posts every shipped shipment to a webhook:

# Class: Shipment, Event: ship
- kind: processor
  name: liquid
  template: |
    ---
    content_type: application/json
    ---
    {"reference": "{{ message.payload.shipment.customer_reference_number }}",
     "tracking": "{{ message.payload.shipment.tracking_number }}"}
- kind: connector
  name: http
  options:
    direction: outbound
    method: post
    uri: https://example.com/hooks/shipped
    credential: example_webhook

Messages

The messages list

Admin › Integration › Messages shows the messages of the last 90 days with ID, Created at, Flow, Extract, State, Subject (the Boxture record the message is about, such as an order or shipment) and Children (the number of split-off messages). You can filter on these columns and search inside payloads.

The same list appears as the Integration Messages tab on an order or shipment, showing only that record's messages.

Message states

State	Meaning
pending	Created, waiting to be processed.
processing	A step is running or waiting for a retry.
completed	All steps have finished.
failed	A step failed five times in a row (or once, in a synchronous flow).

When a step fails, Boxture retries the same step automatically: after about 10 seconds the first time, and then with increasing waits (1, 4, 9, 16 minutes on top). After the fifth failure the message becomes failed and no further steps run. There is no separate error path in a flow.

The message page

Click a message to see:

• Flow, State, Parent (for split messages), the number of message steps and when it was created.
• One tab per step, with the step's state and extract, the envelope and payload as they were after that step, the structured data as JSON, and a download link. This shows exactly where a transformation went wrong.
• Child messages, if the message was split.
• Log for message: the log lines written while processing.

Actions in the card menu:

Action	What it does
Edit flow	Opens the flow, so you can fix a step.
Reprocess	Creates a new message with the original input and runs it through the flow again. Use it after fixing a flow or after the other side is back up.
Clone	Opens a new message form pre-filled with the original envelope and payload, which you can change before sending it into the flow. Useful for testing.

Credentials

Never put passwords or tokens in a flow's options. Store them as credentials and refer to them by key.

Admin › Integration › Credentials lists credentials by Key, Metadata and Created at. Choose New to add one:

Field	Meaning
Account	The account the credential belongs to.
Key	The name used to refer to it, for example acme_sftp.
Description	For your own reference.
Data yaml	The secret values as YAML. Stored encrypted.

user: boxture
password: s3cret
host: sftp.acme.example

Use it in a step with credential: acme_sftp; the values are merged into the step's options when the step runs. In a Liquid template, refer to a value as credentials.acme_sftp.password inside a Liquid output tag.

For HTTP APIs that use OAuth, store client_id, client_secret, uri, access_token and refresh_token in a credential and set oauth_credentials on the HTTP step. Boxture refreshes the access token automatically when the other side answers 401.

Liquid in flows

Templates and extract templates have access to the message:

Variable	Content
message.payload	The payload, as structured data when it could be read (JSON, XML, CSV, ...), otherwise as text
message.raw_payload	The payload as text
message.envelope	The envelope values
message.id, message.state	The message ID and state
message.flow, message.flow_step	The flow and the current step
message.parent	The parent message of a split message
message.payload_from_label_LABEL	The payload produced by the step with label LABEL
credentials.KEY.FIELD	A value from a credential

Two extra tags are available:

{% next_counter account:'ACCOUNT_ID' name:'icn' increment:'1' format:'%09d' %}
{% set_credentials my_credential last_run '2026-11-10' %}

• next_counter increases a counter stored on the account and outputs the new value in the given format. Use it for sequence numbers that the other side requires, such as EDI interchange control numbers.
• set_credentials stores a value in a credential, for example the time of the last successful run, so the next run can use it.

Notifications for failures

Messages fire messaging events when they change state (process, complete, exception, retry). Create a messaging template for the exception event of integration messages to receive an e-mail whenever a message fails. See Messaging.

Purging

Messages are kept for a limited time. The setting Purging › Vorto messages (default 3 months) determines after how many months the messages of an account's flows are removed. Automatic purging is currently switched off, so for now nothing is removed.

Tips

• Start a new flow disabled, test it with Clone on a real message, and enable it when the output is right.
• Give every step a label and comments; it makes the message tabs much easier to read.
• Use an Extract template that shows the order or shipment reference, so you can find messages by searching the list.
• Keep an eye on the Status light on the flows list; a red light means the other side has probably been unreachable for a while.