Installing Shareflex on your SharePoint Online Tenant

The Shareflex Online Solutions are ready-made or custom business applications for digital mapping, automation and optimization of business processes. The Shareflex Online Solutions are based on Microsoft 365 and the Shareflex Online Services. The Shareflex Online Solutions offer all important functions required for company-wide document and file management. Furthermore, individualizations can be made in order to meet the specific requirements and the continuous changes in the business environment.

The foundation of the Shareflex Online Solutions is Microsoft 365, which is extended by the Shareflex Online Services.

The Shareflex Solutions thus consist of a SaaS component (Shareflex Online Services) and scripts/resources that are provided to the customer as a copy for the duration of the contract and must be imported into the customer’s Microsoft 365 environment (Shareflex Online Solutions).

The following is a brief summary of the Shareflex Online Services:

• Shareflex Forms provides user-friendly forms for displaying the SharePoint data of a Shareflex Solution.
• Shareflex Rules provides backend business logic, e.g. when a contract is created, all the necessary data structures are automatically created in the background.
• Shareflex Provisioning can be used to create and update the SharePoint information architecture (e.g. websites, lists/libraries, columns, content types).

These Shareflex Services are provided by a SharePoint App (Forms) and an Azure Enterprise Application (Rules and Provisioning).

The customer’s SharePoint tenant sends certain data (defined and restricted by business logic) to the Shareflex Online Services, where it is processed so that corresponding actions can be carried out on the customer’s SharePoint tenant. Changes to the customer’s documents and other (content) data are made exclusively in his Microsoft 365 environment.

Portal Systems manages the infrastructure (Infrastructure as a Service) hosted in Microsoft Azure data centers, including but not limited to configuration data management, high availability, configuration data recovery, security and scaling.

Portal Systems guarantees that all created and filed data and documents are stored exclusively in the customer’s own Microsoft 365 tenant. In Shareflex SaaS, only customer-specific configurations of the Shareflex ECM Online applications are managed. These individual configurations are not subject to an automatic update mechanism.

What data processing activities are performed by the Portal Systems Azure-based server and how does it integrate with the SharePoint instance?
The processing that is carried out entirely depends on the solution used and any potential customizations. As a general rule:

• Metadata is added and modified (such as a unique identifier to establish a relationship with another item or document).
• Information architectures are supplemented.
• Workflow tasks are created.
• Permissions are set.
• E-mails are sent.
• Items and documents are created, copied, moved and/or deleted.
• SharePoint groups are created.
• Users are assigned to SharePoint groups.
• Processing is initiated by so-called Remote Event Receivers, which are registered and authorized in SharePoint.

• A properly configured Microsoft/SharePoint environment, including SharePoint licenses for your users.
• Shareflex licenses for all users that are going to use Shareflex one way or another (your tenant name will have to be shared with Portal Systems).
• The Shareflex licensing data and SharePoint solution package file, which will be provided by Portal Systems once your Shareflex licenses are active.
• A Microsoft 365 account with the “Global Administrator” role (most actions can be performed with a lower role, as described in each individual step).
• A name for the SharePoint site that will be used to host your  Shareflex app(s). Note that this site must not yet exist.

Needed role: “SharePoint Administrator”

Navigate to the Active sites page within the SharePoint admin center:

https: // <TENANT> -admin.sharepoint.com/_layouts/15/online/AdminHome.aspx#/siteManagement

Click on Create, and in the dialog that opens choose the “Browse more sites” option.

Make sure to select the “Team site” template, and choose “../sites/” as the Site address prefix. All other info (including the site name) is up to you. Click on Finish to create the site.

If all went well, the value in the Template column of the created site should be set to “Team site (no Microsoft 365 group)”.

Shareflex uses SharePoint subsites to store core and application-specific resources. If subsite creation has not been enabled in your SharePoint settings, you will need to do so.

Needed role: “SharePoint Administrator”

