Stages Documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
710:cms_sharepoint_online [2024/07/31 08:10] – [Known Limitations] Haupt, Manfred710:cms_sharepoint_online [2024/09/26 09:35] (current) – Policnik, Florian
Line 2: Line 2:
  
 ====== Sharepoint Online ====== ====== Sharepoint Online ======
- 
  
 You are able to connect Stages with SharePoint Online. A typical URL to SharePoint Online looks like: You are able to connect Stages with SharePoint Online. A typical URL to SharePoint Online looks like:
  
 ''%%https://companyname.sharepoint.com/%%'' ''%%https://companyname.sharepoint.com/%%''
- 
  
 ===== Example Configuration ===== ===== Example Configuration =====
Line 23: Line 21:
     </cms-host>     </cms-host>
 </cms-type> </cms-type>
- 
- 
 </code> </code>
  
Line 31: Line 27:
 These configuration properties affect the behavior of one SharePoint Online server. These configuration properties affect the behavior of one SharePoint Online server.
  
-*** ** ''Required'' \\ +*** ** ''Required'' \\  Properties marked with ** * ** are required for the adapter to work.
-Properties marked with ** * ** are required for the adapter to work.+
  
-**# ** ''Required but can also be set in web-application'' \\ +**# ** ''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.
-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'' \\ +''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.
-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.id ** * **
  
