Integrating Collaboration Hub with Microsoft SharePoint Online

Note

This section explains the Microsoft SharePoint Online integration with Windows Azure-based or certificate-based authentication. An overview over the different SharePoint integration variants is accessible at Microsoft SharePoint Integration.

In case you experience problems during the integration, please read Troubleshooting the Microsoft SharePoint integration.

To integrate Collaboration Hub with SharePoint Online, the following steps are necessary:

Configuring Microsoft Azure Active Directory

Note

Signavio currently only supports Microsoft Azure Cloud US. We do not support Microsoft Cloud Deutschland.

Important

Please configure your Active Directory service before you install the Collaboration Hub SharePoint App.

In case you want to setup certificate-based authentication, please skip this step and proceed at Downloading the Signavio Collaboration Hub SharePoint App.

The Signavio system needs to have read access to your Windows Azure Active Directory. Microsoft offers Cmdlets for the Microsoft PowerShell to configure external application rights to your Windows Azure Active Directory.

To configure the Microsoft Azure Active Directory, proceed as follows:

  1. Download the Windows Azure Active Directory Module for Windows PowerShell and follow the installation instructions on https://docs.microsoft.com/en-us/powershell/msonline/v1/azureactivedirectory.

  2. Open a PowerShell and import the MSOnline module:

    import-module MSOnline
    
    import-Module MSOnlineExtended -Force
    
  3. Login with your SharePoint Online administrator account:

    $msolcred = get-credential
    
    connect-msolservice -credential $msolcred
    
  4. Create a new service principal that represents the Signavio Process Editor application in your Windows Azure Active Directory. Ensure that SYMMETRIC_KEY is created as well as AppPrincipalId. The ObjectID is used in a later step.

    See also: http://technet.microsoft.com/en-us/library/dn194119.aspx

    New-MsolServicePrincipal -ServicePrincipalName @("{principal name/domain}")
    -AppPrincipalID "{A GUID}" - DisplayName "{Display Name}"
    -Type Symmetric -Usage Verify
    

    Example:

    New-MsolServicePrincipal -ServicePrincipalName @("editor/signavio.com")
    -AppPrincipalID "f592d4af-bf33-47c2-a010-94f2a323ab58"
    -DisplayName "Signavio Process Manager" -Type Symmetric -Usage Verify
    

    Output:

    The following symmetric key was created as one was not supplied {SYMMETRIC_KEY}
    
    DisplayName           : Signavio Process Manager
    ServicePrincipalNames : {editor/signavio.com, f592d4af-bf33-47c2-a010-94f2a323ab58}
    ObjectId              : ddadd653-bda2-4f1f-87d2-22a180563a34
    AppPrincipalId        : f592d4af-bf33-47c2-a010-94f2a323ab58
    TrustedForDelegation  : False
    AccountEnabled        : True
    Addresses             : {}
    KeyType               : Symmetric
    KeyId                 : b1b56bcc-63dc-4c80-8320-55bd3cd79a07
    StartDate             : 23.09.2013 16:58:19
    EndDate               : 23.09.2014 16:58:19
    Usage                 : Verify
    
  5. Apply the role Service Support Administrator to the service principal (has read access to the Windows Azure Active Directory):

    Add-MsolRoleMember -RoleName "Service Support Administrator"
    -RoleMemberObjectId {ObjectID} -RoleMemberType ServicePrincipal
    

    Example:

    Add-MsolRoleMember -RoleName "Service Support Administrator"
    -RoleMemberObjectId ddadd653-bda2-4f1f-87d2-22a180563a34
    -RoleMemberType ServicePrincipal
    
  6. Now get your Tenantd:

    #(get-msolcompanyinformation).objectId
    
TenantId, SymmetricKey, and AppPrincipalId are required for downloading the Signavio Collaboration Hub SharePoint App, see next chapter Downloading the Signavio Collaboration Hub SharePoint App.

Updating expired Azure Active Directory credentials

Important

The credentials for establishing the connection to Azure Active Directory expire after one year. In case you don’t update the credentials, searching for users in the ‘Manage read access’ dialog will not be possible.

