• 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?

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.

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.

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

Figure 3. Accessing API token management page in Confluence

Figure 4. Starting the API token creation procedure in Confluence

Figure 5. Adding a label to the API token

Figure 6. Viewing and copying created API token

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.

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

Figure 9. Accessing CIL modules in Admin Panel

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 Custom 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

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 

Figure 12. Configuring the Confluence connection profile in Shelf

In the RUNTIME SETTINGS section, you need to indicate the URL of your Confluence instance (4), i.e. the storage where your content is kept.

In the CREDENTIALS section, the Email field (5), enter the email address you use to access your Confluence instance. 

In the API Token field (6), 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.

Figure 13. Viewing Confluence connection profile on connection profiles list

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.

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 14. Starting creating Confluence sync flow

   
   

3. In the CREATE SYNC FLOW form that appears, select the needed connection profile (1) from the dropdown list that opens if you click in the respective field. In our case—Confluence Connection Profile. Add some title (2) for your sync flow, and description (3) if needed. 

   Figure 15. Configuring Confluence sync flow

   
   

4. You also need to tell Shelf how to run content synchronization (4): 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 scheduled run of Confluence sync flow

5. Finally, you can optionally add filters (5) to apply to the content syncing from Confluence into Shelf KMS. To do so, click ADD FILTER and then select the filter type, criterion, and value.

   Figure 17. Viewing available filters for Confluence sync flow

   
   

   
   

• Space Keys: filters content synced from Confluence to certain Spaces only; can acquire the following criteria - in (for syncing only content that is stored in a Space indicated in the Value field) and not it (for syncing all content excluding items stored in a Space indicated in the Value field)

• Title: filters content items by their title; can have one of the following criteria - contains (syncs content items which title contains word(s) or phrase(s) indicated in the Value field), does not contain (syncs all content items other than those which title contains word(s) or phrase(s) indicated in the Value field), is set / is not set (syncs content items which title is set or not set to exact word(s) or phrase(s) indicated in the Value field)

• Label: helps filter out content depending on its label - if the in criterion is selected, content items with the label indicated in the Value field are synced, and if the not in criterion is selected, all content items other than those with the label indicated in the Value field are synced)

• Created: filters content items by the date/time when they were created; used with one of the available criteria: equal to (syncs content items created on a date indicated in the Value field), less than (syncs content items created before a date indicated in the Value field), and greater than (syncs content items created after a date indicated in the Value field)

• Last modified: filters content items by the date/time when they were last edited; used with one of the available criteria: equal to (syncs content items last changed on a date indicated in the Value field), less than (syncs content items last changed before a date indicated in the Value field), and greater than (syncs content items last edited after a date indicated in the Value field)

• Contributor ID: filters content by the identifier of contributor(s) who took part in creating that content; if the in criterion is selected, content items created with the participation of a contributor whose ID is indicated in the Value field are synced, and if the not in criterion is selected, all content items other than those created with the participation of a contributor whose ID is indicated in the Value field are synced)

• Contributor FullName: filters content by the full name of contributor(s) who took part in creating that content; if the contains criterion is selected, content items created by contributors whose full names are indicated in the Value field are synced, and if the does not contain criterion is picked, all content items other than those created by contributors whose full names are indicated in the Value field are synced.

Once done, click the Create button (7) to finish your Confluence sync flow creation.

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 by clicking on its name in the list or from its More actions menu (...).Figure 18. Opening sync flow
2. On the sync flow page, find and go to the Jobs tab.
3. In the tab window, find and click the Trigger now
    button to start syncing content. 

   

   Figure 19. Manually running content sync from Confluence into Shelf

4. In the popup window that appears, confirm the sync start by clicking the Sync button.Figure 20. Confirming sync start

5. Once done, the sync job is started and becomes visible in the list of sync jobs.Figure 21. Viewing 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.

   
   
   
6.  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 22. 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 Confluence connection profile and sync flow and rerun the sync job. 

Figure 23. Checking sync job status

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 24. Viewing recently synced content from Confluence

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 25. 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 collections button.Figure 26. 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 27. Selecting Confluence collections

Figure 28. Viewing added Confluence collections