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 Google's Docs, Sheets or Slides.

The feature uses Google's Drive API to provide the ability to edit documents, so to use this feature there are a few things required:

• Google account (for authentication)
  • Access to Google Drive (provided along with the Google account)
• 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 Google, first of all a GCP (Google Cloud Platform) application is required.

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

Use GCP application provided by Intland

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

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

Please note that Intland's preconfigured GCP application is supported only on cloud environments hosted by Intland.

Regarding self-hosted environments please see how to prepare own GCP application below.

Configuring your own GCP application

In case the GCP application provided by Intland does not meet your needs - either because the requests are routed via Intland's dedicated proxy server or since you need other permissions configured - it is also possible to create your own GCP application for integration purposes.

The goal of this section is to give guidance on how to create a GCP application and create an OAuth credential for web applications.

Go to the following website: https://console.cloud.google.com/

Log in with your Google account if necessary.

You might need to agree on the terms and services if you use Google Cloud for the first time:

After continue, click on the "Select a project" at the toolbar on the top then click on the "New Project" button at the top right of the appearing dialog.

Add a name for the project, this can be anything and optionally select a location (if there is any).

Click on the "Create" button to finish creating the project.

Wait until the project is created. A notification will appear at the top right corner if the project is ready to use (this might take a few minutes).

The next step is to enable the Drive API for the project. For this, select the "APIs & Services" section then the "Library" option from the left side menu.

Type "Drive API" to the search bar at the top to filter for the Google Drive API. Select it from the list.

Click on the "Enable" button to enable the API for the project.

The next step is to configure the application, for this open the left side menu again and from the "APIs & Services" section, select the "OAuth consent screen" option.

If you have a company managed account, here you will have two options to select from:

• Allow the application to be used by people outside of your organization (External option)
• Use the application internally by your organization (Internal option)

If your Google account does not belong to any organization, the only option is the "External".

After selecting an option, click on the "Create" button.

Fill in the App information section and the Developer contact information at the bottom (these two are required). After filling in the fields, click on the "Save and continue" at the bottom.

The next step is to set the Scopes of the application. Click on the "Add or remove scopes" button.

From the right panel, click on the input field next to the Filter and type "drive.file" to filter scopes.

Select the option from the list (https://googleapis.com/auth/drive.file) and click on the "Update" button.

This scope is a non-sensitive scope, because this allows the application to access only the files and folders that is created by the application itself, so other files stored in the user's Drive, won't be affected by the application.

To be able to "import" files from your Google Drive and create Document type Tracker Items from them, the following additional permission is necessary: (https://googleapis.com/auth/drive.readonly) as the screenshot shows below:

This scope however is a sensitive scope so you can see that it is in a different scope category.

Click on the "Save and continue" at the bottom.

If you selected the "External" application type, you have add test users to the application. Only users listed here will be able to use the application.

For "Internal" type the organization's users are able to use the application automatically.

Please note that there is a limit of how many test users can you have and you cannot remove test users while the application is in testing phase.

As a last step a summary of the configuration is presented. Click on the "Back to dashboard" button.

The next step is to create the OAuth credentials.

Select the "APIs & Services" again from the left side menu and select the "Credentials" menu option.

At the top of the page, click on the "Create credentials" button.

Select the OAuth client ID option.

For the application type, select "Web application" and give a name to the credential.

Click on the "Add URI" button to add a redirect URI.

Please use your instance's address instead of localhost like this:

YOUR_INSTANCE_ADDRESS_WITH_CONTEXT_PATH/rest/exposed/finish-google-auth

Click on the "Create" button.

The created credential (client ID and client secret) will be shown on a dialog. Keep note of the data and click on the "OK" button.

Now we have to enable another API which is the Google Picker API.

This will provide us a nice picker dialog on the UI where we can select a file from our Google Drive to be transferred into the system. For this, first open the "Library" again from the "APIs & Services" section:

Type "picker" into the input then select the "Google Picker API".

Click on the "Enable" button to enable this API.

On the next page, click on the "Create Credentials" button.

From the dropdown list, select the "Google Picker API" option and click on the "What credentials do I need?" button. This will create the necessary credentials for this API.

Copy the Key, we will need it for the configuration. Recommended to restrict this API key to be able to only use the Picker API with it. To restrict the key, click on the "Restrict key" link.

Select the "Google Picker API" from the dropdown and click on Save.

One last bit of information for the configuration is the GCP application ID.

It can be found under the "Settings" menu option under the "IAM & Admin" section:

With this step finished, the GCP application is ready to roll. Now the credential needs to be configured in codebeamer too.

Login to codebeamer X and open the System admin settings. Search for the "Application configuration" and open it.

The following configuration needs to be added to the application configuration:

"editInGoogleCloud": {
    "enabled": true,
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "parentFolderName": "intland.com",
    "apiKey": "YOUR_PICKER_API_KEY",
    "appId": "YOUR_GCP_APP_ID",
    "authClient": "RETINA" or "CODEBEAMER",
    "redirectURI": "http://localhost:8080/cb/finish-google-auth.spr"
}

Fill in the configuration with your credential info and set the enabled to "true".

The "parentFolderName" property is used to create a folder in your Drive with the given name. Every document that is handled by the Edit in cloud feature will be stored under this folder.

The "redirectURI" must match with one of the redirect URIs configured in the GCP application.

Now the everything is set up, the feature is ready to be used.

Use cases

Bring files from your Google Drive into the system

This functionality is available at Document creation in Document type trackers.

For this feature to work, the Cloud Edit feature should be configured properly and you need to authenticate with your Google account.

By clicking on the "Add from GDrive" button, if you are not yet authenticated with Google, the authentication flow starts on a new browser tab automatically.

Before clicking on the button, select the target folder and/or if document duplication is not enabled, select a collision handling strategy below the drag'n'drop area.

A picker dialog will appear when you click on the "Add from GDrive" button:

Here you can select multiple files, they will be used for document creation in the system.

Folder selection is not allowed on the picker dialog and the same restrictions and limitations apply to the selected files as to the files uploaded manually from the local computer.

The picker dialog does not support the following features (these are supported using regular local file system file pick):

• Extract archive
• Upload folder content
• Resumable upload

Edit a document in Google's cloud editor

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

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

• .doc, .docx, .dot
• .xls, .xlsx, .xlsm, .xlt
• .ppt, .pptx, .pps, .pot

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

Let's upload this word document to a Document type tracker.

Hover over the item's row and click on the three dots to reveal the more menu. If the feature is configured and the file extension is supported the "Edit in cloud" option will appear in the menu. Click on it.

For using the feature the first time, first of all, a Google authentication is required, the authentication flow will open up in a new tab in your browser every time if authentication is necessary. Select your google account and continue the flow.

If you use a custom (self) configured GCP application for the feature, multiple messages will notify you through the process about the GCP application's risks, since it is a not published and reviewed application.

If you use Intland's GCP application for this, these messages won't appear.

You need to accept the GCP application's permissions and scopes, they will be listed on the next dialog.

A final confirmation is necessary if using a self configured GCP application.

These are only displayed on the first authentication with your account, subsequent authentications will be faster.

Now the application will take you to your instance, where you might have to login. After logging in a success or error message will be displayed indicating the success or failure of the authentication.

Now that the tab closes in the browser, open the more menu again.

If the authentication was successful, this time clicking on the "Edit in cloud" option will result in a loading dialog. After the loading finished, the document will be opened on a new tab where you can edit it.

When you edit a document in the cloud, updating that document in codebeamer is not allowed.

This means that if you or other users want to upload a new version of that document, or it would be overwritten by another upload (archive extracting or regular upload) an error message will be presented.

To allow version update, the cloud edit must be finished or canceled.

The cloud edit can be finished or canceled by the user who started it only. So if you open the more menu of a cloud edited document that you started, you will see the following extra options:

Other users won't be able to edit an already cloud edited document in the cloud, however they can "Open" the already cloud edited document.

While a document is edited in the cloud, other metadata can be edited on the item, status can be changed, comment can be added, etc. only the document related operations are prohibited.

Update a document from cloud

When you finished editing a document in the cloud, you can pull the changes from the document in the cloud or discard them.

To pull the changes, select the "Finish cloud editing" option from the more menu.

Please note that a Google authentication flow might be started if your authentication is expired or not done yet.

You can finish the cloud editing only if you are the one who started it.

After the loading finished, the document will be updated with the version pulled from the cloud.

If you want to discard the changes introduced in the cloud, select the "Cancel cloud editing" menu option.

Please note that a Google authentication flow might be started if your authentication is expired or not done yet.

You can cancel the cloud editing only if you are the one who started it.

What cancel does is it removes the document from the cloud but the changes won't be pulled before that and the document won't be updated. After cancel, the document will be the same as it was before starting the cloud edit.

After canceling or finishing a cloud edit, the document can be updated manually again.

Working together on a document in cloud

When a document is edited in the cloud, you can open it using the "Open in cloud". This option is visible not just for the user who started the cloud edit, but for other users too who has permission for this item.

When you click on the "Open in cloud" option, according to the permissions you have to that document, either the document will open or Google's request permission to the document page will appear.

Once a document is in the cloud, the permission management is up to the cloud so you can give/ask permission to edit the document to other users so you can work on the document together.

If you give permission to a user to edit the document in the cloud, that won't give the user permission to finish/cancel the cloud edit, these options are still only available to the user who started the cloud edit of the document.

Create a new Document by selecting a file from Drive

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 Google Drive.

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

Click on the "Upload from Drive" button on the upload dialog.

If you are not yet authenticated with your Google account, the authentication flow will start automatically on a new browser tab.

The selected file(s) will be created in the selected folder with the selected same name handling strategy (only present if duplication is not allowed).

Folder selection is not allowed on this dialog and the same restrictions apply to these files as to the regular file system files.

Multiple files can be selected here.

By clicking on the "Select" button, the transfer starts and a loading indicator appears. When the transfer is finished, the loading dialog disappears and the Documents will be present on the previously selected location.

Update an existing Document by selecting a file from Drive

The file selection from Google drive also works at a single Document replace. Open an existing Document and click on the Upload Document button:

This will open the upload dialog where again the Upload from Drive button will be present.

If you are not yet authenticated with your Google account, by clicking on the Upload from Drive button, the authentication flow will start automatically on a new browser tab.

Here from the appearing dialog, you can only select one file, because this is basically a file replacement.

By clicking on the "Select" button, the transfer starts and a loading indicator appears. When the transfer is finished, the loading dialog disappears and the Document will be replaced by the selected file from Drive.

Create new empty Google Documents

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

• Google Document (Docs)
• Google Spreadsheet (Sheets)
• Google Presentation (Slides)

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

The authentication flow might start on a new browser popup after the type selection, if you are not yet authenticated using your Google account.

After selecting the type, the name input popup appears where you have to enter the new blank document's name.

By default the documents will receive the .docx, .xlsx and .pptx extensions after creation.

If the name duplication is not enabled in the tracker configuration, here you do not have the option to select a name collision handling strategy, you should provide a name for the new document that does not collide any other document on the selected path.

If there would be a name collision, the creation will fail immediately.

The new document will land immediately in a state of cloud editing, so the cloud editable document will open on a new tab upon successful creation.

From this point, the behavior is the same on this document as a regular cloud edited document which already exists in the system.

Troubleshooting

The "double tap" rule is in charge when some error happens, refresh the browser, restart the process, try a second time.

Upon error a human readable reason for the error should be presented to the user, contact your system administrator with the error details, in critical cases, turn on the debug mode on the system admin settings, reproduce the error end send us the server logs.

If a Cloud edited document has been removed from your Google Drive (even from the trash), the cloud edit cannot be finished or canceled. In such cases, the cancel error message will contain a "force cancel" button with which the user can explicitly remove the cloud edit state from a document. In this case the document modifications won't be applied to the document.

Security

After Google authentication, the system will receive a token which is used to communicate with the Drive 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 (1-2week) period of time.

You can always go into your Google account settings and remove the permissions from the application:

The system is able to access (read-only) all your files in your Google Drive.

The system is able to create and remove the documents using your Google Drive that you chose to edit in cloud. This means that these files will be uploaded to your Drive while they are under cloud editing.

Limitations

According to the Google Drive API documentation the upload file size limit is 5120GB(?) but in reality using the Cloud edit feature, the office type documents that can be processed by Drive is roughly the following:

• Documents: 15-30MB
• Spreadsheets: 10-15MB

The creation of documents with larger size than this is highly difficult even on a desktop PC with high resources.

Furthermore, since the Office type documents are being converted to online editable Google type formats, in some cases if the document contains non-processable elements, the upload may fail.