To update the credentials, proceed as follows:

  1. Look up the credentials for your service principal:

    ..code-block: none

    Get-MsolServicePrincipalCredential -ServicePrincipalName “editor/signavio.com”

  2. Enter your symmetric key.

  3. If the credentials have indeed expired, update with the following command. The command returns a new symmetric key.

    ..code-block: none

    New-MsolServicePrincipalCredential -ServicePrincipalName “editor/signavio.com”

  4. Now add the key to the configuration via the Manage Collaboration Hub certificate dialog.

Downloading the Signavio Collaboration Hub SharePoint App

Please open the Explorer to download Signavio Collaboration Hub SharePoint App. Make sure you are logged in as a workspace administrator and follow these steps:

  1. Click in the Setup menu the Manage Collaboration Hub authentication entry. If you have not created a certificate yet, a warning dialog opens.
  2. In the warning dialog, click on Create certificate.
The Collaboration Hub certificate management dialog.
  1. Select the authentication mode from the drop down menu:
    • Certificate based authentication
    • LDAP based authentication
    • Windows Azure Active Directory based authentication

    Depending on your selection, you have to perform further configuration.

  2. If you select Certificate based authentication as authentication mode, use SharePoint 365 as SharePoint version. You can then download SharePoint Webpart/App.

  3. If you select Windows Azure Active Directory based authentication as authentication mode, insert the Windows Azure Tenant ID, the Principal ID and the Symmetric Key. Click Save and Test. In case the test terminates with an error, check your configuration settings. Click Download SharePoint Webpart/App.

    Download of Signavio SharePoint App, in this example in Windows Azure Active Directory based authentication mode.
  4. Depending on your web browser configuration the download starts or a download dialog box is displayed.

  5. Unpack the downloaded .zip-file with an application of your choice, e.g. with the standard Windows tool. The unzipped folder contains the following files:

    • SignavioViewer365.app - the Signavio App for Microsoft SharePoint
    • SignavioViewer365config.csv - the configuration file for the Signavio App.

Manage read access rights

In this chapter you will learn how to manage read access rights on Collaboration Hub for Active Directory users and user groups. To enable directory service-based (AD, Windows Azure) authentication, it is necessary to grant diagram access rights to domain users or user groups. Via the read access configuration dialog, you can configure exactly which user or user group can get access to specific diagrams or folders in Signavio.

Important

In case you set up certificate-based authentication, you can ignore this section.

In case you set up Active Directory-based authentication and you do not configure access rights to any published diagram, a user will see an empty Collaboration Hub.

To grant read access, proceed as follows:

  1. Open the Explorer. We recommend you to use a different browser or your browser’s incognito mode, to avoid session conflicts, see SharePoint displays the Signavio login page, although the authentication mechanism was configured correctly.

  2. Click in Setup menu the Manage users & access rights entry.

  3. Open the Read access tab in the Manage users & access rights dialog.

    The read access tab.
  4. Choose a folder or diagram in the left navigation column. The dialog shows the access rights connected to the object. If the right has been assigned to a parent directory the corresponding folder is displayed as well.

    Overview of all assigned rights of a diagram or folder.
  5. If you have marked the desired folder, then you can specify the user you want to grant access for. Type in a user name by using the search functionality - as soon as you start typing, a drop down list appears containing the user names found. Select the user name. Alternatively click the input field and choose a user name from the drop down list. To navigate through the sites, use the arrow at the bottom of the list.

    Adding a user who will get access to the folder and the contained diagrams.

Hint

Opening the read access dialog and searching for a user or user group can serve as a test of the directory service integration. If an existing user does not appear, something went wrong during the setup.

  1. Click the Add button. The user can now be found in the list of granted access rights.

    The read access will be established for the user.

Revoking read access

You can also remove assigned read permissions. Follow the instructions 1 to 3 of the previous section and then proceed as follows:

  1. Select the user you want to remove from the list of users with read access.
  2. Click Remove right next to the user name.
Removing a user from the list.

Hint

