Working with OneDrive files

Applies to version: 2022.1.3 and above; authors: Jacek Język, Krystyna Gawryał

Introduction

WEBCON BPS has a new feature, which is the ability to work with attachments in the form of files stored on OneDrive. A user with the appropriate permissions will be able to edit such MS Office files (Word, Excel) in Microsoft 365 both in a desktop browser and from mobile devices. In addition, files placed on OneDrive as part of the process will be available for editing by multiple users at the same time, and any changes they make will be visible to others in real time.

The present article describes this new feature on the example of a process in which an advertising agency employee prepared marketing documentation requested by a client (a Word document called "Product series advertisement" and an Excel document called "Promotional campaign slogans"). The author would like to share the prepared documentation with their colleagues from the creative department so that they can proofread it and make any changes thereto / give suggestions. In the next step, the documentation will be forwarded to the supervisor for review.

The process used in the business case is as follows:

The designed process assumes that during the review stage by the creative department, several users will simultaneously make changes to the document. To do this, the document will be edited after sharing the file on OneDrive for the time of editing.

Connection to OneDrive – configuration

Handling files located on OneDrive will be possible, provided that the appropriate connections to this service are configured in the system. For this purpose, the application that will be used for communication between WEBCON BPS and OneDrive must be registered in Microsoft Azure. The parameters of the registered application (Tenant ID, Application ID, Application Secret) are part of the connection configuration.

All WEBCON BPS file sharing operations in OneDrive are performed using the Microsoft Graph API in the context of the application. This means that the user who performs the actions of starting, finishing or cancelling file editing does not need to additionally log in to OneDrive. Therefore, a Microsoft Azure application should have Application permissions. Application permissions must allow both writing and reading of files.

• Permissions for all site collections

One of the configuration options is to grant the application the Files.ReadWrite.All permission. It gives the application access to all site collections, i.e. to OneDrive of all users of a given Microsoft Azure Tenant, and allows to indicate any account as the OneDrive Owner when configuring the connection to OneDrive.

The WEBCON BPS Designer Studio administrator will then have full freedom to configure this connection parameter, without having to modify the configuration of the Microsoft Azure Tenant application.

Note that the Files.ReadWrite.All permission is broad (access to all OneDrive instances in the organization) and may violate the company’s security policy.

• Permissions for selected site collection

An alternative configuration of the Microsoft Azure Tenant application is to give it permissions only to selected OneDrive instances.

The Sites.Selected permission should then be set in the configuration.

Then, in the permissions of the selected OneDrive instances (in the case of the company’s OneDrive, these are the permissions in the corresponding site collections), access to the application should be granted using the method available in the Microsoft Graph API:

      POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions

Microsoft does not provide a user interface with the ability to modify this type of permissions, so the configuration must be done using a PowerShell script.

A helpful description can be found at: Controlling app access on a specific SharePoint site collections is now available in Microsoft Graph - Microsoft 365 Developer Blog

The OneDrive connection configuration on the WEBCON BPS Designer Studio side is similar. The Tenant ID, Application ID, Application Secret, and OneDrive Owner parameters must be filled in. Just be sure to enter the exact account whose site collection has been shared with the Microsoft Azure application when specifying the OneDrive Owner.

It should be mentioned here that the connection, like all other connections in the system, will be transferred via the Import/Export, i.e. the connection will appear in the tooltip when importing files, when used in the process.

Start editing a file using OneDrive

In order to share the prepared documentation with colleagues in the department, the advertising agency employee should add an appropriate action on the "Share with coworkers" path from the "Documents created" start step.

Three actions dedicated to OneDrive have been added in the system. One of them is the Start editing a file using OneDrive action required in this case, which allows to add a copy of the file in the indicated location on OneDrive.

This action must be properly configured, using the options in the dedicated window:

The available options allow to define parameters of attached files, such as Name and extension, Category, or Regular expression.

In the OneDrive location section, the employee should indicate the previously configured Connection and Destination folder where the file will be saved.

After configuring the action and following the "Share document with coworkers" path, the files added on the form as attachments will be uploaded to the indicated One Drive location – in this case, the destination folder named "WEBCON BPS".

The uploading of files to OneDrive is evidenced by the change of attachment icons on the workflow instance – the characteristic OneDrive "cloud" will be applied to them.

Now, the indicated department employees will be able to open and edit documents on OneDrive at the same time, and the changes they make will be visible to everyone with the appropriate permissions (including in files attached to the workflow instance immediately after saving the changes).

With the new options, files shared on OneDrive can be opened from the form, both in a dedicated Microsoft 365 application in a desktop browser and directly in the OneDrive location.

When previewing a document at the form level, the system will display the following message:

User permissions to edit files

In order to be able to edit WEBCON BPS form attachments in OneDrive, the persons designated for editing must have the appropriate permissions. Such permissions are granted automatically by the WEBCON BPS action to all persons who are able to edit form elements in WEBCON BPS.

File editing permissions are granted based on the user ID in UPN format – persons specified by the user should have an account in Azure Active Directory.

Finish editing a file using OneDrive

According to the designed process, after making any changes and agreeing them with the author, department staff sends the file to the supervisor for approval. The supervisor can also edit the files shared with them, return the task to the author, or accept the documentation after making changes.

To download all changes made in OneDrive back to the BPS database, it is necessary to create a new automation based on the Finish editing a file using OneDrive action.

In the present case, it will be added to the "Accept" path:

After following the path, the action will download data from OneDrive, save it to the BPS database, and then delete the files from the indicated location in the service. Additionally, the successful action will be evidenced by the restoration of the original appearance of the attachment icons in the workflow instances (in the Archive in the present case).

Cancel editing a file using OneDrive

In emergency situations, when, for example, there is an unexpected error or the workflow in any of the steps goes against the author's original intention, the author has the option to undo OneDrive file sharing. In such a case, the solution will be to use a new action available in the OneDrive group: Cancel editing a file using OneDrive. The action allows BPS users to cancel the link with an attachment in the workflow and restore its version from before publication.

Moreover, the action operates on all attachments linked to the instance in the context of which it was called. If necessary, the action can also be called in the automation (the For each operator) or from the Attachments menu.

In the present case, the author would like to cancel editing of only one of the attachments – the Excel document – so they should configure the action at the selected step to be called from the Attachments menu:

Configuration of the Cancel editing a file using OneDrive action from the Attachments menu

The action will work in the context of a single file that has been added to the workflow and placed on OneDrive.

Both actions: Cancel editing a file using OneDrive and Finish editing a file using OneDrive require no additional configuration. The connection ID is saved in the attachment metadata so that the correct file can be operated on from the form.

Alternative file sharing options

As mentioned above, in order to edit files via OneDrive, the user must have the appropriate permissions. There is, however, an exception to this rule. As long as the company’s appropriate security policy is met, files placed on OneDrive can be made available for editing to any users. This is possible using the Call REST Web service action. Once the action is properly configured, a wider group of users will be able to edit specific files on OneDrive.