Skip to main content

Data Pipelines

Import workers, jobs, and locations from your HRIS or another system into Fountain by CSV upload, SFTP, or webhook, and map and transform the data on the way in.

Data Pipelines is a native data ingestion tool that lets you import data from external files or systems directly into Fountain (no third-party middleware required). You define reusable pipeline configurations that map incoming data to Fountain entities, then trigger imports manually through the app, automatically via SFTP, or in real time via webhook when an external system routes data to Fountain.

  • Workers

  • Jobs

  • Locations

  • Location Groups

  • Openings

  • Prospects


How Imports Match Existing Records

When you import a file, Fountain decides, row by row, whether to update an existing record or create a new one. It compares each row with every matching key you mapped:

  • One match: Fountain updates that record.

  • No match: Fountain creates a record.

  • More than one match: the row fails, and the error names the records it matched. Nothing is changed.

There is no priority between keys. Every key you map counts, so map only the keys you trust.

Data type

Fountain ID

Your system's ID

Other keys

Jobs

Fountain or Hire ID

HRIS ID

Name

Locations

Fountain or Hire ID

HRIS ID

Name

Location groups

Fountain ID

None

Name

Workers

Fountain ID

HRIS ID or External ID

Email or SSN

Openings

Fountain or Hire ID

HRIS ID

Location, job and shift

Prospects

Fountain ID

None

Email

Users

Fountain or Hire user ID

None

Email

Applicants

Fountain or Hire ID

Email and Opening

Know These Rules Before You Map

  • A Fountain ID only updates. If no record has it, the row fails. To create records, leave the ID empty.

  • Your system's ID is set once. After the first import stamps it, a pipeline can't change it, and neither can the API. Map it from your first import, together with the name or email, so the first run finds your existing records.

  • Names match exactly, including case. "Paris" and "paris" are two locations, and a record renamed in your source system creates a new one. To rename a record, map the HRIS ID or the Fountain ID.

  • Terminated workers match only by Fountain ID. Importing a former worker by email or HRIS ID creates a new worker profile.

  • SSN as a key works only if the person who saved the mapping can view protected attributes.

  • Owner and supervisor columns accept a WX user ID, a Hire user ID or an email. Exactly one active user in your account must match.

  • Openings without a shift match only an Opening that also has no shift.

  • Applicants are matched per Opening, so the same person on two Openings is two applicants.

  • Users imports update a user's first and last name only. They don't change email, role or groups, and they are refused when SCIM is turned on for your account.

  • The standard Jobs import matches on Fountain ID and name only. To match jobs on an HRIS ID, create a custom pipeline.

  • Pipelines created before October 28, 2026 keep the previous matching. Clone one to move it to these rules. A pipeline that follows these rules shows the note "How Fountain matches rows to existing records" on its Mapping step.

Fix Rows That Fail

The pipeline logs list each failed row with its line number and one of these messages:

Message

What happened

What to do

This row matches more than one job: name (ID), name (ID).

The row's keys point at different records.

Fix the data, or remove the column that disagrees.

No job has the ID ID. A Fountain ID only updates an existing record.

The Fountain ID matches nothing.

Check the ID, or leave it empty so the row can create a record.

This job already has HRIS ID ID. A pipeline can't change it.

The row carries a different HRIS ID than the one stored.

Correct the ID in your source system.

No active user in this account matches value. Use a WX user ID, a Hire user ID or an email.

An owner or supervisor matches no active user, or several.

Use a value that identifies one active user.

Couldn't verify the owner.

Fountain could not read your users at that moment.

Run the import again.

Validation failed: name: Required

The row has no name.

Add the name, even when the row has an ID.

Duplicate job name 'name' (first seen at row n)

Two rows in the same file share a name. This check ignores case.

Keep one row per record.

The record type in each message follows the data type: job, location, worker, and so on.


Navigate to Data Pipelines

Navigate to Settings, then search for Data Pipelines or scroll to the Workflows section and select it.


The Data Pipelines page

The Data Pipelines page lists all pipeline configurations for your account.

Each pipeline displays the following:

  • Name — The pipeline's display name

  • Direction — Import (inbound); outbound direction is coming soon

  • Data Type — The Fountain entity type the pipeline targets (e.g., Jobs, Workers)

  • Source — The format used (e.g., CSV)

  • Status — Active or inactive

  • Internal — Whether the pipeline is a Fountain-provided standard configuration (Internal) or one created by your team (Custom)

  • Created On — The date the pipeline was created

Use the search field to find a pipeline by name. Select Explore Logs to view the full execution history across all pipelines.

Standard and Custom Pipelines

Fountain provides pre-built standard pipelines for each supported entity type. Standard pipelines are ready to use without any configuration and cover standard field imports. They are listed with an Internal label.

