Setting up connectors

Creating a Primavera P6 Web Service connector

Modified on Tue, 17 Nov at 12:02 AM

TABLE OF CONTENTS

  1. Introduction
  2. At a glance
  3. What to ask your P6 administrator for
  4. Open the connector wizard
  5. Step 1: General
  6. Step 2: Components
  7. Step 3: Authentication
  8. Message encryption
  9. Step 4: Settings
  10. Step 5: Complete, test and persist
  11. Messages and what to do
  12. Questions and answers
  13. Related articles

Introduction

This article shows you, step by step, how to create a Primavera P6 Web Service connector. This connector lets SchedEx exchange schedules with Oracle Primavera P6 EPPM through P6's original interface, P6 EPPM Web Services.

Who can do this: a user with the Tenant Setup role in SchedEx.

You do not need to be technical. Most values come from your P6 administrator. Section 2 lists exactly what to ask them for.

Not sure this is the right connector? Read Primavera P6 connectors: overview first. It helps you choose between the Web Service and the REST API, and lists the P6 permissions SchedEx needs. Using the REST API? See Creating a Primavera P6 REST API connector.


1. At a glance

Creating the connector takes about ten minutes once you have the values from your P6 administrator.

  1. Ask your P6 administrator for the values in section 2.
  2. Fill in the five-step wizard in SchedEx (sections 3 to 8).
  3. Test and persist the connector in the SchedEx desktop client (section 9).

Checklist before you open the wizard:

  • I have the P6 Web Services address (Base URL). It usually ends in /p6ws/services.
  • I have a P6 user name and password, or we sign in to P6 with single sign-on.
  • I know whether transfers run on a person's PC (Desktop Client), on a server (Autonomous Component), or both.
  • I know whether our P6 server requires message encryption. If it does, I have the Key Vault values (section 7).
  • The P6 user has the permissions listed in the overview (section 5 there).

2. What to ask your P6 administrator for

Ask your P6 administrator or IT department for the items below. Tell them that SchedEx will use P6 EPPM Web Services, and whether it will connect from users' PCs (Desktop Client), from a server (Autonomous Component), or both.

Ask for Why SchedEx needs it Where it goes
The P6 Web Services address. It usually ends in /p6ws/services. So SchedEx can find your P6. Step 3: Base URL
A P6 user name and password for SchedEx, ideally a service account whose password does not expire. Or confirmation that federated (single sign-on) authentication is set up for P6 Web Services. So SchedEx can sign in to P6. Step 3: Authentication Method, Username, Password
Module access to P6 EPPM Web Services and the project permissions for that user. Share the overview (section 5) with them. So SchedEx can read, and if needed write, your projects. Set up in P6 by the administrator
Confirmation that P6 Web Services can be reached from users' PCs or the Autonomous Component's server. SchedEx connects to P6 directly from there. Network, set up by IT
The database instance number, if the P6 server has more than one database. So SchedEx uses the right P6 database. Step 4: Database Instance
Whether P6 Web Services require message encryption (message protection). Encrypted servers reject messages that are not encrypted. Step 3: Use encryption
Only if encryption is required: the Azure Key Vault address and the certificate name of the P6 encryption certificate in that vault. SchedEx encrypts messages with that certificate. Step 3: KeyVault URI, Certificate Name
Only if encryption is required, for the Desktop Client: the Tenant ID and Client ID of the Microsoft Entra ID app that may read the vault. Users sign in through this app to read the certificate. Step 3: Tenant ID, Client ID

How SchedEx keeps these values safe: the passwords, client secrets and tokens you enter in the wizard are encrypted with AES-256 before SchedEx saves the connector. The encryption key is kept in Azure Key Vault, separate from the database. Custom header values are not encrypted. Read more in Checking your connectors.


3. Open the connector wizard

  1. Select Setup in the top menu.
  2. On the Connector List card, select New Connector.

The Setup page with the New Connector button on the Connector List card The Setup page. New Connector is on the Connector List card.

The New Connector wizard opens on the right. It has five steps: General, Components, Authentication, Settings and Complete. Every field has an ⓘ icon. Point at it to see a short help text. Next stays grey until every required field on the step is filled in.


4. Step 1: General

Step 1 of the wizard with a connector name and the Primavera P6 Web Service card selected Step 1: give the connector a name and select Primavera P6 Web Service.

Field What to enter
Connector Name (required) A name that tells your colleagues which P6 this is, for example P6 Production (Web Service). The name is shown everywhere the connector is used, such as in Configs and Exchange Agreements.
Host System (required) Select Primavera P6 Web Service.
Import from existing (optional) Copies the settings of a connector you already have, so that you only change what is different.

