Batch import and export

Introduction

FTE Tree provides batch import functionality for loading or updating many records from CSV files. This is useful when initially setting up your organization and when making controlled bulk changes to positions, employees, job codes, or departments.

Imports can take a little time to finish. After upload, FTE Tree validates the file, lets you review the results, and applies confirmed changes. Larger imports may continue processing after you leave the page; the import list and detail page show the latest status while work is running.

Each import job receives an organization-scoped import number, such as IMP-0001. This is a display reference for users reviewing import status, audit history, and downloads. Organization administrators can change the prefix and padding in general organization settings, including removing the hyphen by changing the prefix.

The import process

Batch imports follow a multi-step process designed to protect your data:

Import access is separated by action. A user may be allowed to view import status, upload files and templates, download submitted files or current values update templates, execute validated imports, or reverse completed imports independently. Import permissions do not replace the matching data permissions. For example, an employee import also requires the matching employee create, update, or sensitive read permission depending on the action. Approval-bypass warnings on Operating Budget position imports are shown and audited when applicable, but they are not a separate permission.

Recommended order for setting up a new organization

If you are batch creating the main workforce records for a new organization, import them in this order:

1. Job codes
2. Departments
3. Employees
4. Positions

Use this order because each later import can depend on records from an earlier one:

• Departments can use Available job codes, which must reference job codes that already exist.
• Positions reference departments and job codes, and FTE Tree checks that the job code is available for the selected department.
• Positions can also reference employees as incumbents, so employee records should exist before position records that assign incumbents.
• Position hierarchy files should place parent positions earlier in the same file, or import the parent positions first.

Step 1: download a template

Before importing, download the template file for the type of data and mode you need. Blank template download and upload require Create data imports plus the matching create or update permission for that data type. Current values update templates include current data, so they require Create data imports, View data imports, Download import files, the matching update permission, and the matching read permission for that data type.

FTE Tree provides three template options:

• Blank create template: Use this headers-only file to create new records. Create imports never update existing records.
• Blank update template: Use this headers-only file to update existing records. Update imports never create missing records.
• Current values update template: Use this to export current values for existing records. FTE Tree exports the file only when the full result fits within your organization's import row limit, which defaults to 5,000 data rows and does not count the CSV header row; if it is too large, the download is blocked with a clear message instead of returning a partial file. Contact us if your organization needs a higher limit. For departments, employees, and job codes, you can download an available-records version when inactive records are not needed. If you upload an unchanged current values update template, the rows are treated as unchanged.

Update templates include an ID column and the usual matching field for the import type. Current values update templates use the same columns as blank update templates. Blank cells in update templates generally mean "leave the existing value unchanged." FTE Tree keeps create and update imports separate; choose Create for new records or Update for existing records.

When external position IDs are enabled, position templates include the configured external ID column. Current values update templates include each position's current external ID value.

Employee templates use Employee number as the FTE Tree display reference. In create mode, you can leave Employee number blank and FTE Tree will assign the next number. If the same file needs manager references, provide the manager's Employee number so later rows can reference it. Employee hierarchy columns use Manager employee number, not the manager's name.

When imports read employee numbers, FTE Tree extracts the integer portion of the value. For example, EMP-0007, EMP0007, E0007, and 7 all resolve to employee number 7. The prefix, hyphen, and leading zeros are display formatting, not a separate system ID.

If your organization enables external employee IDs, templates also include your configured external employee ID column. Use that field for HRIS or integration identifiers. It is required only when your organization marks external employee IDs required.

Template columns by import type

The exact template columns can vary by organization. FTE Tree uses your active field configuration labels in the downloaded templates, so your file might show a renamed employee field, job code field, position field, custom position field, or external position ID label. The import page sidebar shows the current labels for your organization, and the downloaded CSV template is the best guide for the column headers your upload should use.

Downloaded templates use sentence-case, user-facing column labels such as Effective start, Position number, Parent position, Name, Job code, and Base wage rate. Use the exact column labels shown in the downloaded template when preparing your upload.

Shared template rules

Department columns

Employee columns

Employee field value formats:

Job code columns

Job code field value formats:

Position columns

Position field value formats:

Step 2: upload your file

Upload your completed data file and choose Create or Update mode.

When importing positions, choose a Scenario destination. The default blank choice is Operating Budget:

• Operating Budget: Position changes are imported into the Operating Budget.

• Scenario: Position changes are imported as draft changes in the selected scenario.

Step 3: validation

After uploading, FTE Tree validates the file before making any changes. During validation:

• Each row is checked for required fields, correct formats, and valid relationships.

• Headers are checked for blanks, unknown columns, and duplicate columns. Header problems explain which column needs correction.

• Position files can include both Name and Job code. FTE Tree treats these as separate position fields, not as duplicate name columns.

• Create mode is checked to prevent accidental updates to existing records.

• Update mode is checked to prevent accidental creation of missing records.

• Parent changes for positions, departments, employees, and job codes are validated to ensure they do not create circular references in the hierarchy. If a proposed parent would result in a circular relationship, a validation error is reported for that row.

