Microsoft Project Server

Key Features and Benefits

• Improved visibility into the overall status of projects by allowing collaboration between the Development team and the project managers and PMO.
• Synchronizes artifacts across the lifecycle allowing free flow of information between Microsoft Project Server and other tools.
• Enables centralized planning and control Improved cross-tool reporting, removing the need for manual processes and spreadsheets.
• Implement a true Scaled Agile Framework® (SAFe®) strategy across your portfolio, program and team levels

Common Integration Patterns

• Associating Planning Items to Implementation Artifacts
• Providing Developers with Early Visibility into Requirements
• Aligning Testing Teams across Testing Tools
• Populating Requirements into PLM Tools

Demo Videos

Minimal User Permissions & Hub User

We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization. 

In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.

Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'

See instructions on how to create a custom user in Microsoft Project Server. 

List of minimal user permissions:

• Ensure the user has sufficient permissions to create and update Projects and Tasks in your integration
• Ensure the user is added to the Project

Connecting to the Microsoft Project Server Repository

Standard Authentication

Required Fields:

• Location/URL
  • Example Format: https://abc-msps999/PWA 
    • Note: PWA is the Project Web App site

• Server Time Zone

  • For versions earlier than 19.4: 

    • Format for time zone can be any of the following:

      • Abbreviation such as "PST"
      • A full name such as "America/Los_Angeles"
      • Custom ID such as "GMT-8:00"
• Username
  • Example Format: ORGANIZATION\gu-sharepoint
  • Note that certain configurations may require you to use the following format: user@domain.onmicrosoft.com
• Password

Optional Fields:

• Work Day Hours: This field indicates the number of hours in a standard task day.
• Work Week Hours: This field indicates the number of hours in a standard task work week.
• Deployment Type: This field represents the deployment type of the Microsoft Project Server instance; options include, None, Auto-detect, On Premise, and Online.
  • The None and Auto-Detect options automatically determine if the deployment is cloud-based or on-prem (i.e., Microsoft Project online or Microsoft Project Server).
  • The On Premise option represents an on-prem deployment (i.e., Microsoft Project Server).
  • The Online option represents a cloud-based deployment (i.e., Microsoft Project Online).
• Enable Legacy NTLM Authentication: If checked, NTLM authentication scheme support will be enabled when authenticating to the repository.
  • When unchecked, the NTLM authentication scheme support will be disabled and the connector will use basic authentication against the repository. See details here  for configuring IIS to support basic authentication.
  • Note: This field only applies to on-premise instances of Microsoft Project Server.
• Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
  • Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment. 
• Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Note: For Microsoft Project Online, the following authentication methods are supported: Cloud Identity, Synchronized Identity. Federated Identity is not supported.

Microsoft Azure Active Directory OAuth2 via Certificate (ROPC) Configuration 

This authentication method only works with Project Online and Azure Active directory.

See the steps below to set up the Azure Active Directory authentication method:

1. Register an application for Hub on Azure Active directory.

   1. 

2. Grant permissions to the application to allow Hub to access Project Online. These settings are found under API permissions > Add a permission > Microsoft APIs > SharePoint > Delegated Permissions.

   1. Grant the application the necessary permissions (e.g., ProjectWebApp.FullControl).

3. Generate a Public / Private X.509 certificate key pair according to your requirements.

   1. Note: You may need a Linux/Windows PC for this process.

4. Add the certificate for Hub to Azure with the following steps:

   1. Click Certificates & secrets in the left sidebar.

   2. Then, upload the public certificate to the Certificates section. 

      1. 

5. Generate a new JWT token.

   1. You can find additional information on the structure of the JWT token here and a tutorial on generating the JWT on Linux using Node here.

      1. Note: You may need a Linux/Windows PC for this process.

6. Save the token to use in Hub.

7. Fill in the Repository Connection fields in Hub as follows:

   • Username: The Hub user’s username

   • Password: The Hub user’s password

   • Token Location: This is the Directory (tenant) ID from the App Registration Overview section

     • Example Format: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

   • Client ID: This is the Application (client) ID from the App Registration Overview section

   • Scope: This is the base URL (i.e., the project URL without “/sites/pwa”)

     • Example Format: https://mycompany.msps.com/.default

   • Client Assertion: This is the entire encoded JWT token 

     1. 

Person Reconciliation

For Person Reconciliation, the following fields are available:

The ID can be found when viewing a resource:

Learn more about how to configure person reconciliation in Planview Hub here.

Full Scan

Due to third party API limitations, changes to the following fields may not trigger change detection or cause a synchronization immediately. To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:

• 'Remaining Work' Field

Learn more about how to configure change detection and full scan intervals in Planview Hub here. 

Query Language

To further refine artifacts in a collection, Hub offers query language support for a limited set of MSPS fields.

The following field types are supported:

Equal/Not Equal operator

• VWL

• String

• Long

  • (Not supported in 2013 on-prem versions)

• Double

• Boolean

