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.

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.

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.

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

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 created key in the list

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.

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, find the Google Drive API option, and then click Enable.

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

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

Figure 10. Sharing Google Drive folder with Google Service account

Figure 11.  Confirming your Google Drive folder sharing with your 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.

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 12. Accessing Admin panel in Shelf KMS

3. On the Admin panel page, 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: Connection Profiles, Sync Flows, and Custom Connectors.

Figure 13. Accessing CIL modules in Admin panel

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. The table grid also shows that the Google Drive connector is of the Pull type, which means that it retrieves content from external sources into Shelf.

Figure 14. 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. 

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. On the CONNECTION PROFILES page that opens, 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 15. Accessing CIL connection profiles and starting creating new connection profile 

Figure 16. Configuring 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 17. Viewing created Google Drive connection profile in Shelf

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.

2. On the SYNC FLOWS page that opens and displays the list of available/created sync flows, find and click the Create sync flow button.

Figure 18. Starting creating Google Drive sync flow

Figure 19. Configuring Google Drive sync flow

4. 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 20. Configuring scheduled run of Google Drive sync flow

• contains: allows you to indicate that you want to sync only that content whose file name(s) contain(s) some specific text/words

• does not contain: lets you filter out all content excluding items whose file name(s) do(es) not contain certain text/words.

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

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 21. Manually running content syncing from Google Drive into Shelf

Figure 22. Confirming sync start

Figure 23. Viewing Google Drive sync job running

❗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 24. Stopping sync job

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 25. Viewing successfully completed sync job

If the sync was successful, you can see the recently synced 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 26. Viewing 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.

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 27. 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 28. 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 29. Selecting Google Drive collections

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

Figure 30. Viewing 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.