• Position imports cannot assign a new department value to a department that is unavailable for position assignment. Existing position rows can keep their current unavailable department so historical and reporting data is preserved.

• Position imports validate the selected job code against the selected department. If the job code is not available for that department, the row is blocked until the department-job-code mapping is corrected.

• Duplicate or invalid row identifiers and matching values are reported with the affected row.

• Operating Budget position imports are checked against your organization's position limit before changes are applied.

• Row and file issues identify the affected row and column when possible, explain the problem, and provide a suggested fix. Row numbers refer to data rows only; the CSV header row is not counted. For example, import row 1 is the first data row below the header, and import row 9303 is usually spreadsheet line 9304 when the header is on line 1. Downloading row details requires import file download permission plus the matching data read permission because it can expose row-level data.

• If a row fails while the import is being applied, the issue list explains what failed and what to review.

• If the import cannot finish, the import detail page shows the error and any suggested next step.

• Warnings identify rows that can continue but may need review, such as warnings about bypassing approval workflows.

If validation fails, you can review the errors, correct your data file, and re-upload.

Step 4: review and confirm

Once validation succeeds, review the preview output to verify the changes are correct. The summary shows:

• Total rows processed.
• Valid and invalid row counts.
• Number of records expected to be created, updated, or left unchanged.
• Field values expected to be skipped because the uploaded value already matches the current value.
• A row preview showing each row's create, update, unchanged, or cannot-import result before confirmation.
• Any warnings or issues found during validation.
• Whether the import can be checked for reversal later.

When you are satisfied with the results, confirm the import to apply the changes. This action requires Execute data imports plus the matching create or update permission for the import type and mode. Your organization may also require an audit note when you confirm the import. For position imports, each row must also be within the acting user’s department access.

Step 5: completion

After confirmation, FTE Tree applies the import and tracks:

• The number of records created, updated, and unchanged.
• Any errors encountered during the import.
• The total row count and success count.

Only rows with real changes are tracked for later reversal. FTE Tree also tracks row progress during execution so a stopped import can show which rows were already processed and which rows still need attention.

When processing finishes, FTE Tree updates the affected position totals so Staffing Strategy and reports use the latest values.

Recovering a stopped import

Most imports finish without you needing to do anything after confirmation. If an import is interrupted, open the import detail page and review the final status, issue summary, and error message before starting another upload.

Use the status to decide what to do next:

• Still importing or stopping: Refresh the import detail page or return to the import list later. The detail page checks whether the import appears to have stopped, and the active import list checks periodically while it is open. If FTE Tree can safely recover the status, it will update to Stopped, Partially processed, Failed, or Completed with errors. If the import does not move for much longer than expected, contact support.
• Stopped: You or FTE Tree stopped the import before every row finished. Rows already confirmed as loaded stay loaded. Review the row counts, choose Download row details if needed, then either choose Continue remaining rows, use Preview reversal, or upload a corrected file.
• Failed: FTE Tree did not find applied import changes for that job. If the page shows Continue remaining rows, use that action to continue from saved progress. If not, review the error and issue summary, correct the file if needed, and upload it again.
• Partially processed: FTE Tree processed part of the file and saved progress, but some rows were not confirmed as loaded. Review the row counts and issue summary. If Continue remaining rows is available, you can use it to process rows that were not confirmed as loaded.
• Completed with errors: FTE Tree finished processing the file, but some rows had issues. Review the issue summary and download row details if you need a row-by-row file and have permission.

Rows that load successfully keep their own record history. For example, a successfully loaded position shows Position imported or Position updated by import in the position history. Row errors stay on the import result page and row-detail download, and the Partially processed or Completed with errors status stays with the import job. These do not appear on the individual employee, position, job code, or department record.

Row ranges in recovery messages use the same data-row numbering. A message such as "rows 559-1319 failed" means the 559th through 1,319th data rows in the import file, not including the header row. In a spreadsheet with the header on line 1, those rows normally appear one line lower.

Recovery does not automatically apply row changes from a page refresh. If the page shows Continue remaining rows, choosing that action continues from saved progress and skips rows already confirmed as loaded. If the page shows an original validation preview after a stopped import, that preview is historical context from before the import started. It does not mean FTE Tree revalidated or reran the remaining rows.

You can also stop a running import from the import detail page. Stop import asks FTE Tree to finish the current row and then pause the remaining rows. It does not roll back rows that already loaded. After the import reaches Stopped, review the detail page before deciding whether to continue, reverse, or upload a corrected file.

When an import shows Partially processed or Completed with errors after a stopped process, do not immediately rerun the same full file. First decide whether the loaded rows are correct and whether continuation is available:

• If Continue remaining rows is available and the loaded rows are correct, use it. FTE Tree skips rows already confirmed as loaded.
• If continuation is not available and the loaded rows are correct, prepare a corrected file for the rows that still need work and upload that file.
• If the loaded rows are wrong, use Preview reversal to see what FTE Tree can roll back. If there are no blockers and you have permission, run Reverse import.
• If the reversal preview has blockers, review the blocker messages before making more changes. You may need to correct the data manually or contact support.