• Custom String (see details below)
• Custom Single Select (see details below)

Before/After operator

• Dates

Note: The following field types are not supported: Duration, Notes, ID.

Custom fields must meet the following criteria:

• The custom field must be a String or Single Select field.

• The field name or value must not contain unicode and should only be standard ASCII.

• The field name should not contain any of the following symbols:

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

• The field name (with all whitespace removed) should not match any of the below "internally reserved" field names:

"ProjectId"
"TaskId"
"ParentTaskId"
"ParentTaskName"
"ProjectName"
"TaskActualCost"
"TaskActualDuration"
"TaskActualFinishDate"
"TaskActualFixedCost"
"TaskActualOvertimeCost"
"TaskActualOvertimeWork"
"TaskActualRegularCost"
"TaskActualRegularWork"
"TaskActualStartDate"
"TaskActualWork"
"TaskACWP"
"TaskBCWP"
"TaskBCWS"
"TaskBudgetCost"
"TaskBudgetWork"
"TaskClientUniqueId"
"TaskCost"
"TaskCostVariance"
"TaskCPI"
"TaskCreatedDate"
"TaskCreatedRevisionCounter"
"TaskCV"
"TaskCVP"
"TaskDeadline"
"TaskDeliverableFinishDate"
"TaskDeliverableStartDate"
"TaskDuration"
"TaskDurationIsEstimated"
"TaskDurationString"
"TaskDurationVariance"
"TaskEAC"
"TaskEarlyFinish"
"TaskEarlyStart"
"TaskFinishDate"
"TaskFinishDateString"
"TaskFinishVariance"
"TaskFixedCost"
"TaskFixedCostAssignmentId"
"TaskFreeSlack"
"TaskHyperLinkAddress"
"TaskHyperLinkFriendlyName"
"TaskHyperLinkSubAddress"
"TaskIgnoresResourceCalendar"
"TaskIndex"
"TaskIsActive"
"TaskIsCritical"
"TaskIsEffortDriven"
"TaskIsExternal"
"TaskIsManuallyScheduled"
"TaskIsMarked"
"TaskIsMilestone"
"TaskIsOverallocated"
"TaskIsProjectSummary"
"TaskIsRecurring"
"TaskIsSummary"
"TaskLateFinish"
"TaskLateStart"
"TaskLevelingDelay"
"TaskModifiedDate"
"TaskModifiedRevisionCounter"
"TaskName"
"TaskOutlineLevel"
"TaskOutlineNumber"
"TaskOvertimeCost"
"TaskOvertimeWork"
"TaskPercentCompleted"
"TaskPercentWorkCompleted"
"TaskPhysicalPercentCompleted"
"TaskPriority"
"TaskRegularCost"
"TaskRegularWork"
"TaskRemainingCost"
"TaskRemainingDuration"
"TaskRemainingOvertimeCost"
"TaskRemainingOvertimeWork"
"TaskRemainingRegularCost"
"TaskRemainingRegularWork"
"TaskRemainingWork"
"TaskResourcePlanWork"
"TaskSPI"
"TaskStartDate"
"TaskStartDateString"
"TaskStartVariance"
"TaskStatusManagerUID"
"TaskSV"
"TaskSVP"
"TaskTCPI"
"TaskTotalSlack"
"TaskVAC"
"TaskWBS"
"TaskWork"

Focus on the Business Problem

When aligning two very different tool environments, it is important to first define your core business problem, and to let that drive a holistic, sustainable solution.

Integrating Microsoft Project Server with an Agile tool requires that you work with two tools that communicate with one another in inefficient ways, as their processes have until now been designed in separation. Designing an efficient integration solution will only be successful if you focus on the business problem first. This will enable you to create a holistic solution, rather than a piecemeal approach driven by individual field-to-field mappings.

For example, when planning out your integration solution, don’t try to map the ‘Actual Start’ field in Microsoft to some field on the Agile side which may not even exist. Instead, think about your business problem. If you need to know when work began on an item, perhaps the crucial information in the Agile tool to focus on is the date/time the artifact moved to ‘in progress’ state.

Below, we have outlined some very specific areas that can prove to be challenging when integrating MS Project Server with an Agile endpoint like Jira, VersionOne, Azure DevOps (formerly Microsoft TFS/VSTS), and more.

Microsoft Project Server API Limitations

With the 2016 release of Microsoft Project Server, Microsoft released some API limitations that impact integration and are worth considering for integration use cases.  

These limitations affect Microsoft Project Server 2016 and later, and Project Online:

• Custom fields cannot flow into MSPS; they can only flow out of MSPS
  • This also includes the stock/placeholder custom fields that are provided in MSPS (i.e. 'text10' field, which users can relabel as a custom field of their choice).  Those fields can only flow out of MSPS.

• Parent fields cannot be updated - they can only be set on creation (this limitation applies to all versions of MSPS).

The recommendations below take these limitations into consideration.

Use Proper Hierarchy Delineations