Custom pipelines are created by your team to handle non-standard schemas, custom attributes, or specific transformation requirements. They are listed with a Custom label.


Create a Data Pipeline

Select Add a data pipeline from the Data Pipelines page. If no pipelines exist yet, select New Data Pipeline from the empty state.

Pipeline creation has two steps: Setup and Mapping.

Set Up the Pipeline

The Setup step configures the pipeline's basic properties.

  1. Enter a name for the pipeline in the Name field.

  2. Under Attributes to provide, Inbound from Outside to Fountain will be selected by default.
    ​Outbound Direction is coming soon — The Outbound from Fountain to outside option is not yet available.

  3. Open the Data type dropdown and select the Fountain entity you want to import data into: Workers, Jobs, Locations, Openings, Location Groups, or Prospects.

  4. Under Sample data, provide a representative sample of your source file. Fountain uses this sample to generate the field mapping interface in the next step. Choose one of three input methods:

    • CSV file — Upload a CSV file (10 MB max)

    • JSON file — Upload a JSON file (10 MB max)

    • JSON — Paste JSON data directly into the text area

  5. If your JSON source data is nested, select Enter custom path under JSON data path and specify the path to the data array.

  6. Select Next to continue to the Mapping step.

Map Fields

The Mapping step connects fields from your source data to the corresponding fields in the Fountain database.

Fountain automatically maps source columns to Fountain fields when the names match. For any column that has not been mapped, open the Select field dropdown on the right side of that row and choose the appropriate Fountain target field.

The Mapping step also shows a blue note, How Fountain matches rows to existing records, with the matching keys for the data type you selected. Each key you map is used to match rows to existing records. See How Imports Match Existing Records.

Target fields are organized into two categories:

  • Standard fields — Core Fountain fields such as uuid, name, etc...

  • Custom attributes — Custom fields defined for your account (for example, Department, Grade, FLSA Status)

To map a source field that does not appear in the main mapping list, select Add a mapping. The Add mapping panel opens on the right side of the screen. Select the source column from the Source Field dropdown, then select the target field from the Target Field list.

To remove a mapping — for example, if your sample file contains extra headers you do not want to import — select the delete icon to the right of that row.

Add Calculated Fields

Sometimes your source data does not line up with Fountain one-to-one: a value arrives in the wrong format, or a single Fountain field has to be built from several source columns. For those cases, add a Calculated Field.

A Calculated Field works differently from a normal mapping. Its value is not copied from a source column — it is computed by a short JavaScript expression that you write, and the result is what gets mapped into the Fountain target field. This lets you handle messy source files directly in Fountain, without pre-processing them in another tool first.

Create a Calculated Field

  1. In the Mapping step, open the + menu and select Calculated Field.

  2. Enter a Field Name. This is a synthetic field that does not exist in your source file, so name it after the value it produces — for example full_name or normalized_state.

  3. Write a Script. It must be a JavaScript arrow expression that receives { row } and returns the value for the field. Read a column with row.column_name, or row["Column Name"] when the header contains spaces or special characters.

  4. Select Save. The new field appears as a row in the mapping list with a Calculated badge — open the dropdown on that row to choose the Fountain target field that receives the result.

To change a script later, select the </> icon on the calculated row. Select Read documentation inside the editor for a searchable library of ready-made examples.

Examples

Common patterns, in increasing order of complexity:

  • Combine several columns — your file has separate first and last name columns, but Fountain needs one display name:
    ​({ row }) => row.first_name + " " + row.last_name

  • Normalize casing and stray spaces — state codes arrive as " ca" or "Ca" and must be consistent:
    ​({ row }) => row.state_code.trim().toUpperCase()

  • Reformat a date — your system exports 03/14/2026 but Fountain expects an ISO date:
    ​({ row }) => row.hire_date.replace(/(\d{2})\/(\d{2})\/(\d{4})/, "$3-$1-$2")

  • Split a combined value — one column holds "Operations - Night Shift" and you only want the department:
    ​({ row }) => row.department.split(" - ")[0]

  • Translate a code into a readable value — your file uses FT and PT:
    ​({ row }) => row.emp_type === "FT" ? "Full time" : "Part time"

  • Derive a true or false value — flag remote roles based on the location name:
    ​({ row }) => row.location_name.toLowerCase().includes("remote")

  • Clear a value on purpose — a blank cell never erases anything, so return an empty string to clear an attribute:
    ​({ row }) => row.status === "terminated" ? "" : row.uniform_size

For lookups that depend on data already in Fountain — resolving a location or job name to its record, or translating a long list of codes through a Dataset used as a lookup table — select the entity types you need under Enrich import data using on the Setup step. They are then available to your script as named parameters. The Read documentation panel in the script editor shows the exact syntax for each entity.

Script Execution and Error Handling

