> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twine.se/llms.txt
> Use this file to discover all available pages before exploring further.

# Property Mapping

> Mapping fields between a system's data model and Twine's

A property mapping defines how a single field from a source system translates into a Twine property, or vice versa. Every domain mapping is made up of a set of property mappings - one per field that should be transferred.

There are three kinds of property mapping:

## 1. Direct (1:1)

The simplest kind. The value is copied from source to destination with no transformation applied.

Every direct mapping has a **direction**:

| Direction | Description                                                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| To Twine  | The value is read from the system and stored on the Twine entity. Also referred to as "common" in some parts of the platform. |
| To system | The value is read from the Twine entity and written to the system.                                                            |
| Both      | The value flows in both directions.                                                                                           |

The **both** direction deserves special attention. It does not mean that the integration itself is bidirectional - Twine does not support synchronising changes back and forth between two systems, as this creates ambiguity about which system holds the authoritative value. Instead, mapping a property in both directions is used to give Twine visibility into the current value on the destination system. This is important for calculating deltas: before writing a value, Twine can compare what it intends to send against what the system already holds and skip the write if nothing has changed.

Direction must be configured with care when multiple Twine properties map to the same remote field. If two mappings both have **both** direction and target the same remote field, the value Twine writes back becomes undefined - it is not deterministic which of the two local values will be used. In this situation, only one mapping should be set to **both** or **to system**. Any additional mappings that read the same remote field purely to populate a local Twine property should be set to **to Twine**.

## 2. Direct with transformers

The same as a direct mapping, but the value passes through one or more **transformers** before reaching its destination. Transformers are applied in sequence.

Each transformer is configured per direction. A mapping set to **both** can apply a different transformer depending on which way data is flowing - for example, string to float when reading from the system, and float to string when writing back. This allows a single mapping to handle the format differences between Twine's data model and the system's in both directions without requiring separate mappings.

Twine includes a set of general-purpose transformers for common type coercions:

* String to date, integer, or float
* Float to percentage
* Boolean conversions
* And others

In addition, many integrations include **system-specific transformers** - transformations that only make sense in the context of a particular system. Examples include active state mappings (translating a system's own status codes to Twine's active/inactive model) and salary period normalisations (mapping a system's pay frequency codes to Twine's standard representation).

## 3. Data Engine transformation

For cases that cannot be expressed as a direct mapping - with or without transformers - a property mapping can use the **Data Engine** to derive the final value. The Data Engine is a node-based pipeline where nodes are wired together to compute an output from any combination of inputs.

A property mapping can have **at most one Data Engine graph** attached to it. That graph is the unit of execution: when the mapping runs, the engine executes the attached graph from its root to its end node, and the value on the end node becomes the value of the mapping.

Data Engine mappings are always **one-way**. The engine reads from attributes on the opposite side (e.g. when mapping to Twine, it reads from the system model) and produces a single output value. It can also emit a **constant** value with no inputs at all, which is useful for hardcoding values that the source system does not provide.

### Reusable graphs

Graphs that need to be reused across multiple property mappings can be saved to the **Data Engine library** at the Organization level. A library graph is a standalone graph that can be invoked from a property mapping graph via a dedicated call node.

<Note>
  The call node used to invoke a library graph from another graph is not yet available. Until it is added, library graphs cannot be referenced from property mappings.
</Note>

<Card title="Data Engine" icon="diagram-project" href="/data-engine/index">
  Full reference for all available nodes and how to wire them together.
</Card>