Table of Contents

Back to CMS Configuration

!!! DRAFT !!!

Sharepoint Online

You are able to connect Stages with SharePoint Online. A typical URL to SharePoint Online looks like:

https://companyname.sharepoint.com/

Example Configuration

<cms-type name="sharepointonlinegraph">
    <!-- Global Properties -->
    <cms-host ident="sharepoint.online.ident" name="https://example.sharepoint.com" displayName="SharePoint Online Example">
        <!-- Host Properties -->
        <cms-property name="client.id" value="xxxx-xxxx-xxxx-xxxx-xxxx" />
        <cms-property name="client.secret" value="xxxxxx" />
        <cms-property name="tenant.id" value="xxxx-xxxx-xxxx-xxxx-xxxx" />
        <cms-property name="state.attribute.name" value="_Status" />
        <cms-property name="link.content.type.name" value="Link to a Document" />
    </cms-host>
</cms-type>

Host Properties

These configuration properties affect the behavior of one SharePoint Online server.

* Required
Properties marked with * are required for the adapter to work.

# Required but can also be set in web-application
Properties marked with # are required but can also be set in the File Management section in the Stages web-application as well. The value entered in the web-application overrides the one from the config.xml.

Required but with default
Properties marked with are required, but there is a default value. This values can be overridden by configuring it in the config.xml.

client.id *
client.secret *
tenant.id *
loginserver
state.attribute.name
document.content.type.name
<cms-property name="document.content.type.name" value="Document#MyDocument#RuleDocument" />
link.content.type.name
<cms-property name="link.content.type.name" value="Link to a document#My Link to a document#Rule Link to a document" />
use.system.account.for.download
sites.selected.scope (since Stages XXX)

Azure Portal

The integration uses Microsoft Graph API. To be able to use the API it is required to register and configure Stages as Azure App.

Authentication

Every application registered at the Microsoft azure portal can register Redirect URIs in the Authentication section of the applications registration page shown in the picture below.

For the authentication process to work, you have to add the following redirect for Web to the list: 

https://<stages-hostname>/stages/app/files/oauth_callback

Example

If the link to your Stages looks like this 

https://stages.example.com/stages/#/workspace/191/_vv/process/process/_h8ijENV8Enq3iqjRPK3spw

then your redirect URI is 

https://stages.example.com/stages/app/files/oauth_callback

API Permissions

In addition to the Redirect URIs, the application needs permissions for file handling. Up to Stages version XXX we had the option to use delegated Sites.ReadWrite.All permission. Because of backward compatibility this is the default behavior. With Stages version XXX we added the option to use application and delegated permission Sites.Selected. This is the recommended option. There is a in detail explanation in Microsoft documentation.

Default option: delegated permission Sites.ReadWrite.All

On this option Stages act in behalf of the user. The permissions are all of the type delegated:

In some cases an admin consent is required. This can be done by a Global Administrator, an Application Administrator, or a Cloud Application Administrator. More information in Azure documentation.

The picture below shows, how this should look like:

To active this option the setting sites.selected.scope has to be set to true in the xml host properties: 

<cms-property name="sites.selected.scope" value="true" />

On this option Stages acts with Azure application permission in case it performs action like fill caches. In case a user performs e.g. a file upload action the Azure delegated permission for this user will be used. The used permission is in both cases Sites.Selected.

The picture below shows, how this should look like:

For this option an admin consent is required. This can be done by a Global Administrator, an Application Administrator, or a Cloud Application Administrator. More information in Azure documentation.

In addition for the Sites.Selected permissions an Global Administrator have to select the specific SharePoint sites and give “write” access. This can be done via PnP PowerShell or Microsoft Graph PowerShell SDK.

PnP PowerShell

The PnP PowerShell offers a command to grant the permission. PnP PowerShell must be installed. The user must be an Azure administrator. In this example we're granting access for Stages app with client ID 11111111-1111-1111-1111-111111111111 to SharePoint Online Site https://example.sharepoint.com/sites/steering. 

Grant-PnPAzureADAppSitePermission -AppId "11111111-1111-1111-1111-111111111111" -DisplayName "Stages" -Permissions Write -Site "https://example.sharepoint.com/sites/steering"
Microsoft Graph PowerShell SDK

The Microsoft Graph PowerShell SDK must be installed. The user must be an Azure administrator. In this example we're granting access for Stages app with client ID 11111111-1111-1111-1111-111111111111 to SharePoint Online Site https://example.sharepoint.com/sites/steering.

Please notice that site https://example.sharepoint.com/sites/steering have to be separeted into example.sharepoint.com and /sites/steering and have to be combined again with : as separator: example.sharepoint.com:/sites/steering 

Import-Module Microsoft.Graph.Sites
 
# Connect PowerShell to Azure
Connect-MgGraph
 
# Find SiteId
$site = Get-MgSite -SiteId "example.sharepoint.com:/sites/steering"
 
# Write permission for Stages app
$params = @{
    roles               = @("write")
    grantedToIdentities = @(
        @{application = @{
                id          = "11111111-1111-1111-1111-111111111111"
                displayName = "Stages"
            } 
        }
    )
}
 
New-MgSitePermission -SiteId $site.id -BodyParameter $params
 
# Disconnect PowerShell from Azure
Disconnect-MgGraph

In this PowerShell script this two Microsoft Graph API endpoints are used:

Certificates & secrets

It is required to generate a client secret for Stages. It's recommended to choose expire never or a long duration. If the secret expires it must be changed in Stages and all users have to re-authenticate.

Repository Configuration

Access to SharePoint Online projects can be configured in Stages processes via “Management > File Management > Repositories”.

If you go to the document library with your browser you will get a URL like this. We will use it in this example. 

https://example.sharepoint.com/sites/steering/Shared Documents/Forms/AllItems.aspx
Name: The name of this SharePoint Online configuration. This name will be used by Stages to refer to this repository configuration (e.g. in repository plan)
Host: This selection field contains an entry for each cms-host section in the Stages configuration file (config.xml). You can select the host for this repository configuration.
Site: Define a site parameter for this repository configuration. The site is the path to the location, where your document libraries are located on the SharePoint server. The site is one piece for the complete connection string to the SharePoint server. > According to the example URL the site-part is sites/steering

This overwrites the path from the URL entered in the configuration file (config.xml).

Example:

Document Library: Defines the name of the document library. The document library is one piece for the complete connection string to the SharePoint server. If your document library contains a space it must be replaced by %20 > According to the example URL the Document Library part is Shared%20Documents
Root Folder: Defines a root folder inside the given document library. Every file linked or uploaded to a repository, which defines a root folder in the configuration, will be inside this root folder.
Default Lifecycle Select a lifecycle from the process metamodel as default for files from this repository.

Known Limitations

Behavior of Lock/Unlock

Currently, the graph API only supports checkin/checkout and no Undo-Checkout. So for every lock/unlock a new version of that file is created in sharepoint online.

Initial commit

Creates two versions (one for the creation of a new file/ second for updating the properties)

Set State

After setting the state of a Sharepoint Online document, the assignment to the Stages user gets lost. The modifier will be the Sharepoint Online user instead of the Stages user.

Major / Minor Version

The Graph API, wich is used by the SharePoint Online Adapter, does currently not support setting major/minor versions when uploading a file.

Action before authentication

If the current user is not authenticated yet and performs an action, the authentication dialog will be opened. After the authentication the user has to performs the action again.

Troubleshooting

Error AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application

Check the Redirect URI in Azure Portal

Unknown certificates

At the moment this public CAs are required:

Download DigiCert-Certificates

Download Microsoft-Certificate