HaloPSA

HaloPSA Guides

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

Guides > PagerDuty Integration

PagerDuty Integration

In this lesson we will cover:

- How to set up the PagerDuty integration 



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. 


IMPORTANT: This integration previously replied on NHServer, this is now depreciated and the integration can be setup using webhooks instead. 


Connecting to PagerDuty

First, head to configuration > integrations and enable the PagerDuty module.

Fig 1. PagerDuty module


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.


Head to PagerDuty > integrations tab > API access keys, hit create new API Key.

Fig 2. Create new API key (existing keys have been redacted here)


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


Now you have the key head back to the integration setup page in Halo and enter the key into the 'API Key' field.


Fig 3. PagerDuty setup page


Webhooks

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:

- Incident is created in PagerDuty

- Incident is acknowledged in PagerDuty

- Incident is resolved in PagerDuty

- Incident is re-opened in PagerDuty

- A note is left on a ticket in PagerDuty


 The webhooks will update the ticket in PagerDuty when the following events occur on the ticket in Halo:

- Ticket is created in Halo

- Ticket is responded to in Halo

- Ticket is resolved in Halo

- Ticket is re-opened in Halo

- A note is left on the ticket in Halo


To set the webhooks up set the 'Webhook Method' field to 'Webhooks'.


Now head back into PagerDuty > integrations > Generic Webhooks (v3) New webhook. 

Fig 4. New Webhook in PagerDuty


In the 'Webhook URL' field enter the following: https://YOURHALODOMAIN.com/api/notify/PagerDuty


Set 'Scope Type' to be 'service'. Then choose which service you would like this webhook to trigger for in the 'scope' field. 


Each checkbox in the 'event subscription' list will determine what events cause this webhook to post to Halo. Ensure the following events are checked:

  • incident.triggered
  • incident.acknowledged
  • incident.resolved
  • incident.reopened
  • incident.annotated

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. 


If you would like incident updates to sync for multiple services in PagerDuty you will need to create a webhook for each service. 


Now we have created the webhook in PagerDuty we will need to finish the setup on the Halo side. 


Service Mappings

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. 


Add a mapping to the table, set the fields shown in figure 5. 

Fig 5. Service mapping fields


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

Default Ticket type- This will determine what ticket type will be created in Halo when an incident under this service in PagerDuty is created. 

Default Agent- Will determine which agent is used to create an incident in PagerDuty when a ticket is created by a Halo user in the portal. 

User for new tickets- Will determine who is the end user of a ticket for tickets created in Halo from PagerDuty. 

Don't sync User created Tickets to PagerDuty - When enabled any tickets created by users (via email or the portal) will not sync to PagerDuty.

Description for new incidents - This will populate the description field of new tickets in Halo created from PagerDuty.

Webhook Signature - Paste the webhook signature copied earlier from the webhook here. 


Setting PagerDuty email 

Now you will need to head into your agent account > integrations tab, here there will now be a 'PagerDuty Email' field.


Fig 6. PagerDuty Email field against agent


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. 


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. 


Configuring Tickets to sync to PagerDuty

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. 


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.


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.


Head to configuration > tickets > ticket types > select your PagerDuty ticket type > field list, here you will need to add the following fields:

  • PagerDuty Service - This will allow you to select what PagerDuty service this ticket corresponds to.
  • Send To PagerDuty - When checked, this ticket will be sent to PagerDuty.

Fig 7. Field List for the ticket


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. 


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

Fig 8. Setting field visibility


Updating Incidents in PagerDuty from Halo

Once an incident is successfully created in PagerDuty, we can post many other updates across to the incident, including acknowledgements, resolutions and notes. Acknowledgments 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.


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.


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.


Configuring Actions to Sync to PagerDuty

Actions using the field 'Note' can be synced from Halo into PagerDuty, these will be stored as Notes in PagerDuty. 


Head to configuration > tickets > actions > new action > field list. Here, add the 'Note' and 'Send To PagerDuty' fields to the action.

Fig 9. Fields to add to action


You can add other additional fields to this action but only the 'Note' field will sync across. 


Note: Other note fields such as 'Private note' will not sync.


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. 


Now, when this action is used on tickets linked to a ticket in PagerDuty this note will now be synced across. 


Testing the Sync

Now we will walk through how to test the integration is successful. 


Create a new ticket in your Halo instance (the ticket type must contain the PagerDuty fields). 

Fig 9. Raising new ticket


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. 


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. 

Fig 10a. Note in PagerDuty

Fig 10b. Note in Halo


Lets try the other way. I will now create an incident for a service in PagerDuty.


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. 

Fig 11. Ticket created in Halo from PagerDuty


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. 

Fig 12a. Completing note action on ticket in Halo

Fig 12b. Note synced into PagerDuty 



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.  



Popular Guides