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
- 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?
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:
- You access the Content Integration Layer feature in your Shelf KMS (Admin Panel).
- 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)
- 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.
- 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.
- 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.
- Open the Google Cloud Console and navigate to its menu.
- 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
Figure 2. Adding key for Google Service account
Figure 3. Selecting key type
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:
- Open your Google Drive storage and find the folder with content you want to have synced to Shelf KMS via the Google Drive connector.
- 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
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:
- Log into your Shelf KMS account using valid credentials.
- 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
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.
- In the Admin Panel in Shelf KMS, go to the Content Integration Layer section, find and select the Connection Profiles option.
- 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
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.
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.
- 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
Figure 18. Configuring the Google Drive sync flow
Figure 19. Configuring the scheduled run of Google Drive sync flow
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.
- Open the newly created Google Drive sync flow, find and go to the Jobs tab in its window.
- 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
Figure 21. Confirming the sync start
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.
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