Go to the Settings page of the SharePoint admin center, then open the “classic settings page”.

Locate the “Subsite Creation” section, select the “Enable subsite creation for all sites” option, then scroll down and click on OK to save the setting.

Needed role: “SharePoint Administrator”

Two properties will have to be updated through the SharePoint Online Management Shell:
– The DenyAddAndCustomizePages site property has to be disabled so that Shareflex can create custom properties, which is essential for it to properly function.
– The SiteOwnerManageLegacyServicePrincipalEnabled tenant property has to be enabled so that the permission scope of Shareflex’s SharePoint Add-in can be restricted to your created site.

On a Windows device, launch “Windows PowerShell ISE” as Administrator. Execute the following code to install the latest version of the SharePoint Online Management Shell:

“`

if (Get-Module -ListAvailable -Name Microsoft.Online.SharePoint.PowerShell) {
Update-Module -Name Microsoft.Online.SharePoint.PowerShell
}
else {
Install-Module -Name Microsoft.Online.SharePoint.PowerShell
}

“`

During the installation it may prompt you to install additional dependencies, or to trust the repository. If so, click on Yes. Once the installation finishes, it will briefly display a notification message:

Once the module is installed, connect to your SharePoint tenant by executing this command:

“`Connect-SPOService -Url https://<TENANT>-admin.sharepoint.com“`

In the Sign-in window that appears, log in using your SharePoint Administrator account.

Execute the following command to disable the DenyAddAndCustomizePages property of the site that you created earlier:

“`Set-SPOsite https://<TENANT>.sharepoint.com/sites/<CREATED-SITE> -DenyAddAndCustomizePages 0“`

Then execute this final command to enable the SiteOwnerManageLegacyServicePrincipalEnabled tenant property:

“`Set-SPOTenant -SiteOwnerManageLegacyServicePrincipalEnabled 1“`

This step should be skipped if you already have another Shareflex-enabled site on your SharePoint tenant.

Needed role: “Global Administrator”, “Application Administrator” or “Cloud Application Administrator”

Navigate to the URL that was communicated by Portal Systems. The URL should look like this:

https://login.microsoftonline.com/<TENANT>.onmicrosoft.com/v2.0/adminconsent?client_id=<APP-ID>&response_type=token&scope=https%3A%2F%2F<TENANT>.sharepoint.com%2F.default&state=give-consent%20&redirect_uri=https%3A%2F%2Fwebsite-<APP-URL-PART>.azurewebsites.net

In the consent dialog that appears, accept the requested permissions.

After accepting the permissions, you will be redirected to the Shareflex Online app. You can close this page.

Shareflex uses remote event receivers, which requires you to grant it access to SharePoint via a SharePoint App-Only authorization.

Needed role: “Global Administrator”, “Application Administrator” or “Cloud Application Administrator”

Head to the Enterprise applications page of the AAD, then locate and open the “Shareflex Online” app.

Go to the Properties section. Do not change anything, but write down the below three highlighted values:

Navigate to the App Permission page of the site that you created:

https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>/_layouts/15/appinv.aspx

Insert the AAD app values that you wrote down earlier into the fields on the page, as seen in the below screenshot.
Note that the “App Domain” field should not contain a “https://” prefix, unlike the “Redirect URL” field.

Copy & paste this XML (without any changes) into the “App’s Permission Request XML” field:

<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
</AppPermissionRequests>

Apply the permissions by clicking on Create, then click on “Trust It” to confirm.

Confirm that the permissions have been applied correctly by going to the Site App Permissions page from within the Site Settings of your created site.

If everything is correct, you should be able to see an entry for the “Shareflex Online” app.

This step should be skipped if you already have another Shareflex-enabled site on your SharePoint tenant.

Needed role: “Global Administrator”, “Application Administrator” or “Cloud Application Administrator”

Navigate to the URL of the Shareflex Online app that will have been provided by Portal Systems. The URL will look like either