Select Next.


5. Step 2: Components

An execution component is the SchedEx program that runs the transfer and talks to P6.

Step 2 with the Desktop Client and Autonomous Component options Step 2: choose which SchedEx program runs this connector.

Option What it means Choose it when
Desktop Client The SchedEx desktop program on a user's PC. Someone must be signed in to start a transfer. People start transfers by hand, or you want to sign in with single sign-on.
Autonomous Component A SchedEx service that runs on a server, without a person. Transfers must run automatically on a schedule.

You can select both. The connector then gets one sign-in profile for each component, and you fill in both in the next step. They can use different sign-in methods. For example, the Desktop Client can use single sign-on while the Autonomous Component uses a service account.

SchedEx connects to P6 directly from where the component runs: the user's PC or the Autonomous Component's server. P6 Web Services must be reachable from there.

Select Next.


6. Step 3: Authentication

If you selected both components in Step 2, you see two tabs: Desktop Client and Autonomous Component. Fill in both. The line at the bottom tells you when the other profile is still incomplete, and Switch to … takes you to it.

First choose the Authentication Method: how SchedEx proves to P6 who it is. The fields below the list change to match your choice.

Method You enter Desktop Client Autonomous Component
UserNameTokenProfile Base URL, user name and password Yes Yes
Federated Authentication Base URL only Yes No

Option A: UserNameTokenProfile (user name and password)

SchedEx sends a P6 user name and password with every request. This is the usual choice, because it works in both components.

Web Service authentication with UserNameTokenProfile selected UserNameTokenProfile: Base URL, Username and Password.

Field What it means Example
Base URL (required) The address of your P6 Web Services. It normally ends in /p6ws/services. Do not put a / at the end. https://p6.yourcompany.com/p6ws/services
Username (required) The P6 user that SchedEx signs in as. svc_schedex
Password (required) The password for that P6 user. SchedEx stores it encrypted.

Always use an address that starts with https://. The password travels with every request. With http:// it is sent unprotected over the network, even when message encryption is on.

Option B: Federated Authentication (single sign-on)

SchedEx signs in through your organization's identity provider, the same way you sign in to other company systems. You only enter the Base URL.

Web Service authentication with Federated Authentication selected Federated Authentication: only the Base URL is needed.

What happens each time the connector runs (a test, a persist or a transfer):

  1. SchedEx opens your web browser on the P6 sign-in page.
  2. You sign in with your company account. P6 then gives you a small sign-in file (an .xml file) to download. Save it somewhere you can find it, for example your Downloads folder.
  3. SchedEx opens a window called Select SAML Assertion File. Choose the file you just downloaded.
  4. SchedEx uses the file until that test, persist or transfer is finished.

Federated Authentication works only in the Desktop Client. It needs a person to sign in and pick a file. On the Autonomous Component, transfers fail with File picker is not available in autonomous client. For automatic transfers, use UserNameTokenProfile on the Autonomous Component tab.

The Message Encryption box

Below the sign-in fields you see a Message Encryption box. Leave Use encryption switched off unless your P6 server requires it. The next section explains how to find out.

Select Next when all required fields are filled in.


7. Message encryption

What it is, in plain words

Normally, the connection between SchedEx and P6 is protected by HTTPS, the same protection your web browser uses. Some organizations add a second layer for P6 Web Services: every message must also be encrypted with a special certificate (a digital key). This is called message encryption or message protection.

When your P6 server is set up this way, it rejects every message that is not encrypted. SchedEx must then encrypt its messages with the P6 server's certificate, and Use encryption must be switched on.

How do I know if encryption is required?

Use one of these three ways. The first one is the surest.

  1. Ask your P6 administrator. Ask: "Do our P6 Web Services require encrypted incoming messages (message protection)?" Your administrator can see this in the P6 Web Services security settings. These are often called Message Protection, with options such as Require Encryption. The exact names depend on your P6 version.
  2. Test without encryption. Create the connector with Use encryption switched off, then run the test (section 9). If the test says Connected, encryption is not required. You are done.
  3. Read the error. If the test fails with Test Failed: followed by a P6 message about security, a security header, a policy or encryption, your server most likely requires encryption. Switch it on and set it up as described below.

If you are unsure, start with encryption off. Switching it on when the server does not need it adds setup work for nothing. Switching it on later is easy: edit the connector, switch on Use encryption, fill in the fields and test again.

What your IT department must prepare