-   * Description: The client id of the stages application, which has to be registered at the Microsoft azure portal website.+  * Description: The client id of the stages application, which has to be registered at the Microsoft azure portal website.
   * Links: [[https://portal.azure.com|Microsoft Azure Portal]]   * Links: [[https://portal.azure.com|Microsoft Azure Portal]]
  
Line 57: Line 50:
 > loginserver > loginserver
  
-  * Default Value: <nowiki>https://login.microsoftonline.com/</nowiki>+  * Default Value: %%https://login.microsoftonline.com/%%
   * Description: The URL to the login server used for OAuth2 authentication. Stages appends /oauth2/v2.0/authorize , to authorize the access. For receiving tokens, /oauth2/v2.0/token will be appended to the login server address.   * Description: The URL to the login server used for OAuth2 authentication. Stages appends /oauth2/v2.0/authorize , to authorize the access. For receiving tokens, /oauth2/v2.0/token will be appended to the login server address.
   * Links: [[https://oauth.net/|More about OAuth]]   * Links: [[https://oauth.net/|More about OAuth]]
Line 69: Line 62:
   * Default Value: Document   * Default Value: Document
   * Description: Name of the **document**  content type. Sharepoint supports multiple content types but stages only supports the default type for documents.   * Description: Name of the **document**  content type. Sharepoint supports multiple content types but stages only supports the default type for documents.
-  * Since Stages 7.5.6.2, 7.6.2.4 and 7.7.0.0 it is possible to define multiple content types. Separate them with a #. For example: +  * Since Stages 7.5.6.2, 7.6.2.4 and 7.7.0.0 it is possible to define multiple content types. Separate them with a #. For example: 
 <code xml> <code xml>
 <cms-property name="document.content.type.name" value="Document#MyDocument#RuleDocument" /> <cms-property name="document.content.type.name" value="Document#MyDocument#RuleDocument" />
Line 80: Line 74:
   * Known Issue: Typo in Default Value. Has to be Link to a **D**ocument   * Known Issue: Typo in Default Value. Has to be Link to a **D**ocument
   * Since Stages 7.5.6.2, 7.6.2.4 and 7.7.0.0 it is possible to define multiple link types. Separate them with a #. For example:   * Since Stages 7.5.6.2, 7.6.2.4 and 7.7.0.0 it is possible to define multiple link types. Separate them with a #. For example:
 +
 <code xml> <code xml>
 <cms-property name="link.content.type.name" value="Link to a document#My Link to a document#Rule Link to a document" /> <cms-property name="link.content.type.name" value="Link to a document#My Link to a document#Rule Link to a document" />
Line 93: Line 88:
   * Default Value: false   * Default Value: false
   * Description: When set to true, Stages uses application permission Sites.Selected for system user and Sites.Selected delegated permission for Stages user. Please refer chapter "Application and delegated permission Sites.Selected" for detailed explanation.   * Description: When set to true, Stages uses application permission Sites.Selected for system user and Sites.Selected delegated permission for Stages user. Please refer chapter "Application and delegated permission Sites.Selected" for detailed explanation.
 +
 +==== Proxy configuration (since Stages 7.10.10.0) ====
 +
 +Stages can communicate with SharePoint Online through a proxy. Fill in the ''proxy.scheme'', ''proxy.hostname'' and ''proxy.port'' host properties to use a proxy. Otherwise no proxy is used.
 +
 +> proxy.scheme
 +
 +  * Default value empty (no proxy)
 +  * Possible values: http, https
 +  * Description: The type of proxy to use.
 +
 +> proxy.hostname
 +
 +  * Default value empty (no proxy)
 +  * Example values: proxy.example.com or 10.1.2.3
 +  * Description: Which proxy host to use.
 +
 +> proxy.port
 +
 +  * Default value empty (no proxy)
 +  * Example values: 3128
 +  * Description: Which proxy port to use.
 +
 +> proxy.username
 +
 +  * Default value is empty (proxy doesn't require authentication).
 +  * Example values: username
 +  * Description: The username to use for authentication on the proxy.
 +
 +> proxy.password
 +
 +  * Default value is empty (proxy doesn't require authentication)
 +  * Example values: secretPassword
 +  * Description: The password to use for authentication on the proxy.
  
 ===== Azure Portal ===== ===== Azure Portal =====
Line 98: Line 127:
 The integration uses [[https://learn.microsoft.com/en-us/graph/overview|Microsoft Graph API]]. To be able to use the API it is required to [[https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application|register and configure Stages as Azure App]]. The integration uses [[https://learn.microsoft.com/en-us/graph/overview|Microsoft Graph API]]. To be able to use the API it is required to [[https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application|register and configure Stages as Azure App]].
  
-{{ :710:azure_overview.png?direct |}}+{{ :710:azure_overview.png?direct }}
  
   * Value of "Application (client) ID" is cms-property ''client.id''   * Value of "Application (client) ID" is cms-property ''client.id''
Line 109: Line 138:
 [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:azure_portal_redirect_urls.png|{{:cms:azure_portal_redirect_urls.png}}]] [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:azure_portal_redirect_urls.png|{{:cms:azure_portal_redirect_urls.png}}]]
  
-For the authentication process to work, you have to add the following redirect for **Web**  to the list:<code>+For the authentication process to work, you have to add the following redirect for **Web**  to the list:
  
 +<code ->
 https://<stages-hostname>/stages/app/files/oauth_callback https://<stages-hostname>/stages/app/files/oauth_callback
- 
 </code> </code>
  
Line 122: Line 151:
 If the link to your Stages looks like this If the link to your Stages looks like this
  
-<code>+<code ->
 https://stages.example.com/stages/#/workspace/191/_vv/process/process/_h8ijENV8Enq3iqjRPK3spw https://stages.example.com/stages/#/workspace/191/_vv/process/process/_h8ijENV8Enq3iqjRPK3spw
- 
 </code> </code>
  
 then your redirect URI is then your redirect URI is
  
-<code>+<code ->
 https://stages.example.com/stages/app/files/oauth_callback https://stages.example.com/stages/app/files/oauth_callback
- 
 </code> </code>
- 
  
 ==== API Permissions ==== ==== API Permissions ====
Line 147: Line 173:
   * Sites.ReadWrite.All (Microsoft Graph, type delegated)   * Sites.ReadWrite.All (Microsoft Graph, 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 [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent|Azure documentation]]. +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 [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent|Azure documentation]].
  
 The picture below shows, how this should look like: The picture below shows, how this should look like:
  
-{{ :cms:azure_permissions.png?direct |}} +{{ :cms:azure_permissions.png?direct }}
  
 === Recommended option: Application and delegated permission Sites.Selected (Since Stages 7.10.7.0) === === Recommended option: Application and delegated permission Sites.Selected (Since Stages 7.10.7.0) ===
Line 171: Line 196:
 The picture below shows, how this should look like: The picture below shows, how this should look like:
  
-{{ :710:azure_permissions_sites_selected.png?direct |}}+{{ :710:azure_permissions_sites_selected.png?direct }}
  
 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 [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent|Azure documentation]]. 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 [[https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent|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. 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 == == PnP PowerShell ==
  
-The PnP PowerShell offers a [[https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html|command]] to grant the permission. [[https://pnp.github.io/powershell/articles/installation.html|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 ''<nowiki>https://example.sharepoint.com/sites/steering</nowiki>''.+The PnP PowerShell offers a [[https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html|command]] to grant the permission. [[https://pnp.github.io/powershell/articles/installation.html|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%%''.
  
 <code powershell> <code powershell>
Line 188: Line 212:
 == Microsoft Graph PowerShell SDK == == Microsoft Graph PowerShell SDK ==
  
-The [[https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation?view=graph-powershell-1.0|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 ''<nowiki>https://example.sharepoint.com/sites/steering</nowiki>''.+The [[https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation?view=graph-powershell-1.0|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 ''<nowiki>https://example.sharepoint.com/sites/steering</nowiki>'' have to be separeted into ''example.sharepoint.com'' and ''/sites/steering'' and have to be combined again with '':'' as separator: ''<nowiki>example.sharepoint.com:/sites/steering</nowiki>''+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%%''
  
 <code powershell> <code powershell>
Line 220: Line 244:
  
 In this PowerShell script this two Microsoft Graph API endpoints are used: In this PowerShell script this two Microsoft Graph API endpoints are used:
 +
   * [[https://learn.microsoft.com/en-us/graph/api/site-get?view=graph-rest-1.0&tabs=http#access-a-site-by-server-relative-url|Get a site resource]]   * [[https://learn.microsoft.com/en-us/graph/api/site-get?view=graph-rest-1.0&tabs=http#access-a-site-by-server-relative-url|Get a site resource]]
   * [[https://learn.microsoft.com/en-us/graph/api/site-post-permissions?view=graph-rest-1.0&tabs=http|Create permission]]   * [[https://learn.microsoft.com/en-us/graph/api/site-post-permissions?view=graph-rest-1.0&tabs=http|Create permission]]
Line 226: Line 251:
  
 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. 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.
- 
  
 [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:azure_certificates_secrets.png|{{:cms:azure_certificates_secrets.png}}]] [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:azure_certificates_secrets.png|{{:cms:azure_certificates_secrets.png}}]]
Line 232: Line 256:
 ===== Repository Configuration ===== ===== Repository Configuration =====
  
-Access to SharePoint Online projects can be configured in Stages processes via “Management > File Management > Repositories”. [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:spo-repository.png|{{  :cms:spo-repository.png  }}]]+Access to SharePoint Online projects can be configured in Stages processes via “Management > File Management > Repositories”. [[https://doc.stagesasaservice.com/lib/exe/detail.php?id=74:cms_sharepoint_online&media=cms:spo-repository.png|{{ :cms:spo-repository.png }}]]
  
-If you go to the document library with your browser you will get a URL like this. We will use it in this example.<code>+If you go to the document library with your browser you will get a URL like this. We will use it in this example.
  
 +<code ->
 https://example.sharepoint.com/sites/steering/Shared Documents/Forms/AllItems.aspx https://example.sharepoint.com/sites/steering/Shared Documents/Forms/AllItems.aspx
- 
 </code> </code>
  
Line 250: Line 274:
 Example: Example:
  
-  * **config.xml**: //<nowiki><cms-host name="https://example.sharepoint.com/sites/brake" /></nowiki>//+  * **config.xml**: //%%<cms-host name="https://example.sharepoint.com/sites/brake" />%%//
   * Value in **Site**: //sites/steering//   * Value in **Site**: //sites/steering//
-  * Resulting **URL**: //<nowiki>https://example.sharepoint.com/sites/steering</nowiki>//+  * Resulting **URL**: //%%https://example.sharepoint.com/sites/steering%%//
   * The path from the config.xml gets overwritten by the value from Repository Path.   * The path from the config.xml gets overwritten by the value from Repository Path.
  
Line 262: Line 286:
  
 ===== Known Limitations ===== ===== Known Limitations =====
- 
-  - Stages application technical limitation: Proxy network won’t work to SharePoint online, it will work to direct internet access. 
-  - We do not support the indirect route via a proxy. The SharePoint Online integration requires direct access to [[https://login.microsoftonline.com/]] and [[https://graph.microsoft.com]] 
- 
  
 ==== Behavior of Lock/Unlock ==== ==== Behavior of Lock/Unlock ====
Line 287: Line 307:
 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. 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.
  
 +==== Internet Access ====
 +
 +  - Stages application technical limitation: Proxy network won’t work to SharePoint online, it will work to direct internet access
 +  - We do not support the indirect route via a proxy. The SharePoint Online integration requires direct access to [[https://login.microsoftonline.com/]] and [[https://graph.microsoft.com]]
  
 ===== Troubleshooting ===== ===== Troubleshooting =====
Line 313: Line 337:
     * SHA1: DF:3C:24:F9:BF:D6:66:76:1B:26:80:73:FE:06:D1:CC:8D:4F:82:A4     * SHA1: DF:3C:24:F9:BF:D6:66:76:1B:26:80:73:FE:06:D1:CC:8D:4F:82:A4
     * SHA256: CB:3C:CB:B7:60:31:E5:E0:13:8F:8D:D3:9A:23:F9:DE:47:FF:C3:5E:43:C1:14:4C:EA:27:D4:6A:5A:B1:CB:5F     * SHA256: CB:3C:CB:B7:60:31:E5:E0:13:8F:8D:D3:9A:23:F9:DE:47:FF:C3:5E:43:C1:14:4C:EA:27:D4:6A:5A:B1:CB:5F
- 
  
 [[https://www.digicert.com/kb/digicert-root-certificates.htm|Download DigiCert-Certificates]] [[https://www.digicert.com/kb/digicert-root-certificates.htm|Download DigiCert-Certificates]]
  
 [[https://www.microsoft.com/pkiops/Docs/Repository.htm|Download Microsoft-Certificate]] [[https://www.microsoft.com/pkiops/Docs/Repository.htm|Download Microsoft-Certificate]]
 +
 +