Project Dataverse Sync — User Guide
Overview
Project Dataverse Sync is a Microsoft Project add-in that synchronises project data (tasks, resources, assignments, dependencies, team members, baselines, and timephased rows) from an open MPP file into a Microsoft Dataverse environment. Configuration, field mappings, and publishing are all controlled through an embedded panel inside Microsoft Project.
Requirements
- Microsoft Project (desktop, .mpp file open)
- A licensed copy of the add-in
- An Azure AD / Microsoft 365 account with access to the target Dataverse environment
- Network access to the Dataverse organisation URL
Ribbon Tab
After installation, a Project Dataverse Sync tab appears in the Microsoft Project ribbon. It contains three groups:
Sync group
| Button | Description |
|---|---|
| Publish | Opens the publishing panel for the active project. The label changes to Publishing… while a sync is in progress. |
| Get Updates | Opens the Get Updates panel to pull changes from Dataverse back into the open MPP file. Disabled for Project Online / Project Server projects and when Synchronization Order is set to Publish Only. |
| Synchronize | Runs a combined publish + get-updates pass in the order configured under Mappings → Advanced Options → Synchronization Order. Disabled in the same scenarios as Get Updates. |
| Download MPP Clone | (Project Online / Project Server only) Saves a local, server-disconnected copy of the active project. Useful as a starting point for syncing the project into Dataverse. |
| Synchronize Lookup Tables | Opens the Sync Lookups panel to align lookup/option-set values between Project and Dataverse. |
| Build Project Team | Opens the Build Team panel to manage resource membership in Dataverse. |
Options group
| Button | Description |
|---|---|
| Mappings | Opens the Config panel where field mappings, the Dataverse environment, and the connected project are managed. |
| Options | Opens the Publish Options dialog (host mode, auto-close, WebView2 cache, diagnostic logging). See Publish Options dialog. |
Licensing group
Displays the current license status, add-in version, and a Manage License button.
First-Time Setup
1. Authenticate
Open the Mappings panel (Config). If you are not yet signed in, click Login. You will be prompted to authenticate with your Microsoft 365 account via the standard browser-based flow.
To switch accounts, click Change User or Logout and sign in again.
2. Select a Dataverse environment
After authentication, a dropdown lists all Dataverse environments your account can access. Select the environment you want to publish into. The add-in fetches the entity (table) definitions from that environment automatically.
3. Configure field mappings
Once an environment is selected, the Table Mappings section appears. Eight mapping tabs cover every syncable entity:
| Tab | What it maps |
|---|---|
| Project | Top-level project fields |
| Tasks | Task rows |
| Resources | Named resources |
| Team Members | Project team membership |
| Assignments | Task–resource assignments |
| Dependencies | Task predecessor/successor links |
| Baselines Data | Saved baseline snapshots (project, task, resource, and assignment levels — see Baselines) |
| Timephased Data | Period-based rows for tasks, assignments, and team members (see Timephased Data) |
For each tab, choose the Dataverse table that corresponds to that entity, then add field mappings pairing each Microsoft Project field with a Dataverse column. If no mappings exist when a table is first chosen, the add-in will attempt to auto-map fields by matching names.
Each field mapping supports value convertors (e.g., divide/multiply a numeric value, apply a formula, or map discrete values to a lookup).
Each field mapping also has a sync direction, controlling which side wins when the value differs:
| Direction | Meaning |
|---|---|
| ↑ Upload only | Project → Dataverse only. The field is never written back from Dataverse during Get Updates. |
| ↑↓ Both (Project wins conflicts) | Two-way sync; on conflict the Project value is kept. |
| ↓↑ Both (Dataverse wins conflicts) | Two-way sync; on conflict the Dataverse value is kept. |
| ↓ Download only | Dataverse → Project only. The field is never pushed during Publish. |
Download directions only take effect for fields whose convertor is reversible (most direct value convertors and lookup/reference convertors).
Mappings are saved automatically when the panel closes or you navigate away. You can also export them to a JSON file (Save mappings to file) or restore the Dataverse-default mappings (Load mappings from Dataverse Config).
Timephased grouping (advanced)
When the Timephased Data tab is active, a Grouping selector appears above the sub-tabs:
| Option | Behaviour |
|---|---|
| Daily | Splits timephased values by day. Highest detail, largest row count. |
| Weekly | Splits by week. Balanced detail and performance. |
| Monthly | Splits by month. Lowest detail, smallest row count. |
The selected grouping is saved in mapping options and applies to both publish and get-updates timephased processing.
Synchronization Order (advanced)
Under Advanced Options in the Mappings panel, the Synchronization Order dropdown controls what the Synchronize ribbon button does:
| Option | Behaviour |
|---|---|
| Publish Only | Synchronize runs Publish only. Get Updates and Synchronize ribbon buttons behave like Publish; the standalone Get Updates flow is disabled. |
| Publish, then Get Updates | Default. Pushes local changes first, then pulls any new changes from Dataverse. |
| Get Updates, then Publish | Pulls remote changes first, then pushes local changes. |
| Publish, then Get Updates, then Publish | Three-pass cycle, useful when Dataverse-side workflows generate fields the local plan should re-publish. |
| Get Updates, then Publish, then Get Updates | Three-pass cycle that begins and ends with a refresh from Dataverse. |
4. Connect to a Dataverse project record
From the Config panel, or when you first click Publish, you will be asked to select or create a Dataverse project record:
- Existing projects tab — search and select a record that already exists in Dataverse.
- New Project tab — enter a name and create a fresh record. The current MPP file name is pre-filled.
Once connected, the Config panel shows the linked record name with a direct link to it in Dataverse. Use Disconnect Project to unlink and choose a different record.
Publishing a Project
Click Publish in the ribbon to start synchronisation.
Publish steps
The panel shows each step in sequence with a progress indicator:
- Validation — checks that all required data is present.
- Loading Metadata — fetches extended Dataverse entity metadata.
- Publishing Project Info — writes top-level project fields.
- Publishing Resources — syncs resource records.
- Publishing Tasks — syncs task records.
- Publishing Dependencies — syncs task dependency links.
- Publishing Team Members — syncs team membership.
- Publishing Assignments — syncs task–resource assignment records.
- Publishing Baselines — syncs saved baseline snapshots (task, resource, and assignment baselines). Skipped silently if no baseline tables are mapped. See Baselines.
- Publishing Timephased Data — syncs mapped timephased rows.
- Finalizing — commits any remaining changes.
A step indicator at the bottom of the Project status bar shows current progress (e.g. Publishing: Publishing Tasks (step 5 of 11) — 42%).
Warnings
Non-fatal issues are collected during the publish run and displayed in a Warnings section. Each warning shows its priority (low / medium / high / critical) and the step during which it occurred.
Warnings are displayed in the Warnings list with their priority clearly labeled; expand a warning to see the full error detail.
Cancelling
While a publish is in progress, a Cancel button is available. Clicking it sends an abort signal; any records already written to Dataverse remain.
Auto-close on success
If Auto Close on Success is enabled in the Publish Options dialog, the panel closes automatically once the publish run completes without error.
Publish Options dialog
Open via Ribbon → Options. The dialog has four sections:
Publish host mode
Controls how the Publish, Synchronize, and Get Updates panels are displayed:
| Mode | Behaviour |
|---|---|
| Window (default) | Runs in a floating dialog window. |
| Task Pane | Runs in the Microsoft Project task pane (side panel). |
| Background | Runs with no visible UI; auto-close is forced on. |
Auto-close on success
When enabled, the panel closes automatically once a run completes without error. Always on in Background mode.
Cache
Shows the current size of the WebView2 user-data folder used by the embedded UI panels (%LOCALAPPDATA%\PDMS-Project-Addon\). Click Clear cache to delete it; the panels will rebuild their cache on next use.
Diagnostics
Enable diagnostic logging writes detailed trace logs and unhandled exceptions to %LOCALAPPDATA%\PDMS-Project-Addon\Logs\. Use Open log folder to browse the files. Leave logging off in normal use and turn it on only when reproducing an issue for support.
Getting Updates from Dataverse
Click Get Updates in the ribbon to pull changes made in Dataverse back into the open MPP file.
The panel runs through the following steps:
- Validation
- Loading Metadata
- Fetching Project
- Fetching Resources
- Fetching Tasks
- Fetching Assignments
- Fetching Timephased Data
- Applying Updates
For each mapped field with a download or both sync direction, the add-in compares three values: the current Project value, the current Dataverse value, and the last-synced baseline. Only fields that actually changed in Dataverse since the last sync are written back into Project; if both sides changed, the sync direction (Project wins / Dataverse wins) decides the winner.
Null / blank values in Dataverse are propagated as field clears in Project where the mapping allows it.
A status-bar indicator shows progress (e.g. Getting Updates: Fetching Tasks (step 5 of 8) — 64%). Warnings, cancellation, and auto-close work the same way as for Publish.
When Get Updates is unavailable: the button is disabled for projects connected to Project Online or Project Server (use Download MPP Clone first to create a local copy), and when Synchronization Order is set to Publish Only.
Synchronize (combined Publish + Get Updates)
Click Synchronize in the ribbon to run Publish and Get Updates back-to-back. The order and number of passes is controlled by Mappings → Advanced Options → Synchronization Order (see above).
Each pass is shown as its own panel in the Synchronize window, in sequence. If a pass is cancelled or fails, subsequent passes are not started.
Downloading an MPP Clone (Project Online / Project Server)
For projects opened from Project Online or Project Server, Get Updates and Synchronize are disabled because writing back into a server-published plan from this add-in is not supported. Use Download MPP Clone to save a local, server-disconnected copy of the active project. The cloned .mpp can then be opened and used with the full set of sync features (Publish, Get Updates, Synchronize).
Synchronizing Lookup Tables
Click Synchronize Lookup Tables in the ribbon to open the Sync Lookups panel.
This panel compares lookup-table and option-set values between Microsoft Project and Dataverse and presents them in three categories:
| Category | Meaning | Action |
|---|---|---|
| Download | Values in Dataverse that do not exist in Project | Tick the desired rows and click Synchronize to import them into Project |
| Upload | Values in Project that do not exist in Dataverse | Tick the desired rows and click Synchronize to create them in Dataverse |
| Rename | Values that exist in both but have different display names | Choose Rename to Dataverse or Rename to Project as needed |
Use the header checkboxes to select or deselect all rows in a category at once.
Baselines
Microsoft Project supports up to 11 saved baseline snapshots (Baseline and Baseline1 through Baseline10) at the project, task, resource, and assignment levels. Project Dataverse Sync can publish each of these to its own Dataverse table so that historical plan snapshots are preserved alongside the live project data.
Baseline publishing is fully optional — if no baseline tables are mapped in Config, the Publishing Baselines step runs silently and produces no warnings.
Configuring baseline mappings
In the Mappings panel, open the Baselines Data tab. It exposes four sub-tabs, one per baseline scope:
| Sub-tab | What it maps | Keyed by |
|---|---|---|
| Baseline | Project-level baseline snapshot (e.g. baseline name, baseline number, project baseline finish/cost) | Baseline number (0–10) |
| Tasks | Per-task baseline values (baseline start, finish, duration, work, cost, …) | Task + baseline number |
| Resources | Per-resource baseline values (baseline work, cost) | Resource + baseline number |
| Assignments | Per-assignment baseline values (baseline start, finish, work, cost, …) | Assignment + baseline number |
For each sub-tab, select the corresponding Dataverse table and add field mappings just as you would for any other entity. The add-in automatically maintains a Baseline reference column on the child rows (Task / Resource / Assignment baselines) pointing back to the matching project-level Baseline row.
You only need to map the baseline scopes you actually want to publish; the others can be left blank.
What gets published
During the Publishing Baselines step, the add-in writes one Dataverse row per (scope, baseline number) combination that contains data in the open MPP file. Rows where every mapped baseline field is empty are skipped.
Baselines are currently a publish-only feature: they are not read back during Get Updates.
Timephased Data
Use the Timephased Data tab in Mappings when you need period-based values (for example, date-bucketed task progress or assignment actual work).
Timephased sub-tabs
| Sub-tab | Scope | Direction support |
|---|---|---|
| Assignments | Assignment timephased rows | Upload and download (based on field direction) |
| Tasks | Task timephased rows | Upload and download (based on field direction) |
| Team Members | Team member (resource) timephased rows | Upload only |
How grouping affects sync
The Grouping selector controls how periods are bucketed while reading and writing timephased rows:
- Daily: highest granularity and row volume.
- Weekly: period rollup per week.
- Monthly: period rollup per month.
Choose a grouping that matches your Dataverse reporting needs and expected volume.
Publish and Get Updates behavior
- Publish includes a dedicated Publishing Timephased Data step.
- Get Updates includes Fetching Timephased Data and applies mapped task/assignment timephased updates for fields configured with download-capable directions.
- Team member timephased mappings are currently publish-only.
Building the Project Team
Click Build Project Team in the ribbon to open the Build Team panel.
The panel shows two columns side by side:
- Dataverse Resources — resources available in Dataverse (from the table mapped in the Resources tab of Config).
- Project Resources — resources currently in the MPP file.
Resources that were automatically matched between the two lists are highlighted.
Actions
| Action | How |
|---|---|
| Add | Select one or more Dataverse resources and click Add. They will be queued for addition to the MPP file. |
| Remove | Select one or more Project resources and click Remove. Existing MPP resources are queued for deletion; newly queued additions are simply de-queued. |
| Replace | Select exactly one Dataverse resource and one Project resource, then click Replace to substitute the Project resource with the Dataverse one. |
| Apply | Commits all queued additions, replacements, and deletions to the MPP file. |
Managing the License
Viewing license details
Click Manage License in the ribbon (Licensing group) to open the License panel. It shows:
- Whether the add-in is licensed
- Licensee name, company, and license type
- Expiration date (or "Never" for perpetual licenses)
- Trial status and remaining evaluation days (if on a trial)
Activating a license
Option 1 — Online activation (recommended): Click Manage License Online to open the licensing portal (app.pdms.io) in the add-in. Purchase or activate a license there; the portal will guide you through the process.
Option 2 — File activation: If you have received a license.pds file from your administrator or the vendor, click Load License From File and select the file.
Deactivating a license
A Deactivate License button is available when the add-in is fully licensed (hidden by default in the current release). Deactivating makes the add-in unlicensed.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Ribbon buttons are greyed out | No project is open, or the add-in is unlicensed | Open an MPP file; check license status |
| "Checking connection…" appears indefinitely | Authentication token could not be refreshed | Click Logout in Config, then Login again |
| Publishing stops at Validation with a project-not-found error | The connected Dataverse record was deleted | In Config, Disconnect Project and reconnect to a valid record |
| "Connected project was not found in Dataverse" warning in Config | The linked record ID no longer exists | Disconnect and re-select the correct project |
| No environments appear after login | Your account has no Dataverse environments, or discovery failed | Verify that your account has access to at least one Power Platform environment |
| Field mappings appear empty after selecting an environment | Entity metadata is still loading | Wait for the loading skeleton to clear, then check the Table Mappings section |