Message encryption needs some preparation by IT before you can fill in the fields. Share this list with them:

  1. The P6 encryption certificate in an Azure Key Vault. SchedEx encrypts messages with the P6 server's own encryption certificate: the one P6 Web Services use for message protection. It is not a separate certificate for SchedEx. IT uploads it to an Azure Key Vault and gives it a name.
  2. Access to the Key Vault. Whoever runs the connector must be allowed to read certificates and secrets in that vault (in Azure: get permission on certificates and secrets, or the Key Vault Certificate User role).
    • Desktop Client: IT registers an app in Microsoft Entra ID that users sign in through. The app needs http://localhost as a redirect address for desktop sign-in. Each user who runs the connector must be allowed to read the vault.
    • Autonomous Component: the component reads the vault with the Azure identity of the server it runs on, for example its managed identity. IT gives that identity read access to the vault. You do not enter a Tenant ID or Client ID for the Autonomous Component.
  3. HTTPS stays on. Message encryption protects the content of each message, but the user name and password travel in a part that is not encrypted. Keep using an https:// Base URL.
  4. Correct clock. Every encrypted message carries a time stamp that is valid for 10 minutes. The PC or server that runs SchedEx must have the correct time, or P6 may reject the messages.

Fill in the fields

Web Service authentication with Use encryption switched on Message Encryption switched on, with the Key Vault and app fields.

Field What it means Where to find it Example
Use encryption Switches message encryption on.
KeyVault URI (required when on) The address of the Azure Key Vault that holds the P6 certificate. Azure portal → your Key Vault → Overview → Vault URI https://yourcompany-vault.vault.azure.net/
Certificate Name (required when on) The name of the P6 certificate in that Key Vault. Azure portal → your Key Vault → Certificates p6-encryption-cert
Tenant ID (required when on, Desktop Client only) The ID of your organization in Microsoft Entra ID. Azure portal → Microsoft Entra ID → Overview xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Client ID (required when on, Desktop Client only) The ID of the Entra ID app users sign in through to read the vault. Azure portal → App registrations → your app → Overview xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

If you selected both components in Step 2, fill in the encryption fields on both tabs.

What you will notice when encryption is on

  • Desktop Client: the first time SchedEx needs the certificate after the desktop client starts, a Microsoft sign-in window opens. Sign in with your work account within two minutes. SchedEx then keeps the certificate until you close the desktop client.
  • When the certificate is replaced: after IT puts a new P6 certificate in the Key Vault, restart the desktop client and restart the Autonomous Component. They keep the old certificate until they restart.

When encryption does not work

What you see What it means What to do
Test Failed: followed by a P6 message about security, a policy or encryption, with encryption off Your P6 server requires encryption. Switch on Use encryption and fill in the fields.
The same kind of P6 message with encryption on P6 could not read the message, usually because the certificate in the Key Vault is not P6's current encryption certificate. Ask IT to check that the Key Vault holds the certificate P6 Web Services use now.
The authentication process was interrupted or timed out before completion… The Microsoft sign-in was not completed within two minutes, or the Key Vault could not be reached. Run the test again and sign in promptly. If it keeps happening, ask IT to check the network path to the Key Vault.
A message that a certificate was not found in this key vault The Certificate Name or KeyVault URI is wrong. Check both values against the Azure portal.
A message that you are not authorized or do not have get permission The signed-in user, or the Autonomous Component's server identity, may not read the vault. Ask IT to grant read access to certificates and secrets.
A message mentioning InteractiveBrowserCredential or User canceled authentication The Microsoft sign-in window was closed. Run the test again and complete the sign-in.
A message mentioning DefaultAzureCredential failed to retrieve a token Autonomous Component only. The server has no Azure identity that may read the vault. Ask IT to set up a managed identity (or other Azure identity) for the server and grant it access.

Key Vault errors appear in the desktop client as An unexpected error occurred while processing your request…. Read the text after Error message - to find the matching row above.


8. Step 4: Settings

All settings on this step are optional. The default values work for most P6 servers. Change them only when you have a reason to.

Settings step for a Web Service connector Step 4: optional settings. The defaults suit most P6 servers.

Setting What it means Default
Custom Headers Extra pieces of information that SchedEx sends with every request to P6. Only needed when your IT department has put a gateway in front of P6 that asks for them. Select Add to enter a name and a value. See Setting Custom Headers for a Connector. None
Read Batch Size How many activities SchedEx reads from P6 in one go. For schedules with more than 50,000 activities, a larger value such as 10000 is recommended. Lower it if P6 times out on large reads. 500
Write Batch Size How many items SchedEx creates, changes or deletes in P6 in one go when it receives data. Lower it if your P6 server rejects large requests or times out. 500
Include project level activity codes P6 has activity codes at global level and at project level. SchedEx always offers global codes for mapping. Switch this on to also offer project-level codes. Off
Database Instance Some P6 servers hold more than one database. This number tells P6 which one SchedEx should use. Most servers have one database, number 1. Ask your P6 administrator if you are unsure. 1

