Feature details

The Edit in Cloud feature allows users to edit office documents (stored in their Document type trackers) in a cloud provided editor, in this case Microsoft's online editor.

The feature uses the Microsoft Graph API to provide the ability to edit documents, so to use this feature there are a few things required:

• Microsoft account (for authentication) (both business and personal accounts can be used)
  • Access to Microsoft OneDrive
• Proper configuration.

Configuration

Here you can find how to configure this feature to be able to use it.

To use the Edit in cloud feature with Microsoft, first of all an Azure application is required.

The configuration allows arbitrary Azure application usage, so it is up to the configurator whether they use a self maintained Azure application or the one provided by Intland.

Configuring your own Azure application

An Azure application is necessary to ask the appropriate permissions from the user to be able to upload, download and create files in the user's OneDrive.

To configure an Azure application, you will need a microsoft account with proper permissions to create such application.

In this section you can find the steps to create the required Azure application from start to finish.

The first step is to go to the Azure portal: https://portal.azure.com

Search for tha Azure Active Directory service and select it.

From the left side menu, select the "App registrations" menu option.

Click on the "New Registration" button at the top.

Give the application a name and select the target audience.

Here you can specify who can use this application and which kind of accounts can authenticate through the application.

If you decide that only your organization (in case of business account) should use the application and for improved security you don't want to allow other users to authenticate, then select the "Single tenant" option.

Enter the Redirect URI which should be the following format:

https://YOUR_INSTANCE_URL_WITH_CONTEXT_PATH/rest/exposed/finish-microsoft-auth

When finished, click on the Register button.

Now you have the application's ID (client ID) take a note of this ID because you will need it for the instance configuration.

Click on the "API permissions" from the left side menu.

Click on the "Add permission" and from the appearing right panel, select the "Microsoft Graph" option.

The application to work properly needs two permissions from the user:

• Files.ReadWrite.All
• Sitest.Read.All

Select these permissions after you selected the "Delegated" option from the panel.

After setting the application permissions, select the "Certificates & secrets" option from the left side menu.

Click on the "New client secret" button.

Optionally you can give a description for the secret, and set an expire date, then click on the "Add" button at the bottom.

Note the generated secret's value because this also required by the instance configuration.

Lastly, select the "Authentication" from the left menu and check the "Access tokens" and "ID tokens" checkboxes.

With all of this, the Azure application is all set, the next thing is to apply the noted client ID and secret in the instance's application configuration.

Go to your instance and open the Application configuration from the System Admin page.

Enter the following configuration:

  "editInMicrosoftCloud" : {
    "clientId" : "YOUR_CLIENT_ID",
    "clientSecret" : "YOUR_CLIENT_SECRET",
    "enabled" : true,
    "parentFolderName": "intland.com",
    "redirectURI" : "YOUR_INSTANCE_LOCATION_WITH_CONTEXT_PATH/rest/exposed/finish-microsoft-auth"
  }

You can enable and disable the feature using the "enabled" property.

The "parentFolderName" property is used as a folder name in your OneDrive where the cloud edited files will be uploaded. Make sure that this name is unique and there are no other folders in the root of your OneDrive.

The "redirectURI" must be your instance's URL with context path and the following postfix: /rest/exposed/finish-microsoft-auth

Save the configuration and everything is now set up to use the feature.

Please make sure that there is no other cloud edit configuration is enabled at the same time!

The configuration only allows one cloud edit configuration at the same time, so for example if Google Drive cloud editing is also enabled along with the Microsoft OneDrive cloud editing, neither of the features will work!

Use the Azure application provided by Intland

There is a production version Azure application that is meant to be used by everyone who use this feature.

Every product has the configuration of this Azure application as a default and the feature is also enabled by default, so you are all set up, the feature should work using our Azure application out of the box!

Use cases

Edit a document in Microsoft's cloud editor

With the Edit in cloud feature configured and enabled, one can edit multiple documents from their Document type tracker in Microsoft's online editor.

The supported file formats where the feature can be used are the following:

• .doc, .docx,
• .xls, .xlsx,
• .ppt, .pptx,

First of all, we need a document, let's say a Word document, like this:

The first thing to do is upload this Word document to one of our Document type trackers.

After the upload finished, hover over the uploaded document's row, and click on the more menu to reveal the cloud edit options.

Click on the "Edit on OneDrive" option.

If you using this feature for the first time, an authentication popup will show up, where you need to login with your Microsoft account.

After signing in, you will see the consent screen of the application, where you can see what permissions the application use and in order to continue, you need to accept these permissions.

Optinally you might need to login to your instance after accepting the permissions.

In case of successful authentication, the popup closes itself and the Word document is being uploaded to OneDrive.

After the upload finish, the online editor will open automatically.

Here you can edit the document just like a regular document in your OneDrive.

After this point you have 2 options:

1. Finish the cloud edit
2. Cancel the cloud edit

The finish option grabs the document from your OneDrive with all it's content and after downloading it, the Document in your Document type tracker is updated to this downloaded version.

The cancel option simply discards the cloud edit and the changes made to the uploaded document won't be downloaded.

Please note that both of these options result in deleting the document from your OneDrive!

Before you click on the finish option, make sure that Microsoft's online editor is closed, because it locks the document and download is not possible for a locked document!

Working together on a document in cloud

Once a document is uploaded (Cloud edit started) to your OneDrive, it is only visible and editable to you specifically.

However, others can still see and open the cloud edited document from the system.

The below screenshot is from a different (but project admin) user's perspective:

