Overview
The Universal Importer lets you bulk-create projects and phases in Factorial by uploading a spreadsheet. Instead of adding projects one by one, you can prepare all your data in Excel or CSV format and import everything at once.
This guide walks you through the full process: preparing your file, uploading it, mapping columns, reviewing your data, and completing the import.
Before you start
Permissions
You need the Import resources permission to use the Universal importer. If you don't see the import option, contact your Factorial administrator.
Supported file formats
The importer accepts the following file types:
- .xlsx (Microsoft excel)
- .xls (Legacy excel)
- .csv (Comma-separated values)
How projects and phases work in the file
Each row in your spreadsheet represents either a project or a project with a phase. Here's how it works:
- If you only fill in project-level columns, the row creates a project.
- If you also fill in phase columns (Phase name, Phase status, etc.), the row creates a project with a phase.
- To add multiple phases to the same project, use multiple rows with the same project name. The importer will detect that they belong to the same project and create one project with multiple phases.
Example: To import a project called "Website Redesign" with two phases ("Design" and "Development"), create two rows. Both rows have "Website Redesign" as the project name, but different phase names.
Step 1 - Access the importer
- Go to Projects from the sidebar navigation
- Click the Import button (upload icon) in the top-right area of the projects list
- The Universal importer window will open
Step 2 - Upload your file
- Drag and drop your file into the upload area, or click Browse to select a file from your computer
- You can also download a template to see the expected format before preparing your data. The template includes example values to guide you
- Once uploaded, the importer reads your file and moves to the column mapping step
Step 3 - Map your columns
The importer will try to automatically match your spreadsheet columns to Factorial fields. Review each mapping and adjust if needed:
- Columns with a green checkmark have been matched automatically
- Columns with a warning icon need your attention — select the correct Factorial field from the dropdown
- You can skip columns that you don't want to import
Once all required fields are mapped, click Continue.
Step 4 - Review and fix errors
The importer validates your data and shows a spreadsheet-like review screen where you can:
- See all your rows with their mapped values
- Cells with errors are highlighted in red — hover over them to see what's wrong
- Edit values directly in the review screen to fix errors before importing
- Remove rows you don't want to import
Common validation errors include:
| Error | What it means |
|---|---|
| Required field missing | Project name, Status, Legal entity, or Budget type is empty. |
| Invalid date range | The due date is earlier than the start date. |
| Invalid email | The project owner email doesn't match the expected format. |
| Inconsistent project data | Two rows with the same project name have different values for project-level fields (e.g., different statuses). |
| Budget field not applicable | A budget field is filled in but doesn't apply to the selected budget type or scope. |
Fix any errors and click Continue when your data is clean.
Step 5 - Confirm and import
Review the import summary showing how many projects and phases will be created. Click Import to start the process.
The import runs in the background. You can:
- Close the window and continue working — the import will complete on its own
- Check the Import History to see the status of your import
Import history
You can review past imports from the Import history section:
- Go to Settings
- Access the Import history section
- Here you'll see all previous imports with their status (completed, in progress, or failed), the number of records imported, and any errors
Available fields reference
Below is the full list of fields you can include in your import file.
Project fields
| Field | Required | Description |
|---|---|---|
| Project name | Yes | The name of the project. Used to group rows belonging to the same project. |
| Project code | No | A short code or reference for the project. |
| Status | Yes | The project status. Accepted values: Active, Draft, Closed. |
| Start date | No | The project start date. |
| Due date | No | The project due date. Must be on or after the start date. |
| Description | No | A text description of the project. |
| Legal entity | Yes | The legal entity the project belongs to. Must match an existing legal entity in your Factorial account. |
| Project owner (email) | No | The email address of the employee who owns the project. Must match an existing employee's email. |
| Type of budget | Yes | The budget model. Accepted values: Time & Material, Fixed Price, No Budget. |
| Budget scope | No | Whether the budget is tracked at project level or delegated to phases. Accepted values: Project, Phases. |
| Estimated cost | No | The planned cost amount. Only applicable for Time & Material or Fixed Price budgets with Project scope. |
| Fixed cost | No | The fixed cost amount. Only applicable with Project scope. |
| Estimated hours | No | The planned hours for the project. Only applicable for Time & Material budgets with Project scope. |
| Billable | No | Whether the project is billable. Accepted values: true / false. Only applicable with Project scope. |
| Estimated client budget | No | The planned income from the client. Only applicable if the project is billable, for Time & Material or Fixed Price budgets. |
Phase fields
| Field | Required | Description |
|---|---|---|
| Phase name | No | The name of the phase to create under the project. |
| Phase code | No | A short code or reference for the phase. |
| Phase start date | No | The phase start date. |
| Phase due date | No | The phase due date. Must be on or after the phase start date. |
| Phase status | No | The phase status. Accepted values: Active, Draft, Closed. |
| Phase description | No | A text description of the phase. |
| Phase cost | No | The planned cost for the phase. Only applicable when budget scope is Phases. |
| Phase fixed cost | No | The fixed cost for the phase. Only applicable when budget scope is Phases. |
| Phase hours | No | The planned hours for the phase. Only applicable when budget scope is Phases. |
| Phase billable | No | Whether the phase is billable. Only applicable when budget scope is Phases. |
| Phase client budget | No | The planned client income for the phase. Only applicable when the phase is billable and budget scope is Phases. |
Tips and best practices
- Download the template first. It includes example data and all available columns, making it easier to prepare your file correctly.
- Keep project names consistent. When importing multiple phases for the same project, make sure the project name is identical across all rows (including capitalization and spaces).
- Project-level fields must be consistent. If two rows share the same project name, they must have the same values for all project-level fields (status, legal entity, budget type, etc.). Otherwise, you'll get a validation error.
- Use budget scope wisely. Set budget scope to "Phases" if you want to track budget at the phase level. Set it to "Project" (or leave it blank) to manage budget at the project level.
- Existing projects are matched by name. If a project with the same name already exists in your Factorial account, the importer will add phases to that project rather than creating a duplicate. However, new phases will not be added to projects that existed before the import process started.
- Phases are also deduplicated by name. Within the same import, if two rows have the same project name and the same phase name, only one phase will be created.
FAQ
-
Can I update existing projects with the importer?
The importer is designed for creating new projects and phases. If a project with the same name already exists, no changes will be made to it, but new phases can still be added.
-
What happens if my import fails partway through?
Each row is processed independently within a transaction. If a row fails, it won't affect the other rows. You can review which rows succeeded and which failed in the Import history.
-
Can I import projects without phases?
Yes. Simply leave all phase columns empty, and the importer will create projects without any phases.
-
Is there a row limit?
The importer handles files with hundreds of rows. For very large imports, consider splitting them into multiple files.
-
Can I undo an import?
Imported projects and phases cannot be automatically undone. You would need to delete them manually if needed.