Reversal only applies to changes FTE Tree tracked during the import. If a row was unchanged or never loaded, there is nothing to reverse for that row.

How to reimport safely

The safest recovery path is the action shown on the import detail page. Use Continue remaining rows when it is available and the rows already loaded are correct. If continuation is not available, use a new corrected file instead of uploading the original file again unchanged.

1. Open the stopped import and review the status, row counts, and issue summary.
2. If Continue remaining rows is available and the loaded rows are correct, choose it and monitor the import detail page.
3. If you need to upload a new file, choose Download row details for a row-by-row list of what loaded or needs attention.
4. Make a new file that contains only the rows that still need to be loaded or corrected.
5. Keep the same import type, mode, approval mode, and scenario unless you intentionally want a different workflow.
6. Upload the corrected file, review validation, and confirm only after the preview matches what you expect.

For create imports, remove rows that were already created. If you need to change records that were already created, use an update import instead of trying to create them again.

For update imports, include only the rows that still need changes. Blank update cells generally leave the current value unchanged, so keep only the columns and values you want to apply.

If you are not sure which rows loaded, use the row-detail download, the import detail counts, and the affected records before confirming another import.

Special column formats

Some field types require a specific format in the import file:

Position numbers

Position import templates use the displayed position number. If your organization uses a prefix or leading-zero padding, a downloaded template with data may show values such as POS-0007, POS0007, or 0007.

Imports extract the integer portion of the position number, such as 7. FTE Tree stores that integer value and applies your organization's prefix and padding when the position is displayed again. This is useful when spreadsheet tools remove leading zeros from CSV files or when an older file uses a different display prefix.

Use the external position ID field for HRIS or payroll identifiers. Position number is the FTE Tree display reference used to match existing positions and parent positions during update imports.

Funding sources

Funding source is a position core field. It is visible by default and optional by default. In position imports, funding source columns use a semicolon-delimited format where each entry is a source name followed by a colon and the percentage:

SourceName:Percentage;SourceName:Percentage

For example, to assign 60% to "General fund" and 40% to "Grant":

General fund:60;Grant:40

The source names must match existing funding source option values in your organization exactly. Percentages must total 100% and support up to two decimal places (e.g., General fund:33.33;Grant:33.34;Self-funded:33.33). Leave the column empty if the position has no funding source assignment. If your organization marks the funding source field as required, each imported position must include a valid allocation.

Multiple adjustments

Multiple adjustment columns use a similar semicolon-delimited format. Refer to Position adjustments for details.

Reversing an import

If you discover an issue after completing an import, FTE Tree may be able to reverse it. Reversal requires Reverse data imports plus the matching create or update permission for the import type and mode.

Reversal has two steps:

1. Preview reversal: FTE Tree prepares a preview that lists records to delete, values or relationships to restore, expected update impact, and blockers.
2. Reverse import: If the preview has no blockers, FTE Tree starts the reversal.

Reversal is all-or-nothing. If a blocker is found, the import is not reversed. Common blockers include later edits to imported data, approval requests that use imported records, departments or records already connected to other data, comments on imported records, missing records, or other conflicts that would make reversal unsafe.

Created records can usually be deleted if they have no blockers. Existing records that were updated can usually be restored when they have not been changed again after the import. If someone edits imported data after the import, the reversal preview blocks that record and explains why.

Import status

You can monitor the progress of your batch import through the following statuses:

• Uploaded: The import has been uploaded and is waiting for validation.

• Validating: The data is being validated.

• Validated: Validation is complete and the import is ready for confirmation.

• Validated with warnings: Validation passed, but warnings should be reviewed before confirmation.

• Validation failed: The data did not pass validation. Review issues and re-upload.

• Waiting to import: The import has been confirmed and is waiting to be applied.

• Importing: The confirmed import is being applied.

• Stopping: A stop request was received. FTE Tree is finishing the current row before pausing the remaining rows.

• Stopped: The import stopped before every row finished. Review loaded and remaining rows before continuing, reversing, or uploading a corrected file.

• Completed: The import finished.

• Partially processed: FTE Tree processed part of the file and saved progress, but rows still remain to review or continue.

• Completed with errors: The import finished processing every row, but some rows had issues.

• Failed: The import encountered a critical error.

• Preparing reversal preview: Reversal preview is running.

• Reversal ready: Reversal preview completed without blockers.

• Reversal blocked: Reversal preview found blockers.

• Reversing: The reversal is running.

• Reversed: The import has been reversed.

The import detail page shows status, current step, row counts, issue counts, next available actions, and any error message. Issue results can be downloaded as CSV.

Import audit history records key actions such as upload, template and file downloads, validation, confirmation, approval bypass when applicable, reversal preview, reversal, attempts, and final results. Row issues and row-level change details stay on the import result page and row-detail download so the history timeline remains focused on lifecycle events.

Need help?

If you have questions about batch imports or need assistance preparing your data, please contact us or email us at support@ftetree.com.