Table of Contents

Prerequisites

Before running the migration, the following must be in place. Each row links to the corresponding section below.

Step Details
1. Download software PowerShell, SharePoint Online Management Shell, Altus for Project, Azure CLI.
2. Create accounts Project Online and Altus accounts for data export and import.
3. Allocate licenses Allocate the required Microsoft and Altus licenses.
4. Install Altus for Project Install the Altus add-in for Microsoft Project.
5. Install PowerShell modules and Azure CLI Install PowerShell 7, Az, SharePoint Online Management Shell, PnP.PowerShell, and Azure CLI.
6. Activate resources Activate inactive bookable resources in Altus.
7. Create solution layers Create a solution layer for migration configuration.
8. Add configuration to a solution layer Lookup tables, choices, custom fields, security roles, and forms.
9. Grant consent to the Altus POL Migration SharePoint app Grant SharePoint API permissions in the customer tenant.
10. Clear cache in MS Project Avoid issues with cached schedules.
11. Remove punctuation from Project Online custom fields Workaround for a known Microsoft export issue.
12. Change macro settings in MS Project Prevent scripts from getting stuck on macro prompts.

1. Download software

The following software is free. You will need administrative rights to install (in an enterprise environment, work with your IT/SOE team).

Item Link
SharePoint Online Management Shell https://www.microsoft.com/en-au/download/details.aspx?id=35588
PowerShell 7.4 or higher https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.5
Altus for Project (add-in) https://project.altus.pro/AltusAddinSetup.msi
Azure CLI https://aka.ms/installazurecliwindows

2. Create accounts

Project Online account

The account being used to export data must satisfy one of:

  • Be a site collection admin on the PWA site, or
  • In Project permission mode: be assigned Manage Users and Groups and Access Project Server Reporting Service permissions, or
  • In SharePoint permission mode: be a SharePoint admin.

The account must also:

  • Have at minimum a Project P3 license.
  • Be a member of the Administrators security group.

Altus account

The account used to run the import scripts must have:

  • The Microsoft licenses described in the next section.
  • The following Altus security roles: Altus Admin User, System Administrator, Basic User.

3. Allocate licenses

Altus licensing

Each user requires the licenses described in the Altus Technical Readiness documentation.

Project Online licenses

The user running the scripts requires a Project Online and Project Desktop license (P3 or above).

How to check Microsoft licenses

  1. Sign in to https://office.com.
  2. Select the waffle icon > More apps.
  3. Select Install apps > Microsoft 365 apps.
  4. On the My Account page, select Subscriptions.
  5. Confirm the following are present: Power Apps Premium, Power BI Pro, Project P3, Project Online Desktop Client, Microsoft 365 E3.

Microsoft documents the assignment process at: https://learn.microsoft.com/en-us/microsoft-365/admin/manage/assign-licenses-to-users?view=o365-worldwide.

4. Install Altus for Project

Altus for Project is an add-in for Microsoft Project that exposes additional functionality directly inside MS Project for managing tasks in Altus.

  1. Open https://docs.altus.pro/index.html > Products.
  2. Open Altus for Project.
  3. Select Install via Microsoft Office (Recommended).
  4. Select Open when the dialog appears.
  5. Select Install in the Microsoft Office Customization Installer dialog.

When you next open MS Project, the Altus tab will be available.

5. Install PowerShell modules and Azure CLI

Install in the following order:

1. Install PowerShell 7

Download and run the MSI from https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.5. Confirm the version with $PSVersionTable.

2. Install Azure PowerShell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Install-Module -Name Az -Repository PSGallery -Force
Update-Module -Name Az -Force

Then, in PowerShell 7 as Administrator:

Install-Module -Name Az -RequiredVersion 11.1.0 -Scope AllUsers

Select Yes to All when prompted.

3. Install SharePoint Online Management Shell

Download and install from https://www.microsoft.com/en-au/download/details.aspx?id=35588.

4. Install PowerShell PnP

In PowerShell 7 as Administrator:

Install-Module PnP.PowerShell -Force

5. Install Azure CLI

Download from https://aka.ms/installazurecliwindows and run the installer.

6. Activate resources

Altus for Project prevents inactive resources from being added to schedules via Build Team. To avoid issues during the migration, activate all bookable resources.

  1. Open Altus > Resources.
  2. Open Resources then select the Inactive Bookable Resources view.
  3. Select all resources > Activate.
  4. Confirm.

7. Create solution layers

Altus stores configuration, code, and workflows in solution layers. The OOTB solution layers form the base layers. Customer-specific configuration belongs in a separate layer above the base.

Create a new solution layer to hold the migration configuration:

  • Project custom fields
  • Bookable Resource custom fields
  • Task custom fields
  • Lookup tables
  • List custom fields (Risks, Issues, custom registers)