Opening the document from a different user will most likely to result in a permission request page:

Here you can request access to the document, which will send and email to the owner of the document who can grant access to it.

After gaining access, you can both work on the same document simultaneously.

Please note that even if you have access to the document, you will not have the ability to finish or cancel the cloud edit in the system, only the owner of the document can finish or cancel it.

Create a new document by selecting a file from OneDrive

It is possible to create Documents not just by dragging and dropping a file from your file system (or picking one through the browser's dialog) but by picking the file from your OneDrive.

For this feature to work, the Edit in cloud feature must be enabled from the application configuration.

Click on the "Add documents" at the top left corner on a Document type tracker to open the create documents dialog.

Here you can find the "Add from OneDrive" button which will open the OneDrive file picker.

Please note that Microsoft authentication is required to use this feature, if you have not yet logged in with your Microsoft account, the authentication popup will appear before showing the picker dialog!

From the dialog, you can select multiple files, then by clicking on the "select" button, the selected files will be downloaded and they will appear as new documents in the Document type tracker.

After creating the documents in the system, they behave like a regular file picked from the file system.

Please note that not just Office type files can be picked using the dialog, other file types like text document (.txt) or images can also be introduced to the system through this dialog, however the cloud edit feature will only be available for the supported document types.

Update an existing document by selecting a file from OneDrive

Just like creating a new document using the OneDrive picker dialog it is also possible to update an existing document by selecting a file from your OneDrive.

Open an existing document from a Document type tracker and click on the "Upload Document" button.

From the appearing dialog, select the "Add from OneDrive" button and the same picker dialog will appear as at new document creation.

Please note that since here the goal is to replace an existing document, you can only select one file fromg the OneDrive picker dialog!

Create new empty Office documents

This feature provides a way to create new empty documents through our system. There are three types of documents that the feature supports:

• Word Document
• Excel Document
• Powerpoint Document

To create a new empty document, click on the Add documents button then click on the caret icon next to the "Add from OneDrive" button to reveal the types menu.

After selecting the new document's type, you need to give the new document a name.

The name does not need to contain the file extension (.docx, .xlsx, etc.) it will be added automatically depending on the type of document you chose.

Please note that OneDrive does not allow files to exist with the same name, so make sure that the name you give for the new file does not exist yet under the cloud edit folder in your OneDrive.

After typing in the name, click on the "create" button and the creation will begin.

When the creation finish, the online editor for the empty file will open automatically on a new browser tab. This means that in this case, not just the new document is being created in the system, it is automatically cloud edited immediately after creation.

Force cancel other's cloud edited document

Since a cloud edited document can only be finished or canceled by the user who started the edit in the first place, in some cases it might be necessary to intervene and cancel an existing cloud edited document progress so others can access the document. When a document is being edited in the cloud, it can only be accessed for read, but nobody can update the document in any way except for the cloud edit owner.

To give more flexibility, project admin users (any only project admin users) have the option to force cancel a cloud edited document which started by others but neither finished, nor cancelled.

This option does not remove the document from the owner's cloud, but rather removes the link between the document in the system and the file in the cloud.

Later the changes made by the owner can be recovered manually from the owner's OneDrive and optionally the document still can be updated using the file and the OneDrive file picker dialog.

Troubleshooting

There are several cases where issues can happen considering the inconsistency of Microsoft Graph API.

Most of the times it is a good approach to simply just retry what we did again, maybe after a page refresh or logging out then in again.

If that does not help enable the debug mode for the feature in the System Admin settings, reproduce the issue and ask for help from our support with the logs.

To enable debug for the feature, add the following lines to the Logging configuration in the System Admin page:

log4j.logger.com.intland.codebeamer.controller.rest.v2.cloud.edit=DEBUG
log4j.logger.com.intland.codebeamer.manager.cloud.edit=DEBUG

Common issues can happen when:

• You try to finish/cancel a cloud edited document while it is open in the online editor. Please close the online editor and try again
• You try to finish/cancel a cloud edited document which no longer exists in your OneDrive (due to accidental deletion or move). Please make sure that when you click on the "Open document in cloud" option the document opens without any issue.
• You try to create a new empty document with a name that already exists under the configured cloud edit folder in your OneDrive. Please make sure you use a unique name.

Security

After the user signed in with the Microsoft account, the system will receive a token which is used to communicate with Microsoft Graph API. Long term tokens are used, which means that you do not have to authenticate every day if you use the featues, just after a longer period of time. There is a renew token which is also received along with the regular token, which can be used to renew the authentication in case it expires. This happens seamlessly in the background.

You can always go into your Microsoft account settings and remove the permissions from the application. Here are the steps to remove the permissions from the application:

1. Go to https://account.microsoft.com login with your account
2. Go to privacy settings
3. Scroll down to the bottom and select "Apps and services that can access your data"
4. Select the application and click on edit
5. Click on remove permissions

Limitations

First time access to a user's personal drive through Microsoft Graph before the user accesses their personal site through a browser leads to a 401 response. (https://docs.microsoft.com/en-us/graph/known-issues#files-onedrive)

On the OneDrive picker dialog, ordering is only supported by the "Name" column.

There are no known file size lmitations at the moment.

Files with the same name cannot exist in the user's OneDrive at the same path.

For private Microsoft accounts the Sharepoint sites section is not available on the OneDrive picker dialog, it is only accessible by business (organization) accounts.

The online editor cannot be used for the following file extensions:

• .pot
• .dot
• .pps
• .xlt
• .doc (only after conversion)
• .xls (only after conversion)
• ppt (only after conversion)