How to migrate from Microsoft Project to OpenProject
Move Microsoft Project plans to self-hosted OpenProject: export XML or Excel, agree the mapping, import through the API, check every date and cut over.
In short
- OpenProject has no importer for Microsoft Project files: each plan leaves Project as XML or Excel and is written in through the OpenProject API, by its Excel synchronisation workbook or by a script.
- Tasks, summary tasks, milestones and finish-to-start links, lag included, map directly; other link types, several resources per task and task or resource calendars need a decision per plan.
- OpenProject has one set of working days for the whole instance, so it is set before the first import: changing it later reschedules work packages across every project.
- Baselines stay in Microsoft Project: OpenProject compares against its own history, which starts on the day of the import, and full baseline comparisons are an Enterprise add-on.
On this page (16)
Moving from Microsoft Project to OpenProject is an export and a rebuild through an API. OpenProject has no importer for Microsoft Project files, so each plan leaves Project as XML or Excel and is written into OpenProject through its API, either with the free Excel synchronisation workbook that OpenProject publishes or with a script that reads the XML. Tasks, summary tasks, milestones, dates and finish-to-start links map cleanly. Other link types, tasks with several resources, Project’s calendars and its baselines each need a decision, agreed with the planner who owns the plan. Deciding which plans are still live usually takes longer than the import. This guide covers the order we run it in, and how to check the dates.
Why teams move from Microsoft Project to OpenProject
Three reasons come up again and again.
- One plan the whole team works in. A Project file is updated by the planner who holds it. In OpenProject, everyone on the project opens the same plan in a browser, with Gantt charts, boards, time and costs.
- Project Online has closed. Microsoft retired Project Online on 30 September 2026, and its retirement announcement states that projects and their data are no longer accessible in the service after that date. Project desktop and Project Server are not affected.
- Plans on machines you choose. The OpenProject Community edition has no per-user fee and runs where you decide.
What you give up is a desktop scheduling engine. OpenProject schedules from one kind of link, counts durations in whole days and has one set of working days for the whole instance. Its own Gantt FAQ says it has no critical path feature yet. Resource management is an Enterprise add-on on the Premium plan, and the team planner and placeholder users are add-ons from the Basic plan. And someone has to run the server, which is the part Pilae takes on.
Step 1: list the live plans
Only some of the plans an organisation keeps are still being updated. Find those first.
- Collect the plans. The .mpp files on shares and laptops, the projects on Project Server, and any plans exported from Project Online before it closed. Premium plans in Microsoft Planner belong on the list too: Microsoft has retired Project for the web, and its plans now open in Planner.
- Sort them. A plan someone still updates is live and moves. A closed plan is archived as files, read-only, and is not imported.
- Name an owner for each live plan. The planner who maintains it agrees the mapping in step 3 and signs off the dates in step 6.
- Record what each live plan relies on. Link types other than finish-to-start; lags entered as elapsed time or as a percentage; tasks with several resources; date constraints such as Must Start On; task and resource calendars; the custom fields and outline codes in use; whether anyone still reports against a saved baseline; and whether time and costs are tracked in the plan.
That list is the real scope of the move: a plan with finish-to-start links, one resource per task and the standard calendar comes across quickly, and one built on start-to-start links and resource calendars needs its planner first.
Step 2: export each plan
Take two copies of every live plan: the archive, and the file the import reads.
XML, from Project desktop. Open the plan, choose File, Save As, Browse, and pick XML as the file type. Microsoft’s export instructions note that XML always covers the entire project and is mapped automatically, without the Export Wizard, and that empty fields are left out of the file. Project Server projects are opened in Project desktop and saved the same way. The XML is the complete record of a plan:
- Tasks with their unique ID, outline level, dates, duration, work, milestone and summary flags, notes and constraints.
- Links on each task, with their type (finish-to-start, start-to-start, finish-to-finish or start-to-finish) and their lag, held in tenths of a minute with a format that says whether it was entered in hours, days, elapsed time or as a percentage.
- Resources and assignments, with units and work.
- Calendars for the project, its resources and its tasks.
- Baselines and custom fields on each task.
Excel, from Project desktop. Save As with Excel Workbook as the type opens the Export Wizard. Build a task map with the fields the plan uses, or use Add All, and save the map to reuse it for every plan. This is the input for OpenProject’s Excel synchronisation in step 5.
Planner premium plans. Choose Export as Excel from the menu of the plan header. Microsoft lists the task title, description, bucket, status, start and due dates, assignments, priority and labels among the exported details. Dependencies are not on that list, so check the file and plan to recreate the links by hand.
Keep each original .mpp file, its XML and a PDF of its Gantt chart in the archive. They are what the planner compares against in step 6, and the only place the baselines survive.
Step 3: agree the mapping with each planner
The vocabulary is close. The scheduling rules are where plans differ.
| Microsoft Project | OpenProject | Note |
|---|---|---|
| Task | Work package | |
| Summary task | Parent work package | In automatic mode, its dates follow its children |
| Milestone | Work package of a milestone type | One date |
| Finish-to-start link and lag | Predecessor and successor, lag in working days | |
| Start-to-start, finish-to-finish | A lag on a predecessor link, or a relation that moves no dates | Agreed link by link |
| Duration | Duration, in days | Tasks under a day become one day |
| Work | Work | |
| Date constraint | Manual scheduling with the date set | |
| Resource | A user who is a member of the project | |
| Generic resource | Placeholder user, or a group | Placeholder users from the Enterprise Basic plan |
| Several resources on a task | One assignee, a group, or child work packages | Or a multi-select user custom field |
| Project calendar and holidays | Working days and non-working days | One set for the whole instance |
| Task or resource calendar | No equivalent | The Working days only switch, per work package |
| Custom field or outline code | Custom field | Hierarchy fields from the Enterprise Basic plan |
| Baseline | Not imported | Kept in the archive |
| Notes | Description |
Links and lag
The predecessor and successor relation is the only one in OpenProject that moves dates. In automatic scheduling, a successor starts one working day after its predecessor finishes, plus the lag in working days. For tasks that end at the close of a working day, that matches a finish-to-start link in Project. Related to, blocks, includes and requires move nothing.
Each lag is converted to whole working days: divide the XML value by ten for minutes, then by the minutes in the plan’s working day for days, and round. Elapsed and percentage lags become a number of working days the planner agrees. A lead, which Project stores as a negative lag, needs a test: OpenProject’s user guide allows a negative lag, while its API reference gives zero as the minimum.
Start-to-start, finish-to-finish and start-to-finish links have no counterpart. Each becomes either a predecessor link whose lag reproduces today’s dates, which drifts if the first task’s duration changes, or a plain relation, with the second task’s dates kept by hand. The planner chooses, link by link.
Resources
A work package has one assignee and one accountable person. A Project task with several resources becomes a task assigned to a group, a parent with one child work package per person, or one assignee with the others in a multi-select user custom field, which the Community edition supports. Generic resources become groups, or placeholder users, which need no email address or licence seat, on the Enterprise Basic plan. The team planner, which shows each person’s work over time, is on the same plan.
Calendars
Working days, the hours in a working day and non-working days such as public holidays are set once for the whole instance, under Administration, Calendar and dates. They cannot be set per project, and changing them reschedules work packages across every project and can notify everyone whose dates move, so they are set before the first import. A task that runs through weekends has the Working days only switch turned off in its date picker. Task and resource calendars have no equivalent.
Custom fields and baselines
Custom fields are created under Administration, Custom fields, added to each work package type’s form and switched on per project. The Community edition offers text, number, boolean, date, list, user, link and version fields; outline codes become list fields, or hierarchy fields on the Enterprise Basic plan. Add one field for each task’s Project unique ID: the import uses it to update rather than duplicate.
Baselines saved in Project are not imported. OpenProject’s baseline comparison reads its own history, which starts on the day of the import; the Community edition compares with the previous day only, and comparisons over any period are an Enterprise add-on from the Basic plan. If a planner still reports against an old baseline, carry its start and finish into two date custom fields.
Step 4: prepare the calendar, fields and people
- Set the working days and non-working days for the instance, as agreed in step 3.
- Create the types, including one flagged as a milestone, and the custom fields from the mapping, added to each type’s form.
- Create the people. Every resource that becomes an assignee needs an account and membership of the project, matched by email address. The Community edition signs people in with local accounts and two-factor authentication, or against your directory over LDAP. OpenID Connect and SAML, so that people sign in through Keycloak or Entra ID, are an Enterprise add-on from the Professional plan.
- Create an import account with an API token, from Account settings, Access tokens.
Step 5: import each plan into staging
Both routes write through the API, into a staging instance first, while teams keep working in Project.
Two ways to write a plan into OpenProject
Excel synchronisation
- A free macro workbook OpenProject publishes on GitHub
- Uploads the rows of the Excel export
- Hierarchy from indented subjects or a Parent column
- Relations by OpenProject ID, without lag
- Fits a plan that is a task list with a hierarchy
A script reading the XML
- Written against the API in any language
- Reads every task, link, assignment and custom field
- Converts each lag to working days
- Reruns safely using the Project unique ID field
- Fits plans with links, lags and milestones
With the Excel synchronisation
OpenProject’s Excel synchronisation is the route its own documentation gives for Microsoft Project. Download the OpenProjectExcel workbook from GitHub (its README calls it a community project, not officially supported, tested on Excel for Windows), enable macros, and enter the instance URL, the API token and the project identifier. Choose the column headers to synchronise, Update status, Lock Version, ID and Subject at least, paste the rows from the Project export, press Ctrl+B and choose Upload / update work packages. Custom fields must already exist in the project. Children are marked by four spaces before the subject, or by parent IDs in the Parent column. Relations go in a Relations column as follows 12345, naming OpenProject IDs that exist only after the first upload, so links are a second pass and carry no lag.
With a script reading the XML
For plans with links and lags, a script does the work in a fixed order, through OpenProject’s API.
- Create the work packages in outline order with
POST /api/v3/work_packages, a link to the project, andnotify=falseso the import does not email every assignee. Each one gets its type, subject, start and finish dates (one date for a milestone), work, description, assignee, custom field values including the Project unique ID, and a parent link to the work package created for its summary task. Send the start and finish dates and let OpenProject derive the duration, because the API refuses a start, finish and duration that disagree. Leave every work package in manual scheduling, the default, with Project’s dates. - Create the relations once every task exists, with
POST /api/v3/work_packages/{id}/relations: typefollows, the predecessor as thetolink and the lag in working days. Other link types follow the step 3 decisions. - Rerun safely. A second run looks each task up by its Project unique ID field and updates it instead of creating another.
- Switch to automatic scheduling where the planner wants links to drive dates: summary tasks, so their dates follow their children, and tasks with predecessors. A work package can be automatic only if it has predecessors or children, and switching can move its dates.
That last step is the test: the import copies Project’s dates, automatic scheduling makes OpenProject compute them, and any date that moves shows a link or a calendar that did not translate.
Step 6: check every date before anyone switches
Planners compare OpenProject with the archive from step 2, plan by plan.
- Compare milestones and summary tasks first: against the XML by script, or in the Milestones view of the Gantt charts module against the PDF.
- Explain each difference. The usual causes are a holiday missing from the non-working days, an elapsed or percentage lag, a start-to-start or finish-to-finish link, a task shorter than a day, a date constraint or a task calendar.
- Fix the cause, not the date. Correct the calendar, the relation or the mapping, then run the import again.
- Sign off. The planner confirms the staging plan in writing.
Nobody works in staging: the final import in step 7 writes production from the frozen files.
Step 7: cut over at a period boundary
Time and costs are booked against periods, so the switch happens at the start of one.
The cutover, in order
- Freeze: On the agreed date, live plans stop changing in Microsoft Project.
- Final import: Each frozen plan is exported again and imported into production.
- Check: Each planner checks the milestones once more.
- Book: Time and costs are booked in OpenProject from the start of the next period.
- Archive: The .mpp files, their XML and their PDFs stay readable as the record.
Actual work and costs booked in Project stay in the archive. Plans linked to each other, or sharing resources, move on the same date, because a link to another plan has nothing to point to until both have moved.
Running OpenProject in production
A production instance is more than the application container.
- PostgreSQL with the extensions OpenProject needs, holding work packages, their history, and time and cost entries.
- A background worker and memcached, for notifications, exports and caching.
- Attachments on a volume or an S3-compatible bucket, backed up on the same night as the database, with the secret key base beside them.
- An SMTP relay for notifications and invitations.
- Upgrades one major release at a time, because OpenProject migrates from one major release to the next and no further.
Pilae operates OpenProject this way, on your premises or on dedicated machines in Pilae Cloud, answering only on your private network. The database, the attachments and the secret key base go offsite daily, encrypted, in the country your contract names, and on Enterprise a restore test every month is recorded in the console. The Pilae Agent tests each upgrade on a copy of your data, waits for your approval and applies it in your window. Where you need an Enterprise add-on, we say which plan before the proposal, and the token is held in your name.
Let Pilae run the move
Pilae runs Microsoft Project to OpenProject migrations at a fixed price: the inventory of live plans, the mapping agreed with each planner, the calendar, fields and accounts, the staging imports, the date checks and the cutover. Then we operate OpenProject for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us how many plans you still update and we will scope it.
Questions
Can OpenProject open Microsoft Project files?
What happens to start-to-start and finish-to-finish links?
Do we need an OpenProject Enterprise plan?
Is OpenProject open source?
What about plans that were in Project Online?
How long does a Microsoft Project to OpenProject migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