If the read access is inherited from the parent directory, the delete option is not displayed. Navigate to the appropriate folder using the inherited from column and delete the permission here.

  1. Confirm by clicking the Yes button in the warning message box.

Installing the Signavio SharePoint App on Microsoft SharePoint Online/365

In this section, you will learn how to install the Signavio Collaboration Hub SharePoint App for Microsoft SharePoint Online/365. To install the Signavio SharePoint Online App on a SharePoint site, proceed as follows:

  1. Access the SharePoint administrator interface by clicking on the Apps button in SharePoint Online:

    App selection in SharePoint Online.
  2. Select the Admin tile:

    Selection of the "Admin" tile.
  3. In the navigation area, select the SharePoint entry under ADMIN:

    Access to the SharePoint admin center.
  4. Go to apps and open the App Catalog:

    Open the App Catalog.
  5. In the navigation area, select Apps for SharePoint and then click New.

    You may need to create a new site here.

    Adding a new SharePoint App.
  6. Click new item and then upload the SignavioViewer365.app file. Disable the check box Add as a new Version to existing files:

    Uploading the app part file.
  7. Finally click on OK.

Adding the app part

To add the app part to a SharePoint Online site, proceed as follows:

  1. Access the SharePoint site, to which you want to add the Signavio SharePoint app part, e.g. https://COMPANY.sharepoint.com/.

  2. Under Settings, select the Site contents entry:

    Selection of the "Site contents" entry.
  3. Select Add an app:

Add an app.
  1. Click SignavioViewer365App and then check Trust it in the pop up dialog.

  2. Now, a one-time configuration is necessary. Click on the newly installed app to start the configuration:

    Configuration of the installed app.
  3. Upload the SignavioViewer365config.csv from the zip-file you downloaded before and click Save. The file contains information about the server address, a certificate and a password to identify your Signavio workspace:

    Uploading the configuration file.

    Subsequently, Signavio Collaboration Hub will open.

Activating the app part

To activate an app part on a teamsite in SharePoint Online, proceed as follows:

  1. First, select the page tab on the page on which the app part should be displayed.
  2. Click Edit.
  3. Switch to the Insert tab.
  4. Click App Part.
  5. Select the entry Signavio Collaboration Hub for SharePoint Online.
  6. Click Add.
  7. Optionally, you can define an entry-point diagram for the Signavio SharePoint app part. Open the configurations menu of the app part and edit the field entry point. You can get the respective URL through the portal preview of the entry point diagram in the Signavio Explorer - for example https://editor.signavio.com/p/portal\#/model/39e3b4b9134544b98ae4291545cd7928
Insert the entry point URL (in the lower left corner).

Insert the entry point URL (in the lower left corner).

It is possible to add the app part multiple times in your SharePoint, for example in different pages, and add a different entry-point to each instance. You do not need to upload the configuration again.

Removing or updating the Signavio SharePoint App

Important

To properly install a new version of the Signavio SharePoint App, the previously installed app must be completely removed.

To remove or reinstall the app, proceed as follows:

  1. Open your App Catalog in SharePoint Online:

    Open the App Catalog.
  2. Select the appropriate app and then click on More - Delete:

    Deleting the app from the App Catalog.
  3. In the naviagtion area, open the Site contents:

    Open the Site contents.
  4. Select the app and then click Remove in the context menu. The app is moved to the recycle bin.

    Remove the app from your site contents.
  5. The app must now be removed from your recycle bin. To do this, open the recycle bin:

    Open the Recycle Bin.

    The recycle bin should contain two apps. If this is not the case, ensure you followed the procedures correctly. Delete both Apps.

  6. Now, the app has to be removed from the SharePoint Administration’s second-stage recycle bin. For this purpose, open the Recycle bin and then the second-stage recycle bin:

    Open the second-stage recycle bin.
  7. Remove both apps from the second-stage recycle bin.

  8. If you want to update the app, reinstall it as described at Installing the Signavio SharePoint App on Microsoft SharePoint Online/365.

  9. When the new app is installed, update all sites that reference the app.