Select Create Connector to save.

Each connector needs its own address. Two connectors cannot use the same Base URL. SchedEx uses the connector to keep track of transferred activities over time, so it stops you from saving a duplicate.


9. Step 5: Complete, test and persist

The last step confirms that the connector is saved. Select View Connector to open it, or Close.

The connector cannot exchange data yet. Two things are left. Both run from the SchedEx desktop client on a PC that can reach P6:

  1. Test the connector. In the desktop client, open Connectors and select Test on the connector's row. SchedEx signs in to P6 and reads from it.
    • Connected means the address, the sign-in and the network all work.
    • Test Failed: followed by a message means something is wrong. See section 10.
    • With Federated Authentication, the browser and the Select SAML Assertion File window open during the test. With message encryption, a Microsoft sign-in window may open.
  2. Persist the connector. Select Persist on the same row. SchedEx reads the list of projects from P6 and how project codes, activity codes and user-defined fields are set up, so that you can select them in Configs. When it finishes you see Host System data stored successfully!

Persist reads every project the P6 user can see. On a large P6 database this can take a while.

If transfers run on the Autonomous Component

A test in the desktop client runs from your PC. It proves that your PC can reach P6, not that the server where the Autonomous Component runs can. To check the server:

  • Persist from the server. In the SchedEx web app, open Setup > Connectors, open the connector and select Persist Within 3 Minutes. The Autonomous Component picks up the request and reads from P6 itself.
  • Ask a Tenant Admin to check the dashboard. In Clients > Autonomous Component > Dashboard, the Connectors panel shows each connector's health and its latest persist. The connector should be Healthy and its persist Completed. If it is Unhealthy, point at the error icon to see why. See Reading the Autonomous Component Dashboard.

Check the connector later

In the web app, Setup > Connectors shows every connector's Status and Last Health Check. A connector that has not been checked for more than 7 days is marked as such: run Test again to refresh it. Test and persist again whenever the P6 address, password or projects change.

More about testing and persisting: Testing and Persisting a Connector.


10. Messages and what to do

For message encryption problems, see When encryption does not work.

While you fill in the wizard

Message What it means What to do
Api base url must be provided The Base URL is empty. Enter the address from your P6 administrator.
For UserNameTokenProfile authentication, username and password must be provided Username or Password is empty. Fill in both.
Next stays grey A required field is empty or not valid, or the other component's profile is incomplete. Look for fields marked in red, and check the line at the bottom of the Authentication step.

When you test, persist or transfer

Message What it means What to do
Test Failed: with a sign-in or authentication error P6 does not accept the user name or password. Check the credentials with your P6 administrator. Make sure the user has module access to P6 EPPM Web Services.
Test Failed: with a message that the server cannot be reached or found The PC or server cannot reach P6. Check the Base URL (it should end in /p6ws/services, without a / at the end). Check that the PC is on the company network or VPN, if P6 is only reachable there.
Test Failed: No XML file selected! Federated Authentication. The Select SAML Assertion File window was closed without choosing a file. Run the test again and choose the downloaded .xml file.
Test Failed: No valid XML file selected! Federated Authentication. The chosen file is not an .xml file. Choose the .xml sign-in file you downloaded from P6.
File picker is not available in autonomous client Federated Authentication is set on the Autonomous Component tab. Change the Autonomous Component tab to UserNameTokenProfile.
This connector is no longer available. Refresh the connector list and try again. The connector was deactivated, or it has no Desktop Client profile. Refresh the list. To test from the desktop client, make sure Desktop Client is selected in Step 2.
This connector test is already running or waiting to start. A test of this connector is already in progress. Wait for it to finish.
The project with ID … could not be found or read from the service… The P6 project does not exist, or the user cannot see it. Make sure the project exists in P6 and the user has access to it. See the overview.

11. Questions and answers

The P6 password changed. What do I do? Edit the connector in SchedEx, enter the new password on the Authentication step (on each tab that uses it) and save. Then run the test again. Nothing needs to change on users' PCs.

Can the Desktop Client and the Autonomous Component use different sign-ins? Yes. Each gets its own tab in Step 3.

Do we have to use message encryption? Only if your P6 server requires it. See How do I know if encryption is required?

Which database instance should I enter? Leave it at 1 unless your P6 administrator tells you otherwise.

Can I change the connector later? Yes. Open the connector and edit it. Run the test again after you change the address, the sign-in or the encryption settings.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article