<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><p><span style="font-size: 14px;"><strong>In this guide we will cover:</strong></span></p><p><span style="font-size: 14px;"><strong>- What is the Confluence Integration?</strong></span></p><p><span style="font-size: 14px;"><strong>- Connecting to Confluence</strong></span></p><p><span style="font-size: 14px;"><strong>- Using the Integration</strong></span></p><p><span style="font-size: 14px;"><strong>- Viewing Confluence Articles in the Portal</strong></span></p><p><br></p><p><br></p><p><span style="font-size: 14pt;"><strong>What is the Confluence Integration?<br></strong></span></p><p><span style="font-size: 14px;">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. </span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 18px;"><strong>Connecting to Confluence</strong></span></p><p><span style="font-size: 14px;">First head to Configuration > Integrations and ensure the Confluence module is enabled. </span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjgyNzdkYjBiLTk1OTQtNDU5ZC1hOGM2LTkwYzcxNDk3ZGM0NCJ9.MmLaKOK1WGRa6JbPommuejFNcamWurjtR-EQOhz7MPk" class="fr-fic fr-fil fr-dib" width="184" style="width: 186px; height: 171.753px;" height="172"></span></p><p><span style="font-size: 10pt;"><strong>Fig 1. Enable module.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">Open the module and select 'Add/Edit Accounts' > new, this will allow you to configure a new connection. </span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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 (This user needs to have access to the spaces you are trying to import into Halo, if not you may receive a 404 error during authentication). In the 'API key' field you will need to enter an API key from Atlassian.</span></p><p><br></p><p><span style="font-size: 14px;">You will need to obtain and use a Classic API key, the integration does not support the use of scoped API tokens. </span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">To obtain the API key head to <a data-fr-linked="true" href="https://id.atlassian.com/manage-profile/security/api-tokens" id="isPasted">https://id.atlassian.com/manage-profile/security/api-tokens</a> and log in to your account. Form here select 'create API token', give it a name and create. The token created will inherit the permissions from the user that generates it, therefore an administrator will need to generate the token for it to have sufficient permissions. However, we do recommend creating a service user with these permissions to generate the API token against. Copy the token to a clipboard. </span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE0NzliOGIzLTFiNGEtNGNkMC1iNzA1LTRhOTRjZThmMzc3NyJ9.kKObNV38zGtJMBhH_vAfKH3UQlpruJqIyaIAa1IjnIw" class="fr-fic fr-fil fr-dib" width="1188" style="width: 1190px; height: 381.099px;" height="381"></span></p><p><span style="font-size: 10pt;"><strong>Fig 2. Generate AI token in Atlassian.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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 <strong>Fig 3</strong> for reference on how the connection details should look.</span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijg3ZThmNGVkLWRiOTUtNDU5Mi1iNTA2LTFmMTQ4YWM3NTk1ZCJ9.o-i8aqDjW4bh3o6oJvzwKMPn7uP8dBDf6xx3zxxXEYU" class="fr-fic fr-fil fr-dib" width="1208" style="width: 1210px; height: 504.622px;" height="505"></span><br></p><p><span style="font-size: 10pt;"><strong>Fig 3. Confluence connection details example.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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.</span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI2ZjVkY2FiLWJiMzQtNDRkYS05MGJhLTU2ZmEwZWYxZmE5YyJ9.DhGNc4D9Z1Cd78JYfUrhDe8w7xwi9Ef20Hk3lu9iNjg" class="fr-fic fr-fil fr-dib" width="1155" style="width: 1157px; height: 570.723px;" height="571"></span></p><p><span style="font-size: 10pt;"><strong>Fig 4. Mapping Spaces to FAQ Lists.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">The example in <strong>Fig 4</strong> 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. </span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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.</span></p><p><span style="font-size: 14px;"> </span></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFhYjlhMTAzLWRhMjEtNDViZi1iYzY5LTBjZTNiM2JjMWQ1MyJ9.5A8hMHJVFDd5ZtQshHqk-SwYUYr5LE5S0R035Mt4jiY" class="fr-fic fr-fil fr-dib" width="1229" style="width: 1231px; height: 232.677px;" height="233"></span></p><p><span style="font-size: 10pt;"><strong>Fig 5. Importing Confluence Spaces.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">In <strong>Fig 5</strong> 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.</span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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.</span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;"><strong><em>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. </em></strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">To have the articles create/update automatically in Halo each time changes are made in Confluence, you will need to create a webhook. First enable the functionality by checking 'Allow Jira webhooks to be processed by Halo'. </span></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU2MWNmMzAwLTZmOGYtNGYzOS04ZTJiLTVjMjI1NjUwNTAyOSJ9.Gtcljsyv1bB0U6UFCBL8SpDS6YSnhtPEQVnwLwC3_YQ" class="fr-fic fr-fil fr-dib" width="851" style="width: 853px; height: 480.751px;" height="481"></p><p><strong><span style="font-size: 10pt;">Fig 6. Setup webhooks for article syncing</span></strong></p><p><br></p><p>You can set the authentication method used for the webhook too. </p><p><br></p><ul><li id="isPasted"><strong>Use a token query parameter:</strong> When this option is selected you will be provided a secret token for the webhook created. Then enter this token in the 'token' field in Halo. When Halo creates the webhook this token will be included in the Webhook URL (as a parameter) automatically, this parameter will be checked by the Halo API before the webhook is processed. This will prevent any other webhooks sent to this endpoint being processed, adding an additional layer of security. </li><li><strong>No authentication:</strong> When selected no webhook authentication will take place, a token for the webhook does not need to be generated but this is a less secure method. </li></ul><p><br></p><p>If you are using a token query parameter to authenticate the webhook, any time the secret value is changed you will need to re-create the webhook to ensure the webhook contains the new secret. </p><p><br></p><p><span style="font-size: 14px;">To create the webhook select 'Create webhook', this will create a webhook in Halo in the background so you will not see any changes in the UI. </span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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).</span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14pt;"><strong>Using the Integration</strong></span></p><p><span style="font-size: 14px;">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 <strong>Fig 6</strong>). </span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkwMjdmZTE5LWY0ZjYtNDE5ZS1iM2Q2LWZmNmZkNDg2NGRiOSJ9.yN-okUNPAUjYvCnbqBUOQrlwu0PU1-zG1QtAKASK1Sc" class="fr-fic fr-fil fr-dib" width="1209" style="width: 1211px; height: 534.074px;" height="534"></span></p><p><span style="font-size: 10pt;"><strong>Fig 6. Teams that can access an article.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">You can also restrict which customers and top levels can view the article by editing the article, see <strong>Fig 7</strong>.</span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQ2NjM1NmExLWNhM2QtNDgwZC1iNDY1LTkxMTJmOWY2MGZkOSJ9.pBgeU_LZs4JAp6v8hVC1-xk6wX5IOeWsuZyefCmIPxo" class="fr-fic fr-fil fr-dib" width="1214" style="width: 1216px; height: 625.322px;" height="625"></span></p><p><span style="font-size: 10pt;"><strong>Fig 7. Restrict Customer/Top Level access to an article.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">You can also restrict access using the FAQ list, for more information on how to do this see our guide <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2044" id="isPasted" target="_blank" rel="noopener noreferrer"><strong>here</strong></a>.</span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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 <strong>Fig 8</strong>.</span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBiMjhiZTdkLWZmM2ItNDFlZi1iZmU1LTczNDA3MjhlZGFjZSJ9.t1EpH9heN1mZHZ3UekClSxhVyiLz_ZJb8-hOIfr_iVs" class="fr-fic fr-fil fr-dib" width="1218" style="width: 1220px; height: 299.649px;" height="300"></span></p><p><span style="font-size: 10pt;"><strong>Fig 8. Open article in Confluence.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 18px;"><strong>Viewing Confluence Articles in the Portal</strong></span></p><p><span style="font-size: 14px;">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. </span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM3ODg0YmJiLWZmZTQtNDExZi1iNjhjLTExY2E4MWY2ZTliNyJ9.o_yljgYNML4iIEud3Tbn8CUQz9BJHb5hn_Yu9-RmXo8" class="fr-fic fr-fil fr-dib" width="999" style="width: 1001px; height: 722.83px;" height="723"></span></p><p><span style="font-size: 10pt;"><strong>Fig 9. FAQ list configuration.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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 <strong>Fig 10</strong>. </span></p><p><br></p><p><span style="font-size: 14px;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE3MDQ3ZTE1LWRkM2EtNDFhMS1hMDM2LTJjZGFhMmMwM2ZkMyJ9.Yt-YjgR0cAgBDwASyv4wqECRQ9jl7DOcu6OjcjLEKGM" class="fr-fic fr-fil fr-dib" width="878" style="width: 880px; height: 436.41px;" height="436"></span></p><p><span style="font-size: 10pt;"><strong>Fig 10. When accessing an article imported from Confluence in the User portal, open it in Confluence instead.</strong></span></p><p><span style="font-size: 14px;"><br></span></p><p><span style="font-size: 14px;">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. </span></p><p><span style="font-size: 14px;"><br></span></p><p id="isPasted"><em><strong>Please note some formatting and content may not exactly match what is displayed in Confluence.</strong></em></p><p><br></p><p><br></p>
