How to Use MPXJ to Read and Convert Microsoft Project FilesMicrosoft Project files (MPP, MPT) and related formats (MPX, XML) are common in scheduling and portfolio management. MPXJ is an open-source library that lets developers read, write, and convert these project files across Java, .NET, and other environments. This article explains what MPXJ is, when to use it, how to set it up, and provides step‑by‑step examples for reading, manipulating, and converting Microsoft Project files. It also covers common pitfalls and tips for handling advanced data (calendars, baselines, resources, custom fields).
What is MPXJ?
MPXJ is an open-source library designed to parse and generate a variety of project management file formats, including:
- Microsoft Project MPP/MPT
- MPX (legacy project exchange format)
- Microsoft Project XML
- Primavera P6 (XER)
- Microsoft Project Server PSI (read-only) MPXJ exposes a consistent object model for tasks, resources, assignments, calendars, baselines, and custom fields which makes it easier to build integrations, converters, and analysis tools.
Key benefits
- Cross-platform: Java and .NET implementations.
- Format coverage: Supports multiple project formats.
- Stable object model: Single API for reading differing file formats.
- Open source: Community maintained with extensibility.
Getting started
Prerequisites
- Java 8+ for Java usage, or .NET (Core/.NET Framework) for .NET usage.
- Build tool: Maven/Gradle (Java) or NuGet (for .NET).
- A sample Microsoft Project file (MPP or XML).
Installing MPXJ
Java (Maven):
<dependency> <groupId>net.sf.mpxj</groupId> <artifactId>mpxj</artifactId> <version>8.1.2</version> </dependency> Java (Gradle):
implementation 'net.sf.mpxj:mpxj:8.1.2' .NET (NuGet): Use the MPXJ .NET package (package names may vary — search NuGet for “MPXJ”).
Note: Check the MPXJ project page or Maven Central for the most recent version.
Reading a Microsoft Project file (Java example)
This example demonstrates reading an MPP file, iterating tasks and resources, and printing some basic details.
import net.sf.mpxj.ProjectFile; import net.sf.mpxj.Task; import net.sf.mpxj.Resource; import net.sf.mpxj.reader.UniversalProjectReader; import java.io.File; public class ReadMppExample { public static void main(String[] args) throws Exception { File file = new File("example.mpp"); UniversalProjectReader reader = new UniversalProjectReader(); ProjectFile project = reader.read(file); System.out.println("Project: " + project.getProjectName()); System.out.println("Tasks:"); for (Task task : project.getAllTasks()) { if (task == null) continue; // MPXJ uses nulls for the blank row System.out.printf("ID: %d, Name: %s, Start: %s, Finish: %s%n", task.getID(), task.getName(), task.getStart(), task.getFinish()); } System.out.println("Resources:"); for (Resource res : project.getAllResources()) { System.out.printf("ID: %d, Name: %s%n", res.getID(), res.getName()); } } } Notes:
- UniversalProjectReader detects file format automatically.
- MPXJ may return null entries in task list (represents blank rows), so check for null.
Reading a Microsoft Project file (.NET example, C#)
using System; using net.sf.mpxj; using net.sf.mpxj.reader; class Program { static void Main() { var reader = new UniversalProjectReader(); ProjectFile project = reader.read("example.mpp"); Console.WriteLine("Project: " + project.getProjectName()); Console.WriteLine("Tasks:"); foreach (var task in project.getAllTasks()) { if (task == null) continue; Console.WriteLine($"ID: {task.getID()}, Name: {task.getName()}, Start: {task.getStart()}, Finish: {task.getFinish()}"); } } } Converting between formats
A common use case is converting MPP to Project XML (or vice versa), or to other formats like MPX or XER. MPXJ can read one format and write another.
Java example: convert MPP to XML
import net.sf.mpxj.ProjectFile; import net.sf.mpxj.reader.UniversalProjectReader; import net.sf.mpxj.writer.ProjectWriter; import net.sf.mpxj.writer.ProjectWriterUtility; import net.sf.mpxj.writer.ProjectWriterFactory; import java.io.File; public class ConvertMppToXml { public static void main(String[] args) throws Exception { File inFile = new File("input.mpp"); File outFile = new File("output.xml"); UniversalProjectReader reader = new UniversalProjectReader(); ProjectFile project = reader.read(inFile); ProjectWriter writer = ProjectWriterFactory.getProjectWriter(ProjectWriterUtility.ProjectFileType.XML); writer.write(project, outFile); } } Note: Writer factory and APIs may differ slightly by MPXJ version. If no direct factory, ProjectWriterUtility provides helpers.
Handling calendars, baselines, and custom fields
MPXJ exposes objects for calendars, baselines, and custom fields.
- Calendars: project.getCalendars() returns calendar objects with working time exceptions and day patterns.
- Baselines: Task.getBaseline(BaselineType.BASELINE) or iterating task.getBaselines() depending on version.
- Custom fields: ProjectFile.getCustomFields() and Task.getValues() for custom data; custom field mapping depends on source format.
Example: reading task baseline dates (Java)
import net.sf.mpxj.*; for (Task task : project.getAllTasks()) { if (task == null) continue; Baseline baseline = task.getBaseline(BaselineType.BASELINE); if (baseline != null) { System.out.println("Task " + task.getID() + " baseline start: " + baseline.getStart()); } } Common pitfalls and tips
- Version differences: MPXJ’s support for newer MPP versions may lag behind Microsoft’s latest format. Test with your MPP files.
- Null entries: getAllTasks() can contain nulls — guard against them.
- Date/time zones: MPXJ reads date/times as stored; be careful with time zone conversions when writing.
- Custom fields mapping: Different formats store custom fields differently; verify field IDs and names after conversion.
- Large files: For very large projects, monitor memory usage. MPXJ holds the entire ProjectFile in memory.
- File protection/passwords: MPXJ doesn’t support opening password-protected MPP files.
Advanced example: modify tasks and save
This example shows updating task names and saving back to MPP (or another format). Note: writing to native MPP can be limited; writing to XML is most reliable.
ProjectFile project = reader.read("input.mpp"); for (Task task : project.getAllTasks()) { if (task == null) continue; if (task.getName() != null && task.getName().startsWith("Old")) { task.setName(task.getName().replace("Old", "New")); } } ProjectWriter writer = ProjectWriterFactory.getProjectWriter(ProjectWriterUtility.ProjectFileType.XML); writer.write(project, new File("modified.xml")); When not to use MPXJ
- If you need to edit complex MPP-specific features not represented in the Project XML schema or MPXJ model.
- If you require editing password-protected files.
- If you need Microsoft’s exact proprietary MPP writeback behavior (MPXJ’s MPP writing support is limited).
Resources and further reading
- MPXJ GitHub: source code, issue tracker, and examples.
- MPXJ Javadoc / API docs for version-specific details.
- Community examples: blog posts and Stack Overflow for integration examples.
Summary
MPXJ is a practical, cross-platform library for reading, analyzing, and converting Microsoft Project files. Use the UniversalProjectReader to read files, the ProjectWriter to export to different formats, and the MPXJ object model to inspect tasks, resources, calendars, and custom fields. Test conversions for complex projects and watch for format/version limitations.
Leave a Reply