Shelf Confluence Connector Overview Guide


Document version history

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

16 Jan 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 Confluence 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 Confluence connector and its configuration and usage, you need to learn the terminology used by Shelf.

Shelf KMS (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 Confluence connector is a set of API parameters to define how to connect Shelf to Confluence). Shelf KMS has a set of preconfigured connectors (Contentful, 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.

An API key (or API token) is a unique identifier used to authenticate a user, developer, or calling program to an API (Application Programming Interface). Simply put, an API key is like a password that allows applications to communicate with each other. For the purpose of this document, API key is a unique identifier that allows Shelf KMS to access Confluence for content retrieval and synchronization.


Prerequisites

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

  • Admin Panel must be accessible on your Shelf KMS account
  • Settings menu must be accessible for you on your Confluence account
  • Content items (articles, documents, etc.) must be available on your Confluence account.




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 Confluence.
  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 Confluence connector to sync your content from Confluence into Shelf KMS, you need to do certain actions both in Confluence and in Shelf. Read the chapters below to learn what exactly you need to do.




Configurations on the Confluence side

First, to make the configurations described below, you need to have access to your Confluence settings page.

To check whether you have that access, once logged in to your Confluence account, click your profile picture and see whether the Settings option is available in the dropdown menu.

Figure 1. Accessing the Settings menu in Confluence

If the Settings option is not grayed out, you have access to it and are able to proceed to the next step, which is creating a Confluence API token.


Creating API token for your Confluence storage

Once you have confirmed your access to the Confluence settings, it is time to enable Shelf KMS access to your Confluence storage for content syncing.

To do so, you need to create a new dedicated API token specifically for Shelf KMS. For this purpose, follow the below steps.

  1. Go to the Settings page as shown in Figure 1 above.
  2. On the Settings page, under the Settings tab (opens by default), find and select the Password option.

Figure 2. Accessing the password parameters in Settings


3. On the page that opens, scroll down to find the API tokens section and click the Create and manage API tokens link button.

Figure 3. Accessing API token management page in Confluence


4. On the API Tokens page, you can see all your API tokens, if any. Even if you have any API token previously created, we recommend creating a new dedicated API token for Shelf purposes—it can prevent any unauthorized use of your Shelf Confluence integration by external people or systems. To start creating a new API token, click the Create API token button at the bottom.

Figure 4. Starting the API token creation procedure in Confluence


5. In the popup window that appears next, enter a label for your new API token. It can be any desired word or phrase you find appropriate. Once done, click Create.

Figure 5. Adding a label to the API token


6. Following that, your new dedicated API token is created. You can see it by clicking the eye icon. Click Copy to copy it to the clipboard or save to a local file for further use.

Figure 6. Viewing and copying the created API token


7. When you have copied and/or saved the API token, click Close to leave the window. You are redirected to the API Tokens page where you can see your newly created API token. From this page, you can later, if needed, revoke your API tokens, that is, cancel them so that the access to your Confluence resources they grant is no longer possible.

Figure 7. Checking the created API token

Once all the above steps are completed without errors or other issues, it means that you have successfully created the needed API token to authorize Shelf KMS to access your Confluence content. It also means the completion of all the configurations on the Confluence side.

Now, you can proceed to configuring your Shelf KMS.


Configurations on the Shelf side

This chapter and its subsections describe the steps you need to take to get your Confluence 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 Confluence 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 8. 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: Connectors, Connection Profiles, and Sync Flows.

Figure 9. Accessing CIL modules in Admin Panel


Configuring Confluence connector

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

Figure 10. Viewing the Confluence 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 Confluence instance.


Configuring Confluence connection profile

The Confluence connection profile is a feature that uses the prebuilt Confluence connector and allows Shelf KMS to access, authenticate on Confluence, 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 Confluence, so you need to create a new connection profile. Click the Create Connection Profile button to start.

Figure 11. Accessing CIL connection profiles and starting creating a new connection profile 


3. The Create Connection Profile page that opens is where you need to do all the configurations for the Confluence connection profile you create. You need to indicate the connector - Confluence - to be used for the profile, enter a desired name for the connection profile, and fill in the important details grouped under the Runtime Settings and Credentials sections. You can also add some description for your new Confluence connection profile in the respective field.

Figure 12. Configuring the Confluence connection profile in Shelf

In the Runtime Settings section, you need to indicate the URL of your Confluence instance, i.e. the storage where your content is kept.

In the Credentials section, the Email field, enter the email address you use to access your Confluence instance.

In the API Token field, respectively, you need to enter the API token you have previously created on the Confluence side.

âť—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 Confluence connection profile. When the system finishes creating the connection profile, you are redirected to the Connection Profiles page where you can see your newly created Confluence connection profile in the list.

Figure 13. Viewing the Confluence connection profile in the connection profiles list


Configuring Confluence sync flow

Now that you have configured the Confluence connector and connection profile, you need to create and configure the Confluence 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 - Confluence.

To create and configure the Confluence 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 14. Starting creating Confluence 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 - Confluence CP. Add some title for your sync flow, and description if needed.

Figure 15. Configuring the Confluence 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 16. Configuring the scheduled run of Confluence sync flow


4. Finally, you can optionally add filters to apply to the content syncing from Confluence 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 Confluence sync flow creation.


Running Confluence sync job

Once you have created the Confluence 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 Confluence into Shelf, follow the below steps.

  1. Open the newly created Confluence 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 17. Manually running content syncing from Confluence into Shelf


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

Figure 18. Confirming the sync start


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

Figure 19. Viewing the running Confluence 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 20. 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 Confluence connection profile and sync flow and rerun the 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 Confluence into Shelf.

Figure 21. Viewing the recently synced content from Confluence

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 - Confluence.


Configuring Confluence permissions in User Groups

Even when you successfully configured the Confluence connector, connection profile, sync flow, run the sync job and pulled the content from your Confluence repository, you need to add Confluence 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 22. 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 23. Starting to set Confluence collection permissions in Shelf

In the form that opens, find and select the needed Confluence collections you want to allow. A Confluence collection is in fact a Confluence space that was synced as a result of a sync job.

Figure 24. Selecting Confluence collections

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

Figure 25. Viewing the added Confluence collections

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




Viewing Confluence resources in Shelf

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

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

Figure 26. Viewing content synced from Confluence into Shelf

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

Figure 27. Viewing content item in Confluence

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 Confluence.

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

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

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

Figure 29. Viewing the search results for Confluence articles