HaloITSM

HaloITSM Guides

Documentation to assist with the setup and configuration of the HaloITSM platform

Guides > Confluence Integration

Confluence Integration

In this guide we will cover:

- How to connect the Confluence integration

- How to use the integration

- Viewing Articles from Confluence in the Portal


The Confluence integration is used to import and update knowledge base articles from Confluence into Halo. Allowing you to use the formatting tools available in Confluence but be able to view the articles in your Halo. This uses single directional webhooks, so changes made to articles (pages) in Confluence will update the article in Halo almost instantly. 


Connecting to Confluence

First head to configuration > integrations and ensure the Confluence module is enabled. 

Fig 1. Enable module


Open the module and select 'Add/Edit Accounts' > new, this will allow you to configure a new connection. 


Complete the fields on the details tab. In the 'Name' field give the connection a name. In the 'URL' field enter your Confluence instance URL. In the 'Email' field enter the email you use to log in to Confluence. In the 'API key' field you will need to enter an API key from Atlassian.


To obtain the API key head to https://id.atlassian.com/manage-profile/security/api-tokens and log in to your account. Form here select 'create API token', give it a name and create. Copy the token to a clipboard. 

Fig 2. Generate AI token in Atlassian


Head back to Halo, paste the API key into the API key field. Save the changes and hit 'test configuration' to check you have connected successfully. See figure 3 for reference on how the connection details should look.

Fig 3. Confluence connection details example


Now you will need to import the 'Spaces' from Confluence. FAQ Lists in Halo are the equivalent of Confluence Spaces, when importing spaces they can either be mapped to an existing FAQ list in Halo, otherwise they will create a new FAQ list. To map a space to an FAQ List, add a mapping to the table and select the Halo FAQ list and the Confluence space you would like to map together. 

Fig 4. Mapping Spaces to FAQ Lists


The example in figure 4 shows the spaces 'Asset Articles' and 'Email Troubleshooting' will be linked to existing Halo FAQ lists, so any pages imported from confluence that come under these spaces will be imported to the mapped Halo FAQ lists. 


Now you can 'Import FAQ Lists'. Any spaces you import that are not mapped will create a new FAQ list in Halo. If you would like to not import certain spaces, de-select these on the import screen. 

Fig 5. Importing Confluence Spaces


In figure 5 the first two spaces are not selected so will not be imported. I did not create a mapping for the 'How to make a change request' space so this will create a new FAQ list in Halo then automatically add this to the mapping table.


Now you can import your pages from Confluence. To import pages head to the 'Knowledge base article' tab within the integration configuration page and select 'Import Knowledge base articles'. Knowledge base articles are the Halo equivalent of Confluence pages, so pages will be imported as knowledge base articles into Halo. The articles will be imported under the FAQ list that is mapped to the article's Confluence space.


Note: If a Confluence page is under a space that has not been mapped to an FAQ list in Halo, the page will not be imported. 


To have the articles create/update automatically you will need to create a webhook, to do this select 'Create webhook', this will create webhook in Halo in the background so you will not see any changes in the UI. 


Once created you can make changes to your pages in Confluence and these changes will update the article in Halo. In the 'Inbound Requests' tab in the integration configuration you can see all the requests that the webhook has processed. If a page is created that has not yet been imported to Halo, it will be created in Halo automatically (provided the space the page is under is in the mapping table).


Using the integration

Once articles have been imported these will appear in the 'Knowledge base' module in Halo, under their associated FAQ list. If the articles have any visibility settings against them in Confluence this will not carry across to Halo, so after import everyone will be able to view the article. If you would like certain articles to have visibility restrictions you will need to set this in Halo. You can restrict agent access to the article by editing the article and entering the teams that you would like to have access (see figure 6). 

Fig 6. Teams that can access an article


You can also restrict which customers and top levels can view the article by editing the article, see figure 7.

Fig 7. Restrict Customer/Top Level access to an article


You can also restrict access using the FAQ list, for more information on how to do this see our guide here.


Any articles that have been imported from Confluence will not be able to have their title or body be edited in Halo, changes can only be made in Confluence. When viewing the article there is a shortcut to open the article Confluence, see figure 8.


Fig 8. Open article in Confluence


Viewing Confluence articles in the Portal

If Confluence has created some some new FAQ lists in your Halo you will first need to ensure that these FAQ lists are set to be visible on the portal. To do this head to configuration > knowledge base > FAQ lists > select the FAQ list. Here, you can set the FAQ list to be visible for all users or choose the customers/user roles that can see this. Note, you can allow access to an FAQ list but restrict user access on individual articles. 

Fig 9. FAQ list configuration


Once the articles are visible in the portal they will appear as they do in Halo, however, you can set the articles to open in Confluence when selected. To do this head to configuration > integrations > confluence, enable the setting shown in figure 10. 

Fig 10. When accessing an article imported from Confluence in the User portal, open it in Confluence instead


When enabled, the knowledge base area of the portal will function as usual, but if the user selects an article that has been imported from Confluence this will open the article in Confluence in a new tab. The Halo version of the article will still appear in the original self-service portal tab. 


Please note some formatting and content may not exactly match what is displayed in Confluence.



Popular Guides

Pin It on Pinterest