Steps

  1. Open https://make.powerapps.com/.
  2. Select the environment where Altus is deployed.
  3. Open Solutions in the left-hand menu.
  4. Select New Solution.
  5. Select New Publisher and create a publisher with your prefix > Save.
  6. Save the new solution.
Note

The solution layer prefix used in the migration scripts (e.g. ce_) is the publisher prefix you set in this step.

8. Add configuration to a solution layer

There are six sub-steps:

  1. Create flat lookup tables
  2. Create hierarchical lookup tables
  3. Create choice sets
  4. Create custom fields
  5. Create a security role
  6. Add new fields to forms

1. Create flat lookup tables

Flat lookup tables require the following columns:

  • Name (Single line of text) – created by default.
  • Description (Multiple lines of text, plain text).

Steps:

  1. Open https://make.powerapps.com/.
  2. Open Solutions > your solution layer.
  3. Select New > Table > Table (advanced properties).
  4. Provide a Display Name and (optional) description > Save.
  5. Open Columns and add a Description column.
  6. Add the lookup table details to your field mapper spreadsheet.

To show the description in the lookup picker:

  1. Open the table > Views > Lookup View.
  2. Drag the Description field into the view > Save and publish.

2. Create hierarchical lookup tables

In addition to the flat lookup table steps:

  1. Add a Parent lookup column to the table.
  2. Open the table > Relationships > select the new self-referential relationship > Edit.
  3. Tick Hierarchical > Save.

Multi-select Project Online lookup tables

Dataverse does not support multi-select on lookup fields. To represent a multi-select Project Online lookup:

  1. Create a Dataverse table that stores the lookup values.
  2. Open the primary table (e.g. Project, Bookable Resource) > Relationships.
  3. Select + New Relationship > Many-to-many.
  4. Select the lookup-value table.
  5. Optionally surface the relationship on a form using a sub-grid.

The migration script can populate the lookup-value table and create associations using the multi-select script blocks documented in Migration Reference.

3. Create choice sets

  1. Open https://make.powerapps.com/.
  2. Open Solutions > your solution layer.
  3. Select New > More > Choice.
  4. Provide a name and add the labels (Dataverse will assign the values).
  5. Save.

4. Create custom fields

  1. Open https://make.powerapps.com/.
  2. Open Solutions > your solution layer.
  3. Select Add Existing > Table.
  4. Search for and select the table > Next.
  5. Select Include all objects and Include table metadata (recommended).
  6. Open the table > Edit.
  7. Select New Column and define the field (selecting the relevant lookup table where applicable) > Save.
  8. Repeat for all custom fields and tables.

5. Create a security role

  1. Open Solutions > your solution layer.

  2. New > Security > Security role.

  3. Provide a role name and business unit > Save.

  4. Search for the lookup tables you created and set permissions to:

    Permission Scope
    Create None
    Read Organization
    Write None
    Delete None
    Append Organization
    Append To Organization
    Assign None
    Share None

  5. Repeat for all lookup tables.

Note

For Admin users, set all permissions to Organization.

6. Add new fields to forms

Project form

  1. Open Solutions > your solution layer > Projects table > Forms.
  2. Open the Information main form.
  3. Set Show hidden = On.
  4. The three details tabs map to: Major and Minor / Operational / Agile. Select the relevant tab.
  5. Drop a 1-column section, rename it, then drag the new fields from Table columns.
  6. Save and publish.

Resource form

Same process as above, but on the Bookable Resources table.

Register forms

Same process for the Issue, Risk, and any custom register tables.

Task fields

Task fields are added via a view, not a form.

  1. Open Solutions > your solution layer > Project Tasks > Views.
  2. Select All Project Tasks.
  3. Drag fields onto the view > Save & Publish. The columns automatically appear in the Advanced tab of the Task Details form in Altus.

The migration requires permissions to an Enterprise/App application that grants the following SharePoint permissions:

Setting Value
API Name Office 365 SharePoint Online
Claim Value AllSites.Manage
Permission Read and write items and lists in all site collections
Type Delegated
Granted through Admin Consent
Granted by An administrator

You can either grant consent to the Altus-published application or create your own — see Altus POL Migration SharePoint App for both options.

10. Clear cache in MS Project

To avoid issues, clear the MS Project cache before running the migration.

  1. Open MS Project > File > Options.
  2. Open Save and click the cache location link.
  3. Remove all items in that folder.

11. Remove punctuation from Project Online custom fields

There is a known Microsoft issue: the export script will fail if any custom field name contains punctuation. Before running the export, remove the following characters from every Project, Resource, and Task custom field name:

`. , ; : ' " ! ? - _ ( ) [ ] / \ @ # $ % ^ & * + = < > ~ ``

Microsoft ticket reference: 2603040030007843.

12. Change macro settings in MS Project

To prevent the scripts from stalling on macro prompts:

  1. Open MS Project > Options > Trust Center > Trust Center Settings.
  2. Select Macro Settings > Enable all macros > OK.
Edit this page