SharePoint Data Sources

With the implementation of Microsoft's move to Modern Authentication, using the Microsoft identity platform, logging into cloud-based versions of SharePoint is no longer possible by simply using a user name and password. Legacy installations that user older versions of SharePoint may still do so, but SharePoint has largely implemented an OAuth-based authentication scheme, with additional security provided by the use of encryption certificates.

In Process Director v5.44.1000, Modern Authentication for SharePoint was implemented using the SharePoint OAuth Datasource, which only gives access to SharePoint at the Tenant (organizational) level.

For Process Director v5.44.1103, The SharePoint OAuth Datasource was renamed to SharePoint OAuth (Tenant), while a new Datasource SharePoint OAuth (Site), was added to give access to SharePoint at the Site level, rather than at the entire tenant.

The existing SharePoint Datasource, which uses the simple username/password authentication scheme, is still available for customers who are using older versions of SharePoint. This legacy authentication method should be relevant to only a very small minority of customers, and has been renamed to SharePoint Legacy.

Important This update to the SharePoint Datasources will require updating the SharePoint Custom Tasks!

Configuring a SharePoint OAuth (Tenant) Datasource #

Note A PDF file for end-to-end Azure OAuth configuration can be found here: Configuring Azure OAuth (PDF Download)

Modern Authentication provides much more secure access to SharePoint, but does require a more complex setup process. To set up Modern Authentication between SharePoint and Process Director, you must first create and register an Azure Active Directory (AAD) application. The System Administrator's Guide has instructions for creating the AAD application in the Configuring Azure for Process Director Integration topic.

Once you've created the AAD Application, you can begin the process for configuring SharePoint Online.

Configure SharePoint Online permissions #

To configure the AAD application to use SharePoint with Process Director, you'll need to perform the following configuration steps:

  1. If you have access to multiple tenants, use the Directories + subscriptions filter in the top menu to switch to the tenant in which you want to register the application.
  2. Search for and select Azure Active Directory.
  3. Under Manage, select App registrations, then select your Process Director application In this example, we'll use “Test SharePoint OAuth” as the AAD Application name, though, of course, the name you use may vary.
  4. Click API permissions.
  5. Click Add a permission and add all permissions displayed below to the SharePoint section of the API Permissions area:

Create the SharePoint OAuth (Tenant) Datasource #

Now that the application has been fully registered in Azure, and the appropriate SharePoint API permissions have been set, you can create the SharePoint OAuth Datasource in Process Director. Be sure to keep the Azure window open, however, as you'll need to transfer some information from Azure to configure the SharePoint OAuth Datasource. Ensure you've opened the Azure Active Directory admin center window to the Overview tab of the App registrations page of your Process Director integration app. In this example, we'll use the "Test SharePoint OAuth" application we used in the steps above.

  1. Navigate to the Process Director folder in which you want to store the new Datasource, then select Data Source from the Create New menu.
  2. In the Create New Data Source screen, enter an Name for the Datasource, then click the OK button to create the Datasource and open its configuration screen.
  3. On the Properties tab of the Datasource definition, change the DataSource Type to "SharePoint OAuth (Tenant)".
  4. Set the SharePoint Site URL to the URL your SharePoint Online server.
  5. To set the Client ID property, go to the Azure window, and using the "Copy to Clipboard" icon, copy the value in the Application (client) ID property, then paste it into the Client ID Property of the Datasource definition.
  6. Similarly, you'll need to copy the value of the Directory (tenant) ID property in Azure to the Tenant ID property of the Datasource definition.
  7. To set the certificate to use for this Datasource, click the Browse button for the SharePoint Certificate File property, then locate and select the PrivatePublicKeys.pfx file you created earlier (either with certreq.exe or PowerShell).
  8. Enter the certificate Password that you created for the PrivatePublicKeys.pfx file.
  9. Click the OK button to save your changes, then update the Datasource definition by selecting Update from the OK dropdown menu at the upper right corner of the page.
  10. Click the Test Connection button to ensure that the Datasource can connect properly to SharePoint.