Within Microsoft Project Server, all items are of the same type: Tasks. However, Agile tools contain artifacts of different types such as Epics, Stories, and Defects, which relate to one another via different relationship hierarchies. As a result, it is important to find a reliable way to delineate between different artifact types in Microsoft Project Server.

Here are some best practices to consider:

Allow the original creation of each artifact type on one side only.

For example, high level epics are created only on the Microsoft Project Server side as part of a project plan. Lower level items like Features and Stories can only be broken down in the Agile tool.

Thus, the integration flow will be:

• • Epics: MSPS → Agile

  • Features: MSPS ← Agile

  • Stories: MSPS ← Agile

If different artifact types must be created in Microsoft Project Server, choose a reliable method to delineate between them.  

Using the outline level or order in the hierarchy within MSPS to delineate between different artifact types is an unreliable option, as hierarchies can change and tasks can be moved around the project plan. If tasks do not move around the project plan after the plan has been published, you may consider this option.

A more reliable option would be to take advantage of a custom field to delineate between the different artifact types. For example, create a custom field in MSPS that specifies if a task is a feature or a story in the other tool.

Use Concatenation to Work with Microsoft’s Custom Field API Limitation

Given that Microsoft’s API prevents Hub from writing data to custom fields in MSPS 2016+ or Project Online, we’d like to provide some best practices for satisfying your use case if it is necessary for you to have some additional information flow back into MSPS.

The first question to consider is, “what is the most important information for the PMO office to see back in MSPS?” Given that Microsoft’s API only allows Hub to write to default/out-of-the-box fields, one best practice is to take advantage of the Summary/Name field and to concatenate some necessary information into via your integration, using an extension.

For example, let’s say there are two important pieces to flow to MSPS from your Agile tool:

1. Dev Status
2. Dev ID

To accommodate this use case, your integration can append both fields to the title field in MSPS. 

Here is an example of a possible concatenation:

Remember, custom fields can be retrieved, thus one way integration of this value from MSPS → Agile tool is still feasible.

Status and Progress Updates

From an integration perspective, there tend to be two different types of updates back from the Agile world:

1. Status updates (i.e., New, In Progress, Complete)
2. Progress updates showing a calculation or depiction of the progress (i.e., Hours Complete or Percentage Complete).

If you are looking for a word to specify the status (Red/Yellow/Green or ToDo/InProgress/Done), then take advantage of the concatenation approach outlined above.

However, if you want to look into more detailed progress updates via integration, here are some considerations and best practices:

Roll-up Use Cases

In many cases, you may want your Agile tool to contain very granular, detailed information regarding implementation work, while Microsoft Project Server contains a high-level roll-up summary. When implementing this use case, keep in mind that the best place to perform these roll-ups is within the endpoint tool itself, and not within Hub.  

One reason not to have Hub perform the roll-up calculations is the following: let's say we had logic in Hub that took data from the child artifact in the source system and then flowed it to the parent artifact in the target system. If the data changed on the child artifact, Hub might not pick up those changes, since change detection is run on the artifacts within scope of the integration itself (meaning - on the parent artifacts, and not on the child artifacts). Since Hub only picks up changes occurring on the parent artifact, if your roll-up relies on data contained on a separate artifact (i.e., the child artifact), Hub could miss some vital updates.

Best Practices

• Use filters or views to hide low level items within MS Project Server project views.

• Use a third party tool to perform the calculation. For example, take advantage of Jira internal extensions, Azure DevOps (formerly TFS) extensions, or other third party extensions to loop through child items and calculate an aggregate % complete, which can then be assigned to the top-level artifact and integrated to Microsoft Project Server.

Calculated Fields

Most PMO tools have some calculation embedded within their tools. Meaning, some fields on Tasks are interrelated and are adjusted in conjunction with changes to other fields. For example, if you have “Work Completed” and “Work Remaining” fields in MSPS, the “Work Remaining” field will automatically be updated as you increase “Work Completed.” This adds some complexity to integration configuration, as care must be taken to determine which fields Hub will update and which will simply be auto-updated in the repository itself.

Let’s examine a few scenarios.

Resource Assignments

While MS Project Server breaks down tasks to be assigned to multiple resources, most Agile tools do not allow more than one assignee per task. This architectural mismatch presents some challenges when trying to align resource assignments between the two tools.

Here are some best practices and considerations:

• Make the Agile tool the system of record for assignments to ensure that only one person is assigned per task. This is the most reliable option

• Use a custom field on the Agile side to hold multiple assignees that have been assigned on the MS Project side. While Jira supports proper multi-user custom fields, Azure DevOps (formerly TFS) does not. Thus, if you are flowing assignments to Azure DevOps, it must be a one-way MSPS -> Agile mapping, or you must flow to a custom text field in Azure DevOps.

• Finally, you could use an extension to perform some logic on the assignment. For example, if there are multiple assignees on the MSPS side, you could configure an extension in your integration to only flow the first one to the Agile tool.

Special Features Supported

Supported Work Items