https://<website-APP-URL-PART>.azurewebsites.net

or

https://sfs<NUMBER>.portalsystems.de

Enter the absolute URL of the site you that you created (e.g. https://contoso.sharepoint.com/sites/shareflex) into the “SharePoint site” field, then click on Enter.

In the dialog that appears, make sure to check the “Consent on behalf of your organization” checkbox, then click on Accept to agree to the requested permissions.

Head back to the Enterprise applications page of the AAD, open the Shareflex Online app and click on the Permissions menu entry.
Verify that the listed permissions match the below screenshot.

Needed role: Site (Collection) Administrator

Now that all permissions have been properly configured, the Shareflex Online app can be used to install its required Core resources on your SharePoint site.

Navigate to either of the following URLs (depending on what domain was provided by Portal Systems) :

https://<website-APP-URL-PART>.azurewebsites.net/baf/?SPHostUrl=https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>

or

https://sfs<NUMBER>.portalsystems.de/baf/?SPHostUrl=https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>

Enter an email address into the “Administrative Contact” field and click on Save.

Before moving on, make very sure that the display language of your Microsoft account matches the default language of your created site. This is a technical limitation that (only) applies during the execution of any Shareflex script (including the Core resources).

To check the default language of your created site, navigate to:

https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>/_layouts/15/muisetng.aspx

To check the display language of your Microsoft account, navigate to:

https://myaccount.microsoft.com/settingsandprivacy/language

If they are different, (temporarily) change your account’s display language.

You can now start the installation of the Core resources by clicking on “Setup Core web now”, then on OK to confirm.

The installation will take a couple of minutes. The page will auto-refresh until the installation completes.

Once the installation has finished (the Job Log status should be green), click on the “Prepare as Master Site” button, then on OK to confirm.

After a few minutes the second Job Log should be green as well.

Most of the Shareflex resources will have been deployed to the Shareflex Core subsite located at https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>/pscBAF. Feel free to look around.
You can also get to the Shareflex Core subsite by clicking on the “Core web” button on the Shareflex Online app page.

In the Settings menu of your SharePoint site (including its subsites such as Shareflex Core), you can now also find a menu entry to quickly navigate to the Shareflex Online app.

Keep in mind that this link is site-specific, so whenever you use the Shareflex Online app (including the Provisioning Client), always double check if its context is set to the correct site:

Once you are logged in to the Partner Portal, click on the Deployments button.

Then open the “Shareflex Add-ons” folder and locate the latest version of the ShareflexAddons archive for SharePoint Online (O365).

Download the archive file and unzip it somewhere.

Needed role: Site (Collection) Administrator

In your own SharePoint tenant, head to the Deployment library inside of the Shareflex Core subsite:

https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>/pscBAF/Deployment

Then upload (e.g. by dragging and dropping) the entire “ShareflexAddons” folder to the Deployment library.

Shareflex offers a complex proprietary XML-based scripting language that can be used to automate certain SharePoint & Shareflex actions.
Files making use of this language will have the “.beeml” file extension.

Inside the ShareflexAddons folder there should be a file called “ShareflexAddons.beeml”. Open this file with any text editor, and copy its contents.
Head back to the Shareflex Online app page (through the link in the Settings menu), select the Tools tab, and click on Open Web IDE.

This Web IDE (also called Provisioning client) allows you to execute *.beeml scripts.
Before executing anything, make sure that the “Start Web” field contains the URL to your created site (https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>).
The “User” and “Password” fields should be ignored.
The “File Name” field is useful for providing a short script description that can later be used to the execution jobs/logs. This is optional, but recommended.

Feel free to execute the default script as a test, by clicking on Execute. Then click on Autorefresh to view the execution progress in real-time.
If the script ran successfully, the progress log will end with “Script successfully executed”. Note that any warnings (unlike errors) are generally safe to ignore.

Now delete the default script, and replace it with the contents from the “ShareflexAddons.beeml” file.
Before executing the script, perform a Precheck. This will quickly analyze the script to look for potential issues.

After the precheck finishes, click on Execute. The Shareflex Addons installation will take about two hours.

Note that the Provisioning client runs all scripts as background jobs, so it is fine to close your browser.
At any point in time you can view the status/progress/history of a background job by clicking on the Joblist button within the Provisioning client.

Which brings you to this background job overview:

Once the installation job finishes it will move to the Completed tab,  and its Run State will update to “Terminated (Normal)”, assuming that no problems arose.

This step should be skipped if you already have another Shareflex-enabled site on your SharePoint tenant.

Needed role: “SharePoint Administrator”

Navigate to the App Catalog page within the SharePoint admin center:

https://<TENANT>-admin.sharepoint.com/_layouts/15/tenantAppCatalog.aspx

Upload the “shareflex-forms.sppkg” file that Portal Systems shared with you. This SharePoint solution package contains the client-side web parts that are necessary to view Shareflex forms.

Once the upload finishes the “Enable app” dialog should automatically appear.
Select “Enable this app and add it to all sites, uncheck “Add to Teams” and then click on the Enable app button.

Once enabled it should look like this:

And that’s it!

Note that the Shareflex Contract app requires its own dedicated (Shareflex-enabled) site. If you don’t already have one, follow all of the above steps first.

Head to the Deployments library of the Partner Portal, open the Shareflex Contract folder, then locate the latest version of the ShareflexContract archive for SharePoint Online (O365).

Download the archive file and unzip it somewhere. It should contain two folders: “ShareflexContract” and “ShareflexAddons”. Open the latter and identify its version number by locating the subfolder that starts with an underscore.

Needed role: Site (Collection) Administrator

In your own SharePoint tenant, head to the Deployment library inside of the Shareflex Core subsite:

https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>/pscBAF/Deployment

If the library contains a ShareflexAddons folder, identify its version number in the same manner.

If the version number of the ShareflexAddons inside the Deployment folder is lower than the one included in the ShareflexContract archive, delete the entire ShareflexAddons folder from the Deployment library.

If the Deployment library does not contain a ShareflexAddons folder (anymore), upload the ShareflexAddons version included in the archive.

Finally, upload the “ShareflexContract” folder from the archive as well.

Open the Provisioning Client by navigating to the Shareflex Online app (remember the link in the settings menu?) and clicking on “Open Web IDE” under “Tools”.

Open the ShareflexContract > BEEML folder within the downloaded archive, then copy the contents inside file “0 Init.beeml”.

Head back to the Provisioning Client and replace the default script with the script you just copied. Perform a Precheck, then Execute it if no problems were found.

Open the Joblist and wait until the background job finishes. If no problems occur, the job’s Run State will be “Terminated (Normal)”.

Now, depending on what contract types you want to support, also execute scripts 1 to 8. Wait until each script finishes before starting the next one.

This is what your site’s homepage will look like after installing the Service Agreements contract type (script “1 DV – SA.beeml”):

The TimeKeeper app can be deployed as subsite on any of your existing (Shareflex-enabled) sites. It does not need its own dedicated site.

Needed role: Site (Collection) Administrator

Unzip & upload the provided TimeKeeper deployment package to the Deployment library of the Shareflex Core subsite:

https://<TENANT>.sharepoint.com/sites/<CREATED-SITE>/pscBAF/Deployment

Head to the Provisioning Client by navigating to the Shareflex Online app  (remember the link in the settings menu?) and clicking on “Open Web IDE” under “Tools”.

Locate the file “setup.beeml” within the TimeKeeper deployment package, open it with the text editor of your choice, then copy its contents.
Head back to the Provisioning Client and replace the default script with the script you just copied. Perform a Precheck, then Execute it if no problems were found.

Open the Joblist and wait until the background job finishes. If no problems occur, the job’s Run State will be “Terminated (Normal)”.