Scripts run in a secure sandbox, once per row, with a short execution limit per row. Keep them simple and free of side effects, and make sure they return a single value (text, number, true/false, or empty).

If a script fails on a given row, that field is left unmapped for that row rather than failing the whole import. Failures appear in the pipeline logs as Calculation error, with the row number and field name.

Always use Test before saving the pipeline to confirm your calculated values resolve as expected against real sample data.

Test the Mapping

Before saving, test the mapping against your sample data to confirm that fields resolve correctly.

Select Test in the top right corner of the Mapping step. The Preview Mapping modal opens ready to run the test. Click Run Test to run the mapping against all records in your sample data.

The modal has three sections:

  • Record list (left) — A scrollable list of records from your sample data. Select any record to view its values in the center panel.

  • Sample data (center) — The field values for the selected record, showing source values and their resolved Fountain targets. The top of this panel displays a summary of total lines processed, errors, and warnings.

  • Logs (right) — A per-field breakdown showing whether each mapping passed or failed, along with the resolved value

If you need to adjust a mapping after reviewing the results, close the modal, update the mapping, and select Test again. Select Retry within the modal to re-run the test without closing.

Save the Pipeline

When you are satisfied with the mapping, select Save in the top right corner of the Mapping step.

The pipeline is saved and added to the Data Pipelines list with a status of Active. A confirmation message appears at the top of the page.

Import Data

There are three ways to import data using a pipeline: directly from an entity settings page for manual imports, automatically via SFTP, or in real time via webhook when an external system sends data to Fountain.

Import From an Entity Settings Page

Settings pages for supported entity types, and some entity-specific pages such as Hire openings, include an import option for uploading a CSV file and processing it through a pipeline immediately.

For Openings, you can also start an import directly from the Hire Openings page by selecting Add Opening > Import Openings. This uses Data Pipelines to upload opening data from a CSV file and process it through the selected opening import configuration.

To import data manually:

  1. Navigate to the entity settings page, or for Openings, go to the Hire Openings page and select Add Opening > Import Openings.

  2. Select Import.

  3. In the Upload a CSV file with your [entity] data modal, open the Import configuration dropdown and select the pipeline to use.

  4. Optionally, select Download CSV template to download a correctly formatted template for the selected pipeline.

  5. Upload your CSV file by dragging it into the upload area, or select browse to locate it on your computer (CSV file, 10 MB max).

  6. The Preview Mapping modal opens automatically and displays a preview of the resolved data against the selected pipeline's mapping.

  7. Review the results. Warnings appear for any rows where a field may not resolve as expected. Errors indicate rows that cannot be imported.

  8. Select Import [entity] to execute the import.

Standard Configurations Available Out of the Box

Fountain provides pre-built standard pipelines for each entity type. These work for most standard-attribute imports with no setup required. If you need to import custom attributes or apply specific data transformations, select a custom pipeline from the dropdown or create one in Data Pipelines.

After the import completes, you are returned to the entity list. Import results are available in the pipeline logs.

Blank Cells and Missing Columns Keep Existing Values

When an import updates an existing worker, job, location, location group or prospect, a column you leave out of the file keeps its current value, and so does a blank cell. The pipeline log shows an Empty value warning for each blank cell, so you can see what was skipped.
To clear a value on purpose, add a Calculated Field whose script returns an empty string (({ row }) => "") and map it to that attribute.
Openings work differently: an opening update replaces the opening's custom attributes, so include every attribute you want to keep.

Import via SFTP

SFTP Import Requires Configuration

SFTP-based imports require a dedicated folder provisioned by a Fountain representative. Contact your Fountain representative to set up SFTP access for your account.

Connect via an External Webhook

If your external system supports outbound automations (for example, triggering a notification when a worker record is created or updated in your HRIS) you can route that data directly into a Fountain Data Pipeline without SFTP access or engineering assistance.

To set this up, create an automation in Fountain's Automation Center using Webhook as the source. Fountain generates a webhook URL that you provide to your external system. When the configured event occurs in that system, it sends a JSON payload to the URL, and Fountain processes it through the selected pipeline.

This approach is self-serve — no SFTP access or engineering assistance required — as long as your external system supports outbound event notifications.

View Pipeline Logs

The Logs page shows the execution history for all pipeline runs. Select Explore Logs from the Data Pipelines page to access it.

Each log entry displays:

  • Direction — Whether the run was an import

  • File Name — The name of the file that was processed

  • Data Pipeline — The pipeline used to process the file

  • Status — Whether the run succeeded or failed

  • Last Attempted At — The date and time of the run in local time

Select a log entry to view the full execution detail, including row-level statistics: total rows processed, success count, failure count, create count, and update count.

Rows that fail to match are listed in the execution detail with their line number and a message that explains what happened. See Fix Rows That Fail.

Select Copy payload to copy the raw execution log to your clipboard.

Did this answer your question?