Batch imports and exports
Overview
FTE Tree provides batch import functionality for loading or updating many records from CSV files. Imports are useful during initial setup and when making controlled bulk changes to departments, employees, job codes, positions, position assignments, funding sources, compensation settings, and custom details.
Imports validate the whole file before applying changes. If validation fails, no rows are applied. After an import is confirmed, FTE Tree records import history, row counts, actor, validation result, linked records, and any generated approval requests.
Access needed
| Activity | Access needed |
|---|---|
| View import history | View data imports |
| Create or prepare imports | Create data imports plus the relevant record permission, such as Create positions, Update employees, or Manage job codes |
| Apply import changes | Execute data imports plus the relevant create or update permission for the imported records |
| Download import files | Download import files |
| Reverse completed imports | Reverse data imports plus the relevant create or update permission for the imported records |
| Access setup | See Permissions and roles. |
Recommended setup order
If you are batch creating the main workforce records for a new organization, import them in this order:
- Job codes and compensation setup.
- Departments.
- Department job-code availability.
- Employees.
- Positions and position values.
- Position assignments.
- Funding sources and funding allocations, if not included with positions.
- Approval workflow setup, if managed through import.
Use this order because each later import can depend on records from an earlier one. Positions reference departments and job codes. Position assignments reference positions and employees. Funding allocations reference funding source values.
Template options
Before importing, download the template file for the type of data and mode you need.
- 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, update them in a spreadsheet, and upload the file back into FTE Tree.
The exact template columns can vary by organization. FTE Tree uses your active detail labels in downloaded templates, so your file might show a renamed employee detail, job code detail, position detail, custom detail, or external ID label.
Shared template rules
| Rule | Details |
|---|---|
| Create templates | Include the columns used to create new records. |
| Update templates | Include ID plus the matching reference for the import type. |
| Blank update cells | A blank mapped detail cell in update mode leaves the existing value unchanged. |
| Effective date | Required for employees, job codes, positions, position assignments, compensation values, adjustments, pay ranges, funding allocations, and effective-dated custom details. |
| Configured required details | Active details marked required are required for new records. |
| Parent columns | Parent, manager, and reports-to columns are optional. If supplied, the value must match an existing parent record or a parent created earlier in the same create import. |
| Hierarchy safety | Parent changes cannot point to the row itself or create a circular relationship. |
Empty value rules
FTE Tree treats empty import values conservatively. This follows the standard bulk-load pattern that absence should not delete existing production data unless the file uses a supported explicit clear action.
| File value | Result |
|---|---|
| Missing optional column | Ignored. No value is validated or changed. |
| Blank mapped detail cell in update mode | No change. FTE Tree does not create a blank value row and does not clear the existing value. |
| Blank mapped optional detail cell for a new record | Skipped. The new record is created without that optional detail value. |
| Blank mapped required detail cell for a new record | Validation error. Required details need a value before the import can be applied. |
<clear> for optional funding source |
Clears the funding-source allocation using the supported clear marker. |
<clear> for required funding source |
Validation error. Required details cannot be cleared. |
Use current-values update templates when updating existing records. They show the current values so you can edit only the values that should change and leave the rest blank.
Common column groups
Departments
Department templates commonly include Name, Parent department, Available to assign positions, and Available job codes. Departments do not use an effective date for their own name and availability settings, but department parent and GL-related values can have effective dates where your organization uses those features.
Job codes
Job code templates commonly include Effective date, Job code, Parent job code, Default wage rate, Pay grade, and Adjustments. Job-code values can be effective-dated so wage and pay-range values can change over time.
Employees
Employee templates commonly include Effective date, Employee number, external employee ID when enabled, manager employee number, employee status, job code, base wage rate, and configured employee details.
Positions
Position templates commonly include Effective date, Position number, external position ID when enabled, Name, Department, Job code, Reports to, FTE, Base wage rate, Adjustments, Funding source, and configured position custom details.
In create mode, leave Position number blank when FTE Tree should assign the next position number. In update mode, FTE Tree can match by ID, position number, or enabled external position ID.
Position assignments
Position assignment templates commonly include External assignment ID, Effective start, Effective end, Position identifier, Employee identifier, Assignment FTE, Assignment type, and Primary assignment.
Assignments are imported separately from position records so staffing changes can be maintained without rewriting the position's approved FTE or wage setup.
Funding sources
Funding source is a position built-in detail. 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:
General fund:60;Grant:40
The source names must match existing funding source values in your organization. Percentages must total exactly 100.00% and support up to two decimal places.
Use <clear> only when you intentionally want to clear an optional funding source value. If funding source is required for your organization, <clear> is rejected during validation.
Upload and validation
After uploading, FTE Tree validates the file before making changes. Validation checks:
- Required details and value formats.
- Unknown, blank, or duplicate headers.
- Matching references such as position number, employee number, job code, department, and external IDs.
- Department job-code availability.
- Circular parent relationships.
- Duplicate row identifiers.
- Funding allocations totaling exactly
100.00%. - Whether the user has permission for the affected department and record type.
- Whether controlled position changes should be applied directly or submitted as approval requests.
If validation fails, correct the file and upload it again.
Review and confirm
Once validation succeeds, review the preview before confirming. The summary shows total rows, valid and invalid rows, expected creates, expected updates, unchanged rows, warnings, and whether any rows will create approval requests.
Confirming an import requires Execute data imports plus the relevant data permission. Your organization may also require an audit note when you confirm the import.
Position approval behavior
Some position imports can apply directly, such as permitted reference updates or changes to details that do not require approval. Controlled position changes can instead create approval requests for review. The import history links to records that were applied directly and requests that were submitted.
When an import creates approval requests, users should review the generated request details, approval path, FTE and cost impact, requested values, and attachments before approval.
Recovering a stopped import
Most imports finish without action. 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 Continue remaining rows when it is available and the rows already loaded are correct. If continuation is not available, prepare a corrected file containing only the rows that still need work. If the loaded rows are wrong, use the reversal preview to see what can be rolled back.
Rows that load successfully keep their own record history. Row errors stay on the import result page and row-detail download.
Exporting from FTE Tree
Exports are available from reports, current-values update templates, and selected list pages. Use reports when you need period output or calculation details. Use current-values update templates when you plan to edit existing setup or position records and upload the results.
Downloads are audited when they include sensitive, position, employee, approval, or import data.