> For the complete documentation index, see [llms.txt](https://docs.violetlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violetlabs.com/features/workflows/data-sync-workflows/getting-started.md).

# Getting started

## **Key concepts**

Before building a sync workflow, it helps to understand a few terms:

* **Source** — the system and record type you're syncing *from* (e.g., Duro – Part Revision)
* **Target** — the system and record type you're syncing *to* (e.g., ION – Part Revision)
* **Trigger** — what causes the workflow to generate (compile) Pending Changes: either a time schedule, or an activity such as Violet fetching new data from the source app
* **Filters** — optional conditions that limit which source records get synced (e.g., only sync parts with Status = "Released")
* **Mappings** — how properties in the source correspond to properties in the target (e.g., source "Part Number" → target "Item Name")
* **Dependencies** — related records synced alongside the main record (e.g., files attached to a part)
* **Pending Changes** — a staged preview of what will be created, updated, or deleted before anything is applied to your target system
* **Sync Batch** — as Pending Changes are identified, they are gathered into a sync batch. These batches hold all of the Pending Changes for an integration pair since the last sync was executed.
* **Change Execution** — the actual execution of the changes in the Target system. Each integration pair has an execution mode: **Test Mode** (never executes), **On Timer** (executes on a schedule), or **On Activity** (executes after a batch is approved, or after selected compile workflows complete). All changes in a Sync Batch are executed together.

## **Creating a workflow**

### **Step 1 — Open the workflow builder**

In the **Workflow Manager**, click <mark style="color:$primary;">**+ Sync Workflow**</mark> at the top right of the page.

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FQs9dgsvtlyGCrJ7f2qr9%2Fimage.png?alt=media&amp;token=03559741-1db8-48e8-8c5c-ea65af8cb4fe" alt=""><figcaption></figcaption></figure>

### **Step 2 — Name your workflow**

Enter a descriptive name at the top of the canvas. Choose something that makes it easy to identify later, like *"ION → Ramp Purchase Order Sync"*. We recommend including the source and target app names and the type of records being synchronized in the workflow.

### **Step 3 — Configure source and target**

When you create a new workflow, the **Source & Target** dialog opens automatically. (To change it later, click the Source or Target node on the canvas.) Select:

* The **source integration** (the system you're syncing from), then the **source entity** (the kind of record — e.g., Part, Purchase Order, Task)
* The **target integration** (the system you're syncing to), then the **target entity**

The entity field for each side appears once you've chosen its integration.

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FEMbzjP4H4zSKHSNTJDt9%2Fimage.png?alt=media&amp;token=ff9121fb-bc34-46da-9b15-c6c2fe5a9050" alt=""><figcaption></figcaption></figure>

### **Step 4 — Set a trigger**

Click the **Trigger** node and choose how the workflow generates pending changes:

| Trigger Type  | When it runs                                                                                                                     |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Activity**  | When the selected **Activity type** occurs (e.g., **Integration Fetched** — when the source integration is fetched or refreshed) |
| **Scheduled** | On a **Timer interval** you choose: every 15 minutes, 30 minutes, hour, 2 hours, 4 hours, 6 hours, 12 hours, day, or week        |

Additional trigger options:

* **Disable full compiles** — only changes from fetches are compiled. Full-integration compiles (manual or scheduled) are blocked.
* **Reconcile full integration after fetch** *(Activity triggers)* — after each fetch, compile sync changes for all source entities and configured relationships, not only the items that changed in that fetch. Off by default.
* **Scheduled full compile** *(Activity triggers)* — in addition to compiling after each fetch, recompile changes for every entity in the workflow on a schedule. Use this to pick up items whose earlier sync failed after the data was fixed. Runs after any in-progress sync for the integration pair finishes.

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2F8Xk2EeYTgKUhZtswQonb%2Fimage.png?alt=media&amp;token=160b365f-4ad8-4a9b-bd8e-a11572d2c7da" alt=""><figcaption></figcaption></figure>

### **Step 5 — Add filters and options&#x20;*****(optional)***

Click the **Filters and Options** node to control which source records are included in the sync and what kinds of changes are allowed in the target.

**Source filters**

* **Structural filters** — depending on the source, you may see options such as **Exclude assembly relationships**, **Delete relationships in target application if they do not exist in the source**, or **Sync the full BOM tree of items matching the filters** (all BOM components under a matching item will sync, even if they don't match the filters themselves).
* **Write options** — target-specific write settings, when the target offers any.
* **Default filters** — always evaluated first, for every change type.
* **Mode-specific filters** — additional filters applied, in order, after the default filters:
  * **Entity Creation Filters – Source** — apply only to the creation of new entities (e.g., only create new parts when they are part of a BOM)
  * **Entity Update Filters – Source** — apply only to updates of existing entities (e.g., only update parts in a non-Released state)
  * **Entity Deletion Filters – Source** — apply to relationship deletes under this entity (e.g., removed BOM lines); the relationship is only deleted in the target when the entity matches the filter criteria

To add a filter, click **+ Filter** and choose:

1. A **property** from the source record (e.g., Status, Is Released)
2. An **operator** — the available operators depend on the property type. Text properties offer equals, does not equal, contains, does not contain, starts with, does not start with, ends with, does not end with, is any of, is not any of, is null or empty, is not null or empty, and regex match.
3. A **value** to match against (note values are case sensitive). Turn on **Multiple values** to match against more than one value.

When you have more than one filter, use the **OR / AND** toggle to set how each filter combines with the next.

**Target filters**

* **Allowed Change Types** — uncheck **Allow Create handler** or **Allow Update handler** to prohibit that type of change for this entity type. By default, all change types are permitted.
* **Entity Update Filters – Target** — prevents updates to entities in the target that meet the filter criteria (e.g., don't update POs that have been closed in the target).

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FUYEB5u9sLmSDvYYiDSj8%2Fimage.png?alt=media&amp;token=b9483c72-3294-470e-80be-f4d82f0681a3" alt=""><figcaption></figcaption></figure>

### **Step 6 — Map properties**

Click the **Property Mappings** node to define how properties from the source translate to properties in the target. Violet will automatically populate likely property mappings between the source and target systems, but you should confirm that they are correct.

* Properties marked with \* are required — they must be mapped before you can save. Some required properties fall back to a default from your integration configuration if left empty; the builder tells you when that applies.
* Optional properties can be mapped or left blank as needed. If left blank, syncs will not create or update data in that target property during a sync. Unmapped target properties are listed under **Unmapped Fields**.
* Some target properties are mapped through your integration configuration (e.g., MATERIAL\_FIELD → Material); the builder shows this under the property name.

**Mapping options:**

| Option                  | Description                                                                                                                                                                                                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Source property**     | Map one source property directly to the target property                                                                                                                                                                                                     |
| **Fixed value**         | For select/dropdown target properties, use **Or fixed value** to set the same value regardless of source                                                                                                                                                    |
| **Plain concatenation** | Click **Use multiple fields or transformer**, then **Plain Concatenation**. Combine multiple source properties with **Add property**, and add fixed text with **Add literal**                                                                               |
| **Transformer**         | Click **Use multiple fields or transformer**, then **Transformer**, and pick a built-in transformation (e.g., Concatenate Part Number and Revision, Standardize Status, Extract NetSuite ID from String). Available transformers depend on the integrations |

Click **Back to simple mapping** to return a property to a single source property.

**Value mapping**

Click **Add value mapping** on any property to translate individual values (e.g., source status "Released" → target status "Active"). For each value mapping you can also choose:

* **When source value is blank** — **Skip — keep existing value**, **Clear value in target**, or **Map to value…**
* **When source value is unmatched** — **Pass source value through** (default) or **Map to value…**

**Advanced options**

Expand **Advanced options** on a property to set **How to handle changes at target**, which controls what happens when the target value was changed outside of Violet after the last sync: **Update from source** or **Keep target edits**.

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2F1FdzEC8S80EV4iC0JFsk%2FScreenshot%202026-05-12%20111844.png?alt=media&amp;token=0cfb0ace-306b-48f4-abbd-9a7ca8adef66" alt="" width="375"><figcaption></figcaption></figure>

### **Step 7 — Configure dependencies&#x20;*****(if shown)***

Some target entity types have required relationships or related sub-entities. For example, if you're syncing a Purchase Order, the target system may require that it be matched to a Vendor in that system. Similarly, Purchase Order Lines are a sub-entity of the Purchase Order, and they will be synced together.

These dependent syncs appear as additional rows beneath the main sync on the canvas. If your sync has required dependencies, you must configure your integration to fetch those entity types alongside the main entity that you wish to sync (e.g., you must fetch both Purchase Orders and Suppliers/Vendors on the same Integration for both the Source and Target systems). Sub-entities, like Purchase Order Lines, are automatically fetched along with their parent entity - you do not have to do any special configuration to enable this.

For each dependency:

1. **Select the source relationship** — if multiple source relationships could apply, choose which one to use
2. Optionally add **Filters and Options** and **Property Mappings** specific to that dependency

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FljdfR35FvFcI19o10W1x%2Fimage.png?alt=media&amp;token=a05094f9-e210-4c39-b5c8-c85a3be93081" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Click the outline icon at the top right of the builder to open the **Workflow Outline**, a read-only summary of the filters and property mappings for the main flow and each dependency.
{% endhint %}

### **Step 8 — Save**

Click **Save Workflow** when you're done.

If anything required is missing, the affected nodes will show a **red border with an error indicator**. Click the node to see what needs to be filled in.

On success, you'll be redirected to the Workflows list and the new workflow will appear there.

### **Step 9 — Choose execution method and set notifications**

Execution is configured per integration pair. In the **Workflow Manager**, open the selector next to **Workflow Manager /** (it shows **All Integrations** by default) and choose your **Source → Target** pair. Then click the gear in the **Execution Configuration** block.

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FAtrKq6bIyR5ySt8x9Szl%2FScreenshot%202026-05-12%20111703.png?alt=media&amp;token=964cbdf9-42b6-4369-aedb-76d734521f23" alt="" width="375"><figcaption></figcaption></figure>

Choose an **Execution Mode**:

| Execution Mode  | What happens                                                                                                                                                                                                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Test Mode**   | Workflows run and generate Pending Changes, but nothing is written to the target. Pending changes are never executed.                                                                                                                                           |
| **On Timer**    | Pending changes are executed on the **Timer Interval** you choose.                                                                                                                                                                                              |
| **On Activity** | Pending changes are executed when the selected **Activity trigger** occurs: **When pending changes batch is approved** (manual approval), or **When selected compile workflows complete** (automatic execution after the chosen workflows finish successfully). |

By default, Violet fetches the target integration after an execute batch completes so the results can be validated. Turn on **Disable automatic target integration fetch after execute batch completes** to skip this.

<figure><img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FGihVVj2AuGwf40pnhHfy%2Fimage.png?alt=media&amp;token=62686c09-b367-4fc3-8ac6-790e5af3224c" alt="" width="178"><figcaption></figcaption></figure>

#### Notifications

Turn on **Turn on notifications**, then choose:

* **Notify on** — **Success**, **Failure**, or both
* **Delivery methods** — **Email** and/or **In-app**
* **Notify users** — who receives the notifications

Click **Save Configuration** to apply your changes.

***

## **Managing Sync Workflows**

From the Workflows list, each workflow card shows its name, source and target integrations, number of rules and mappings, last run, next run, latest run status, and current status (e.g., **Active**).

* **Edit:** To edit a workflow, click anywhere on the workflow card.
* **View Run History (**<img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2F4IFOJyH4FdXmxqleBNRw%2Fimage.png?alt=media&amp;token=70bfbb64-f6fb-46fd-957e-2bf759ddc2ec" alt="" data-size="line">**):** View past compile runs for the workflow, with metrics, filters by status and date, and the number of entities created, modified and deleted in each run.
* **View Config History (**<img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FYpvyiE0Ef9qVrEogQlty%2Fimage.png?alt=media&amp;token=cce25cea-6d76-4839-b82b-5142cfd520b6" alt="" data-size="original">)**:** View historical changes to the workflow configuration (triggers, attribute mappings, execution method).
* **Create changes for entire integration (**<img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FD41eLUQ66ztWfx8mQ2O0%2Fimage.png?alt=media&amp;token=fca824a2-abf0-4b3a-8f95-ead3bfd638b5" alt="" data-size="line">**):** Immediately stage pending sync changes for all records in the source system. You can use this for initial changes when you are first setting up your workflow if you don't want to wait for the next source integration fetch.
* **Pause:** Pause the workflow.
* **Delete (**<img src="https://2091741164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvrraExym8pNEUvBDoima%2Fuploads%2FUxTon9pv8KzaDgQhCi2t%2Fimage.png?alt=media&amp;token=9c775919-0420-4894-8593-d0949f8c1c72" alt="" data-size="line">**):** Delete the workflow.

### **Drafts**

While you build a new workflow, the builder saves your work as a draft in your browser. You can also click **Save Draft** to save it explicitly.

* Click **Clear Draft** inside the builder to discard the draft at any time
* Clicking **Cancel** leaves the builder and discards the draft

> ***Note:** Drafts are stored in your browser and will not appear on other devices or after clearing your browser data.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violetlabs.com/features/workflows/data-sync-workflows/getting-started.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
