Integrations & automation

# Build a self-configurable integration

Exchange data with any system over API, SQL, FTP, SFTP, webhook or email, with your own triggers, filters and field mappings.

Updated 4 October 2026

**Who can do this:** Role level 800 or higher and the integration permission.

A self-configurable integration is for systems that do not have a preset connector. You decide when it runs, which records it handles and how fields in the other system map to fields in Transportial. One integration can have several data sources, for example one that fetches orders and one that sends back status updates.

## Choose how the integration starts

After you choose **Self-configurable integration** as the type, pick a trigger in **Select trigger Type**:

* **Scheduled**: runs at fixed intervals or on a cron schedule, for example to poll an FTP folder every 10 minutes.
* **Trigger**: runs when something happens in Transportial. Choose one or more events in **Select trigger event**, for example when a trip is updated.
* **Listener**: waits for the other system to send data in, for example through a webhook or by email. Its data sources are then set to incoming data.

For **Trigger** and **Listener**, you can add filters so the integration only runs for matching records.

## Create the integration

1. Open the side menu (☰, top right), choose **Integrations** and click **\+ Create integration**.
2. Enter a **Name** and choose **Self-configurable integration** in **Select integration type**.
3. Choose the trigger in **Select trigger Type** and, for a scheduled integration, set the schedule.
4. For a **Trigger** or **Listener** integration, optionally click **\+ Add filter** and build a condition: a **Selector** (the field), a comparison (for example **Equal to (==)** or **Is in ...**) and a **Value**.
5. Click **\+ Add data source**.
6. Choose the direction in **Select data direction...**: **IN** for data coming into Transportial, **OUT** for data going out.
7. Choose the connection in **Select connection type...** and fill in its fields (see below).
8. Choose which kind of record the data source creates or reads in **Select entity**, for example a transport order or a trip.
9. Map the fields (see below) and test the mapping.
10. Set **Off/On** to on and click **Save**.

## Connection types

| Connection         | What you set up                                                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | The **URL** and the request method in **Select request method**.                                                                       |
| **SQL connection** | The database address and login details.                                                                                                |
| **FTP** / **SFTP** | **Host**, **Port**, **Path** and login details.                                                                                        |
| **Virtual FTP**    | Transportial hosts the FTP server for you. The connection details and login are generated when you save; share them with your partner. |
| **Webhook**        | After saving, a webhook address appears. Give it to the other system so it can post data to Transportial.                              |
| **Email receiver** | Transportial receives the data by email.                                                                                               |

For every connection, the **With authentication** switch decides how access is secured. Switch it on to enter login details. Leave it off to allow only the **IP Addresses** you enter. For outgoing data, choose the file format (JSON, XML or CSV) in **Select dataType**.

## Map the fields

Each mapping line connects a field in the other system to a field in Transportial.

* **Incoming** and **Outgoing**: the path of the field on each side.
* **Select field type**: **Text**, **List**, **Object**, **Boolean**, **Date Time**, **Time** and more. Lists and objects contain their own lines.
* **Format**, **Regex** and **Default value**: read a date in a given format, pick part of a value, or fill a value when the field is empty.
* Options such as **Identification** (the field identifies the record, so a second delivery updates it instead of creating a duplicate), **Trim** or **To capital letters**.

Click **\+ Add field** to add a line, or switch on **JSON mode** to edit the whole mapping as text. With an entity selected, **Generate mapping with AI** drafts a mapping for you. Switch on **OTM** if the data source uses the Open Trip Model standard instead of your own mapping.

## Options for incoming data

* **Sequential processing**: handle deliveries one by one, in order.
* **Partial updates**: a delivery names only some elements (for example one order of a trip) and the others are kept. Every element must carry an identifier; an element delivered with deleted = true is removed.

## Test the mapping

1. Switch on **Test view** for the data source.
2. Paste or enter sample data from the other system.
3. Click **To test** and check the result shown next to it.

Save your sample data as a test so you can rerun it after every change. See [Test an integration](/en/help/integration-tests).

## Related articles

* [Connect other systems with integrations](/en/help/integrations)
* [Test an integration](/en/help/integration-tests)
* [Monitor an integration](/en/help/integration-logs)
* [Import data from a file](/en/help/data-importer)

## Still need help?

Our support team is happy to answer any question about Transportial.

[Contact support](/en/contact)[Report an issue](/en/report-issue)

---
Canonical page: https://transportial.com/en/help/self-configurable-integration