<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><strong>In this guide we will cover:</strong></p><p id="isPasted"><strong>- What is the PagerDuty Integration?</strong></p><p><strong>- How to set up the PagerDuty integration </strong></p><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">What is the PagerDuty Integration?</span></strong></p><p>PagerDuty can be integrated with your Halo instance to have incidents sync between PagerDuty and Halo. This integration syncs two-way so updates in Halo will sync over to PagerDuty and vice versa. </p><p><br></p><p><strong>IMPORTANT: This integration previously relied on NHServer, this is now deprecated and the integration can be setup using webhooks instead. </strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Connecting to PagerDuty</span></strong></p><p>First, head to Configuration > Integrations and enable the PagerDuty module.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJiZjZlMTQ0LTA4YWItNGFmYS05NTgxLWNkNjE5OTIyNTE4NiJ9.VTSrZapEUZ2AJCjxKZpmyl_ce5JDWjSQOrOQ1fLxhVk" class="fr-fic fr-fil fr-dib" width="154" style="width: 156px; height: 126.507px;" height="126"></p><p><strong><span style="font-size: 10pt;">Fig 1. PagerDuty module</span></strong></p><p><br></p><p>Once enabled open up the module to see the setup page. Here, you will need to enter an API key to connect to your PagerDuty instance.</p><p><br></p><p>Head to PagerDuty > integrations tab > API access keys, hit create new API Key.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAzMDBiNTFjLTY2N2YtNDkyMi1iYmZhLWJmOGZhN2RhMjFjMCJ9.n7xCyyiIcjpn4Q1uqhcXY7I_u5-SByQP6jAPRlai56k" class="fr-fic fr-fil fr-dib" width="1221" style="width: 1223px; height: 497.045px;" height="497"></p><p><strong><span style="font-size: 10pt;">Fig 2. Create new API key (existing keys have been redacted here)</span></strong></p><p><br></p><p>Give the key a name and ensure it has full access, once saved you will be given the key, copy and paste this onto a clipboard (once this window is closed the key will no longer be visible).</p><p><br></p><p>Now you have the key head back to the integration setup page in Halo and enter the key into the 'API Key' field.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQ0Njg4NjgxLTgxMjgtNDY1Ni04YWYyLWE5OGUyM2E1MmVkNCJ9.R-kXAgltTo47lw7OLRlhtqsPyAspouK88kc5JPiGzBg" class="fr-fic fr-fil fr-dib" width="1221" style="width: 1223px; height: 737.683px;" height="738"></p><p><strong><span style="font-size: 10pt;">Fig 3. PagerDuty setup page</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Webhooks</span></strong></p><p>Now we will configure the webhooks for this integration. The webhooks will update the ticket in Halo when the following events occur on the incident in Pager Duty:</p><p><br></p><p>- Incident is created in PagerDuty</p><p>- Incident is acknowledged in PagerDuty</p><p id="isPasted">- Incident is resolved in PagerDuty</p><p id="isPasted">- Incident is re-opened in PagerDuty</p><p id="isPasted">- A note is left on a ticket in PagerDuty</p><p><br></p><p> The webhooks will update the ticket in PagerDuty when the following events occur on the ticket in Halo:</p><p><br></p><p>- Ticket is created in Halo</p><p>- Ticket is responded to in Halo</p><p>- Ticket is resolved in Halo</p><p>- Ticket is re-opened in Halo</p><p>- A note is left on the ticket in Halo</p><p><br></p><p>To set the webhooks up set the 'Webhook Method' field to 'Webhooks'.</p><p><br></p><p>Now head back into PagerDuty > integrations > Generic Webhooks (v3) New webhook. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIxNzFhNWYwLWIwZDUtNDllOC04MDFiLTJmMjEzMmZkYjAwYSJ9.BfcdeKOrhfD7MdQCU4Z82ZeJe-H9kEuXJdt3V73H_HE" class="fr-fic fr-fil fr-dib" width="923" style="width: 925px; height: 604.408px;" height="604"></p><p><strong><span style="font-size: 10pt;">Fig 4. New Webhook in PagerDuty</span></strong></p><p><br></p><p>In the 'Webhook URL' field enter the following: <a data-fr-linked="true" href="https://woohooo123.halopsa.com/" id="isPasted">https://YOURHALODOMAIN.com</a>/api/notify/PagerDuty</p><p><br></p><p>Set 'Scope Type' to be 'service'. Then choose which service you would like this webhook to trigger for in the 'scope' field. </p><p><br></p><p>Each checkbox in the 'event subscription' list will determine what events cause this webhook to post to Halo. Ensure the following events are checked:</p><p><br></p><ul><li>incident.triggered</li><li>incident.acknowledged</li><li>incident.resolved</li><li>incident.reopened</li><li>incident.annotated</li></ul><p>Now hit 'Add Webhook, you will be given the webhook signature in the following popup, copy this to a clipboard as this will no longer be accessible once you close the window. </p><p><br></p><p>If you would like incident updates to sync for multiple services in PagerDuty you will need to create a webhook for each service. </p><p><br></p><p>Now we have created the webhook in PagerDuty we will need to finish the setup on the Halo side. </p><p><br></p><p><strong><span style="font-size: 14pt;">Service Mappings</span></strong></p><p>Now you will need to map a service in PagerDuty to a ticket type in Halo. This will determine what service an incident is logged against in PagerDuty when this ticket type is raised in Halo. </p><p><br></p><p>Add a mapping to the table, set the fields shown in figure 5. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE0ZTM0N2JmLTBmZTctNDU1MS04NzZiLWZmMDA2NTg1Zjg4MyJ9.J91A0e-6zGw25ATddJqYqNrNPMFjuJOyopTKJI61WY0" class="fr-fic fr-fil fr-dib" width="489" style="width: 491px; height: 634.562px;" height="635"></p><p><strong><span style="font-size: 10pt;">Fig 5. Service mapping fields</span></strong></p><p><br></p><p><strong>Service</strong> - This determines what service in PagerDuty this mapping relates to, when an incident for this service is synced into Halo the criteria in this mapping will apply. </p><p><strong>Default </strong><strong>Ticket </strong><strong>type</strong>- This will determine what ticket type will be created in Halo when an incident under this service in PagerDuty is created. </p><p><strong>Default </strong><strong>Agent</strong>- Will determine which agent is used to create an incident in PagerDuty when a ticket is created by a Halo user in the portal. </p><p><strong>User for new tickets</strong>- Will determine who is the end user of a ticket for tickets created in Halo from PagerDuty. </p><p><strong>Don't sync User created Tickets to PagerDuty</strong> - When enabled any tickets created by users (via email or the portal) will not sync to PagerDuty.</p><p><strong>Description for new incidents</strong> - This will populate the description field of new tickets in Halo created from PagerDuty.</p><p id="isPasted"><strong>Webhook Signature</strong> - Paste the webhook signature copied earlier from the webhook here. </p><p><br></p><p><strong><span style="font-size: 14pt;">Setting PagerDuty email </span></strong></p><p>Now you will need to head into your agent account > integrations tab, here there will now be a 'PagerDuty Email' field.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjdhMGE1N2FjLWY3YjgtNGExZS1iMmVhLWYxNDI4MzhiNjIxMCJ9.yIx6lJLVofOTGZo9TjX3-Ou9jAPoUTBu5mw1KCgh48M" class="fr-fic fr-fil fr-dib" width="473" style="width: 475px; height: 481.496px;" height="481"></p><p><strong><span style="font-size: 10pt;">Fig 6. PagerDuty Email field against agent</span></strong></p><p><br></p><p>Here, you will need to enter the email used for your user account in PagerDuty. If the agent who raises the ticket does not have this field set the sync will not be able to take place. </p><p><br></p><p>Each agent that raises tickets to be sent to PagerDuty will need to have this field populated as this allows PagerDuty to link the incident raised to the appropriate agent. </p><p><br></p><p><span style="font-size: 14pt;"><strong>Configuring Tickets to sync to PagerDuty</strong></span></p><p>Now you have set up the connection between Halo and PagerDuty you will need to add some additional fields to your ticket type to allow it to sync to PagerDuty. Alternatively you may want to create a new ticket type, specifically used for logging incidents to PagerDuty. </p><p><br></p><p id="isPasted">It is possible to send across both the source and severity of the issue to PagerDuty. The source can be synced by making your source field visible on the new ticket screen. There are then 4 severity values that can be synced. These are Critical, Warning, Error and Info. If a ticket is given a priority description matching one of these 4 values, the severity will be set accordingly.</p><p><br></p><p>If the incident is successfully created in PagerDuty, a field will be visible on the ticket highlighting the incident ID in PagerDuty. This is hyperlinked, so you can click this ID and the Incident will be opened in a separate tab.</p><p><br></p><p>Head to configuration > tickets > ticket types > select your PagerDuty ticket type > field list, here you will need to add the following fields:</p><p><br></p><ul><li>PagerDuty Service - This will allow you to select what PagerDuty service this ticket corresponds to.</li><li>Send To PagerDuty - When checked, this ticket will be sent to PagerDuty.</li></ul><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM1MDk3ZDM2LTY4YjEtNDRlOS04MGIzLWZhMzk2ODM2OWU5YSJ9.yMMN0M_LbIe0gFGZnthmszSTbvptzxQH2MoF-LR16xs" class="fr-fic fr-fil fr-dib" width="1053" height="422"></p><p><strong><span style="font-size: 10pt;">Fig 7. Field List for the ticket</span></strong></p><p><br></p><p>The 'Send to PagerDuty' checkbox is off by default and must be checked on to sync. To have this on by default head to the defaults tab within the ticket type and enable 'Send To PagerDuty'. You will also see a setting here to set the default service populated in the ' PagerDuty Service' field. </p><p><br></p><p>If you would like 'lock' the 'send to PagerDuty' checkbox on so these tickets are always synced, ensure the default is set to be on, then you can edit the field so that the field is visible to agents but cannot be edited (or you can hide the field altogether). </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjA0ODQxNDQ3LWY2NTgtNDY0My04MGZlLWIwMmM1MzNhN2VjNyJ9.IT1Ubr2cUbP7KwtX6KC51nTF5i2zEeMPi7bcZnfsAEA" class="fr-fic fr-fil fr-dib" width="519" style="width: 521px; height: 458.444px;" height="458"></p><p><strong><span style="font-size: 10pt;">Fig 8. Setting field visibility</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Updating Incidents in PagerDuty from Halo</span></strong></p><p id="isPasted">Once an incident is successfully created in PagerDuty, we can post many other updates across to the incident, including acknowledgements, resolutions and notes. Acknowledgements and resolutions happen automatically when a synchronized ticket is responded to or resolved in Halo. You will receive a message informing you whether or not this was successful.</p><p><br></p><p>Adding notes to incidents in PagerDuty is very similar to syncing the incident in the first place. To do this, you need to add the “Send to PagerDuty” field to any action you’d like to push the notes for.</p><p><br></p><p>If the notes field is blank, or your action does not use a notes field, then the action will not be posted. Notes can also only be synced by technicians who have an account with a matching email address in PagerDuty.</p><p><br></p><p><strong><span style="font-size: 12pt;">Configuring Actions to Sync to PagerDuty</span></strong></p><p>Actions using the field 'Note' can be synced from Halo into PagerDuty, these will be stored as Notes in PagerDuty. </p><p><br></p><p>Head to configuration > tickets > actions > new action > field list. Here, add the 'Note' and 'Send To PagerDuty' fields to the action.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQ4YzM4OTk0LTU0MzgtNDQwNi05MDRjLWJiOTQwNWU2YzY2MiJ9.aG_x4atzrJPowaoHY5_Hn69cqEU-yCXZMdCisgbm4Kw" class="fr-fic fr-fil fr-dib" width="850" style="width: 852px; height: 413.634px;" height="414"></p><p><strong><span style="font-size: 10pt;">Fig 9. Fields to add to action</span></strong></p><p><br></p><p>You can add other additional fields to this action but only the 'Note' field will sync across. </p><p><br></p><p><strong><em>Note: Other note fields such as 'Private note' will not sync.</em></strong></p><p><br></p><p>Then head to the defaults tab and enable 'Send To PagerDuty'. Now just ensure this action is on the workflows for the ticket type it will be used on. </p><p><br></p><p>Now, when this action is used on tickets linked to a ticket in PagerDuty this note will now be synced across. </p><p><br></p><p><strong><span style="font-size: 14pt;">Testing the Sync</span></strong></p><p>Now we will walk through how to test the integration is successful. </p><p><br></p><p>Create a new ticket in your Halo instance (the ticket type must contain the PagerDuty fields). </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJjN2M1YjFjLTdhNjMtNGUxNi05OGM3LTZkZjQ2YTcxZDM5NSJ9.nhXRUFTKJixjrIsHpLMPXBGr4GqZh2Q7b_tmLS0FUko" class="fr-fic fr-fil fr-dib" width="1218" style="width: 1220px; height: 510.954px;" height="511"></p><p><strong><span style="font-size: 10pt;">Fig 9. Raising new ticket</span></strong></p><p><br></p><p>In the figure 9 example you will see I have chosen which PagerDuty service this ticket relates to and enabled the 'send to PagerDuty' checkbox. Once I submit the ticket a pop-up containing 'New Incident created in PagerDuty' will appear. </p><p><br></p><p>If I head into my PagerDuty I can see an incident has been created under this service. If I leave a note on this incident in PagerDuty, this will be synced back to Halo. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBlNWE2MmE4LTgyMWUtNDAzZS05NDY3LTM2YWY1NWFlODg3OCJ9.qcHJOmLKSWaTIXYr5paBk73x73V1rxX0_nhi7G3W7Dk" class="fr-fic fr-fil fr-dib" width="1208" style="width: 1210px; height: 440px;" height="440"></p><p><strong><span style="font-size: 10pt;">Fig 10a. Note in PagerDuty</span></strong></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZlYTllODg1LThlNTYtNDlkMy05ODJmLThhZDE4YjNlNDZjNCJ9.PfZtjzA18ieXr-OqPRP58Dap4Jg-8pZyA16F5pRCJi8" class="fr-fic fr-fil fr-dib" width="838" height="444"></p><p><strong><span style="font-size: 10pt;">Fig 10b. Note in Halo</span></strong></p><p><br></p><p>Lets try the other way. I will now create an incident for a service in PagerDuty.</p><p><br></p><p>A ticket has been created in my Halo for this incident. The ticket has ticket type alert and is assigned to 'General User' as this is what I specified in my service mappings. The assigned team and agent for the ticket will be taken from the ticket type. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImY0YWQ3NTA5LTJkMmItNDRlMC1hZjdhLTgxMTgwYmU3OTMzZCJ9.rATqgWN9nyzaZ0SRlUns_0cxBGJ9eZA4E6XWFI5GT70" class="fr-fic fr-fil fr-dib" width="1217" style="width: 1219px; height: 524.178px;" height="524"></p><p><strong><span style="font-size: 10pt;">Fig 11. Ticket created in Halo from PagerDuty</span></strong></p><p><br></p><p>Now if I complete a note action on the ticket in Halo, this will add a note to the incident in PagerDuty. (Ensure the action you are using has the 'Send To PagerDuty' field set. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI0Y2NiNzI4LWU5MzktNGI3ZS04MmI5LTc4NzQ0NTdhODIyMyJ9.uloE0mP-jsKeuHEwGRYV1X5_OKQnkuGDAgNDRAKYjao" class="fr-fic fr-fil fr-dib" width="1104" height="440"></p><p><strong><span style="font-size: 10pt;">Fig 12a. Completing note action on ticket in Halo</span></strong></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI1MWViY2EyLTMwNmItNDE0ZC05ODFlLTQyNDJlNDdiNDU1YiJ9.3qlaGIxL7nkP6hEbK5vSFHqMJWiYYRK0Upd4kocrmdI" class="fr-fic fr-fil fr-dib" width="1214" style="width: 1216px; height: 490.132px;" height="490"></p><p><strong><span style="font-size: 10pt;">Fig 12b. Note synced into PagerDuty </span></strong></p><p><br></p><p><br></p><p><strong><em>Note: The webhooks in PagerDuty do contain a 'Test' functionality, we do not recommend testing this way as this will not create a ticket in Halo for an incident. </em></strong></p><p><br></p><p><br></p>