SharePoint OAuth (Tenant) Datasource Properties

In addition to the standard Description property, setting the Datasource Type property to SharePoint OAuth enables configuration of the connection properties listed below.

The fully-qualified URL that connects to the SharePoint installation.

The value of the Application (client) ID property contained in the App Registration screen in Azure.

The value of the Directory (tenant) ID property contained in the App Registration screen in Azure.

A Content Picker than enables you to browse to and upload the certificate (.PFX) file to Azure.

The password that you configured for the certificate (.PFX) file when you created it.

Configuring the SharePoint OAuth (Site) Datasource #

Configuring the SharePoint OAuth (Site) Datasource is far less complex than configuring the tenant-level Datasource, and requires no certificate to be created or uploaded to Azure. To add Process Director as an application in your Azure Active Directory portal at the Site level, complete the steps below after signing into your Azure portal (portal.azure.com):

  1. Navigate to the site you want to configure access for in your tenant. This is typically of the form https://mytenant.sharepoint.com, replacing “mytenant” with the appropriate name.
  2. Adjust the URL to https://mytenant.sharepoint.com/_layouts/15/appregnew.aspx.
    1. Click the buttons to generate both a Client Id as well as a Client Secret.
    2. Select the Client Id value, copy the text and store the value somewhere safe to be used in later steps in this guide.
    3. Select the Client Secret value, copy the text and store the value somewhere safe to be used in later steps in this guide.
  3. Now you need to grant permissions to newly registered app (AKA principal). Navigate to
    https://mytenant-admin.sharepoint.com/_layouts/15/appinv.aspx.
    It’s important to note the addition of “-admin” to your site's normal name.
    1. Add your Client Id as App Id.
    2. Add the XML as shown, reproduced here to aid in copy and paste. Note, there are other, more restrictive options that can be considered listed in Table 1 at Microsoft's documentation topic, Add-in permissions in SharePoint. Be careful using other values as it may prevent Process Director from working correctly.
      <AppPermissionRequests AllowAppOnlyPolicy="true">
           <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
      </AppPermissionRequests>
    3. Set the Title to “Process Director”.
    4. Set App Domain to the fully qualified domain name of you Process Director deployment.
    5. Set the Redirect URL to the URL of your Process Director deployment.
  4. Click Create.
  5. Click Trust It in the follow-up prompt.

  1. In a Process Director Content List folder, select Data Source from the Create New menu.

  2. Supply a Name and click OK to open the new Datasource definition.

  3. Set the Datasource Type drop-down to "SharePoint OAuth (Site)".

  4. Add the SharePoint Site URL for your SharePoint Online installation.

  5. Add the Client ID (AKA Application Id) and Client Secret from SharePoint that you set aside in the steps for Configure SharePoint Site Permissions above.

  6. Click OK then select the Update item from the OK menu at the top right corner of the page to save the configuration.

  7. Click theTest Connection button to test your connection to the SharePoint site.

A successful test means that your Datasource is correctly configured and is connecting to the SharePoint site correctly.

Conclusion

Congratulations! Assuming that you've correctly followed the instructions above, you've now configured both SharePoint Online and Process Director. You can now use this Datasource and the SharePoint Custom Tasks in Process Director to integrate your SharePoint sites and data with Process Director.

Sharepoint Legacy Datasource #

For connections to pre-OAuth versions of SharePoint, the SharePoint Legacy datasource type enables you to create a datasource connection to the SharePoint server.

There are four properties to configure to create this datasource.

The Sharepoint Site URL property enables you to enter the fully qualified URL of the Sharepoint server to which you wish to connect.

The User ID must be the user ID for a valid SharePoint User, while the Password property will be the password for the specified user. The Domain property is the SharePoint domain that contains the specified user.

Once you've configured the datasource, you can click the Test Connection button and a message banner will appear, notifying you whether the connection was successful.

Other Datasource Types

To see more information about different Datasource Types and their configuration, please refer top the following topics: