Shelf Google Drive Connector Overview Guide


Document version history

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

11 March 2024

Active



























Document purpose

This document has been developed for those customers’ end users who are using Shelf Knowledge Management System (Shelf KMS) with the Content Integration Layer feature to manage and handle various content both stored in Shelf KMS and in external platforms integrated via CIL. The document’s goal is to answer the following questions:
  • What is the Shelf Content Integration Layer?
  • What purposes does this feature serve?
  • What is a Google Drive connector?
  • How is it configured?
  • How is it used in practice?
If you require further assistance, feel free to contact us at support@shelf.io or from the in-app chat support within the Shelf platform.

Glossary

Prior to starting to learn about the Google Drive connector and its configuration and usage, you need to learn the terminology used by Shelf.

Google Drive (https://drive.google.com) is a cloud-based file storage and synchronization service developed by Google, allowing users to store files online, access them from any device, and share them with others. Google Drive offers seamless integration with other Google services, such as Google Docs, Sheets, and Slides, facilitating collaborative document editing and real-time collaboration. For the purpose of this document, Google Drive is identified as an external content storage.

Shelf KMS (Shelf Knowledge Management System) is a knowledge management platform that employs AI capabilities to create, edit, process, store, export/import, and otherwise handle various content. The platform sports multiple AI-enabled features such as Search Copilot, Analytics Copilot, Semantic Search, Content Intelligence etc., all of which are intended to optimize and centralize customer organizations’ knowledge and provide fast, accurate, and consistent answers.

The Content Integration Layer (CIL) in Shelf Knowledge Management System (Shelf KMS) is a feature that allows for the seamless integration of various types and formats of content into the system. It enables users to import and organize content from various sources and knowledge repositories.

A connector is an entity that defines which external Content Management System Shelf KMS needs to connect to via Content Integration Layer (e.g. the Google Drive connector is a set of API parameters to define how to connect Shelf to Google Drive). Shelf KMS has a set of preconfigured connectors (Google Drive, Zendesk, Sharepoint, Confluence connectors, etc.) but also allows for creating the custom ones.

A connection profile is a feature that allows users to establish a connection to various external applications or sources. It enables seamless integration and collaboration between Shelf KMS and other platforms such as external content repositories. Using Shelf’s connection profiles, users can import and synchronize various content and generally streamline workflows between Shelf KMS and external systems. This feature enhances the overall efficiency and effectiveness of knowledge management processes by enabling easy access to relevant information from different sources within the Shelf platform.

A sync flow is a feature that is responsible for the synchronization of content from external sources to Shelf KMS. Shelf’s sync flows can work on schedule or on demand, making it a versatile tool for content synchronization and prompt knowledge delivery.

Credentials is a set of unique identifiers—such as a username and password—that enables a user to verify identity in order to log in to an online account. In our case, these are the client email and the private key, and described in the respective section below.


Prerequisites

For proper operation of your Google Drive connector and successful synchronization of your content from the Google Drive platform into Shelf KMS, the following preconditions must be met:

  • Admin Panel must be accessible on your Shelf KMS account
  • Google Service account must be created and Google Developer Profile must be configured. For more details about Google Service accounts and their creation, read the dedicated Google article
  • Content items (articles, documents, etc.) must be available in your Google Drive storage.




Content Integration Layer and its purpose

The Content Integration Layer feature makes it possible to integrate various content types and formats into a single platform, Shelf KMS, from where users can further derive useful information to deliver accurate and relevant answers to their clients.

The Content Integration Layer ensures that content is indexed, tagged, and categorized appropriately, making it easily searchable and accessible to users within the knowledge management system. It provides capabilities for content mapping, transformation, and synchronization, enabling the consolidation and synchronization of data from multiple sources.

CIL also ensures that the latest version of content is always available to users and facilitates efficient content updating and maintenance.

Overall, the Content Integration Layer plays a crucial role in providing a centralized repository of relevant and up-to-date information, making it easier for users to find and access the knowledge they need.

The detailed information about the CIL feature can be found in the relevant chapters of the Shelf Content Integration Layer Feature User Guide.


Understanding the Content Integration Layer workflow

In-depth configurations and use cases of the Shelf Content Integration Layer are described in the dedicated Shelf Content Integration Layer Feature User Guide mentioned above, but the short example of the CIL workflow is as follows:

  1. You access the Content Integration Layer feature in your Shelf KMS (Admin Panel).
  2. You select one of Shelf-preconfigured connectors or create your custom one (based on the external content repository from which you need to sync content)
  3. You create a connection profile that uses the selected or created connector, and configure it: indicate credentials (username/password/API key/token/etc.) to access your external repository. All these credentials and access details can be taken from that external platform, and in the respective section below we will show you how to get them on Google Drive.
  4. You create a sync flow that uses the created connection profile and configure this sync flow to run either on some specific schedule or on demand. It is here where you can apply filters to tell CIL which exactly content needs to be synced.
  5. You run the created sync flow manually (if set to run on demand) or wait for the scheduled run, and get your content from the needed external source right in Shelf KMS.

For the proper operation of the Google Drive connector to sync your content from Google Drive into Shelf KMS, you need to do certain actions both in Google Drive and in Shelf. Read the chapters below to learn what exactly you need to do.




Configurations on the Google Drive side

Configurations you need to perform in Google Drive anticipate generating access keys for your Google Service account, enabling access to the Google Drive API for your Google Service account, and, finally, sharing data stored in your Google Drive with your Google Service account. All these steps are described in the respective sections below, so feel free to start learning them.


Generating access key for Google Service account

Once you have created your Google Service account and logged in to it, your first step is to get a key that enables access to it for external systems such as Shelf KMS. To do so, follow the steps below.

  1. Open the Google Cloud Console and navigate to its menu.
  2. In the menu, find and select the IAM & Admin option, then select the Service Accounts option in the expanded submenu..

Figure 1. Accessing your Google Service account configurations in Google Cloud Console


3. In the next window, go to the KEYS tab and select the ADD KEY button at the bottom. Select the Create new key option from the dropdown menu.

Figure 2. Adding key for Google Service account


4. In the popup window that appears, select the type of the created key. JSON is recommended. Click Create.

Figure 3. Selecting key type


5. Select the folder where you want your new key to be saved on your local computer.

Figure 4. Saving key to local computer

The key is created and saved and is displayed in the list under the KEYS tab.

Figure 5. Viewing the created key in the list


Obtaining access credentials

Once you have created and saved your key for your Google Service account, you need to open the saved JSON file and obtain the private_key and client_email values from there. These values are needed for enabling Shelf KMS to access Google Drive.

Figure 6. Retrieving private_key and client_email from key JSON

❗Important: to avoid connection and data syncing errors at a later stage, make sure to copy the private_key value INCLUSIVE of -----BEGIN PRIVATE KEY----- and n-----END PRIVATE KEY-----\n.

Once these values are obtained, save them for further use.


Enabling Google Drive API

The next step is to enable Google Drive API for your Service account. This API allows you to access your Google Drive resources from external environments.

To enable it, go to the dedicated Google Cloud Console page and click the ENABLE button.

Figure 7. Enabling Google Drive API for your Google Service account

After enabling, Google Drive API is added to the list of enabled APIs and services for your Google Service account.

Figure 8. Viewing Google Drive API enabled for your Google Service account


Sharing Google Drive content with Google Service account

The final step of configurations on the Google side is to share the content stored in your Google Drive with your Google Service account.

To do so, perform the following procedure:

  1. Open your Google Drive storage and find the folder with content you want to have synced to Shelf KMS via the Google Drive connector.
  2. Right-click the folder to open its context menu and then select the Share options in it. Select Share again in the submenu that appears.

Figure 9. Sharing Google Drive folder


3. In the popup window that opens, in the text entry field, enter the email address you have obtained from the JSON file when creating the key for your Google Service account. Click Send to finish.

Figure 10. Sharing Google Drive folder with Google Service account

Once done, the selected Google Drive folder is now shared with your Google Service account, and the configurations on the Google side are successfully performed. You can now proceed to the configurations on the Shelf side as described in the sections below.


Configurations on the Shelf side

This chapter and its subsections describe the steps you need to take to get your Google Drive connector configured and ready for use.


Accessing Content Integration Layer

From the standard workflow described above you see that to start configuring and using your Google Drive connector you need to access the Content Integration Layer feature. To do so, perform the following steps:

  1. Log into your Shelf KMS account using valid credentials.
  2. Once logged in, go to the Admin Panel by selecting the respective option in the dropdown menu.

Figure 11. Accessing Admin Panel in Shelf KMS


3. In the Admin Panel window, you can see the left sidebar panel serving as a navigation menu to browse all the necessary components and their settings. One of these components is Content Integration Layer, consisting of three modules: Custom Connectors, Connection Profiles, and Sync Flows.

Figure 12. Accessing CIL modules in Admin Panel


Configuring Google Drive connector

In fact, no configurations are needed for your Google Drive connector. It is prebuilt and preconfigured by Shelf. You can see it in the connector list that appears once you select the Custom Connectors option in the Content Integration Layer section.

Figure 13. Viewing the Google Drive connector in CIL

What you need to do next is to create and configure a connection profile dedicated to work with the external content source such as your Google Drive folder.


Configuring Google Drive connection profile

The Google Drive connection profile is a feature that uses the prebuilt Google Drive connector and allows Shelf KMS to access, authenticate on Google Drive, and communicate with it to find and sync content stored there. But to enable its proper operation, you need to create and configure it as described in the procedure below.

  1. In the Admin Panel in Shelf KMS, go to the Content Integration Layer section, find and select the Connection Profiles option.
  2. In the Connection Profiles window that appears, you see the list of available connection profiles. Neither the prebuilt nor other custom connection profiles can be used for communicating with Google Drive, so you need to create a new connection profile. Click the Create Connection Profile button to start.

Figure 14. Accessing CIL connection profiles and starting creating new connection profile 


3. The Create Connection Profile page that opens is where you need to do all the configurations for the Google Drive connection profile you create. You need to indicate the connector (1) — Google Drive — to be used for the profile, add a name (2) and, if desired, some description (3) for your connection profile, and, finally, fill in the Runtime Settings (4) and Credentials (5) sections.

Figure 15. Configuring the Google Drive connection profile in Shelf

In the Runtime Settings section, you need to enter the client_email value you have retrieved from the JSON file when obtaining access credentials. In the Credentials section, you need to enter the private_key value you have received from the JSON file when obtaining access credentials.

❗Note:

Fields with the asterisk symbol (*) are mandatory. If they are left blank, you are not able to save the connection profile you are creating.


4. Once you have populated all the necessary fields in the form, click Create to save changes and finalize creating your Google Drive connection profile. When the connection profile is created and saved, it is displayed in the Connection Profiles list.

Figure 16. Viewing the created Google Drive connection profile in Shelf


Configuring Google Drive sync flow

Now that you have configured the Google Drive connector and connection profile, you need to create and configure the Google Drive sync flow. Sync flows are basically sets of instructions telling Shelf KMS what content and when it needs to pull from external sources, in our case - Google Drive.

To create and configure the Google Drive sync flow, perform the following steps.

  1. In the Admin Panel in Shelf KMS, go to the Content Integration Layer section, find and select the Sync Flows option.

Figure 17. Starting creating Google Drive sync flow


2. In the Create Sync Flow form that appears, select the needed connection profile from the dropdown list that opens if you click in the respective field. In our case - Google Drive CP. Add some title for your sync flow, and description if needed.

Figure 18. Configuring the Google Drive sync flow


3. You also need to tell Shelf how to run content synchronization: if you want it to be a scheduled procedure, select the On-schedule checkbox, and if it needs to be a manual procedure, select the On-demand checkbox.

Figure 19. Configuring the scheduled run of Google Drive sync flow


4. Finally, you can optionally add filters to apply to the content syncing from Google Drive into Shelf KMS. To do so, click Apply Filter and then select the filter type, criterion, and value. Read more about filters in Table 3 of the Sync Flows chapter in the Shelf Content Integration Layer Feature User Guide document.

Once done, click the Create button to finish your Google Drive sync flow creation.


Running Google Drive sync job

Once you have created the Google Drive sync flow, you can either wait until it performs the content sync per schedule (if you have selected the On-schedule option for the sync flow run type), or start the sync manually at any time (if you have selected the On-demand option for the run type).

To manually start syncing your content from Google Drive into Shelf, follow the below steps.

  1. Open the newly created Google Drive sync flow, find and go to the Jobs tab in its window.
  2. In the tab window, find and click the Trigger Now button to start syncing content.

Figure 20. Manually running content syncing from Google Drive into Shelf


3. In the popup window that appears, confirm the sync start by clicking the Sync button.

Figure 21. Confirming the sync start


4. Once done, the sync job is started and becomes visible in the list of sync jobs.

Figure 22. Viewing the running Google Drive sync job

❗Note:

The sync job can be triggered manually both for the on-schedule and on-demand sync flows, unless there is a sync job running at that time. 

In the first case, the manually triggered job overrides the schedule set for the sync flow. At the same time, the sync flow execution will resume to occur per schedule after the manually triggered sync job is finished. If you manually trigger the sync flow job, it starts immediately.

If there is a running sync job in this sync flow when you attempt to start a new job, this new job will not be created and, respectively, the content sync will not be started. In this case you will see the error message informing that the job is already running. 

If there are no other sync jobs running in this sync flow, the Jobs tab window refreshes, and a new job with the IN PROGRESS status appears in the table grid.


5. While the job is running, you can stop it by accessing its More Actions menu and selecting the Stop option in the dropdown list as shown below.

Figure 23. Stopping the sync job


Checking syncing results

Once the sync job triggered manually or on schedule is finished, you will see it to change the status to SUCCESS (if the sync was successful) or FAILED (if some issues occurred during the sync). In the latter case, check your configurations in the Google Drive connection profile and sync flow and rerun the sync job.

Figure 24. Viewing the successfully completed sync job

If the sync was successful, you can see the recently sync content directly from this window. To do so, open the Recent Sync tab and check the content items synced from Google Drive into Shelf.

Figure 25. Viewing the recently synced content from Google Drive

Note that the tab shows not more than 50 content items, so if you have synced more items, you will see them only after going back to the Shelf KMS Homepage and selecting the respective source - Google Drive.

Important:

When checking whether your content has been successfully synced, note that the sync flow you have created and the sync job you have triggered and run work for this specific Google Service account configuration, that is for a folder or folders stored on your Google Drive and shared with your Google Service account. It means that if you share a new Google Drive folder with your Google Service account, the existing configuration of this account is considered outdated. As a result, rerunning the sync job does not sync this new folder and content stored in it. To counter this, you need to create a new sync flow and run its sync job. In this case, your new content is successfully synced with Shelf KMS.


Configuring Google Drive permissions in User Groups

Even when you successfully configured the Google Drive connector, connection profile, sync flow, run the sync job and pulled the content from your Google Drive repository, you need to add Google Drive collections to the permitted sources via Shelf’s User Groups feature. Otherwise, you will not be able to search for the synced content and otherwise manage it in Shelf KMS.

To set the mentioned collection permissions, go back to the Admin Panel where find and select the User Groups option in the left sidebar menu. Select the needed user group from the list to open it.

Figure 26. Accessing User Groups in Shelf

In the selected user group window that opens, go and select the Collection Permissions tab. Once it opens, click the Add Collection button.

Figure 27. Starting to set Google Drive collection permissions in Shelf

In the form that opens, find and select the needed Google Drive collections you want to allow.

Figure 28. Selecting Google Drive collections

Confirm your choice by clicking the Add button. Once the collections are added, they appear in the list.

Figure 29. Viewing the added Google Drive collections

Once done, you are finished with all the configurations needed to sync content from Google Drive into Shelf KMS using the Google Drive connector.




Viewing Google Drive resources in Shelf

After completing all the configurations on your Google Drive connector and associated features and options, you can now view and work with the content synced into Shelf KMS from your Google Drive repository.

Go back to Shelf KMS homepage and select Google Drive as the needed source in the navigation panel.

Figure 30. Viewing content synced from Google Drive into Shelf

Note that if you select any content item synced from Google Drive it will open in Google Drive not in Shelf KMS.

Figure 31. Viewing content item in Google Drive

Now, you can enjoy all the benefits, including the AI-enabled features such as Search and Analytics Copilots, of Shelf KMS in relation to your content synced from Google Drive.

In particular, you can filter this content using the Collections filter in Shelf KMS’s advanced search, as shown in the figure below.

Figure 32. Searching the synced content using the Collections filter in Shelf KMS search

You can also search across the articles synced from Google Drive by title, description, and content (keyword(s) or phrase(s)). You can use virtually all the capabilities of Shelf KMS in relation to searching, viewing, and managing content synced from Google Drive.

Figure 33. Viewing the search results for Google Drive articles