Before you can configure the integration within Halo, there are a few required PagerDuty configuration steps that must be completed first.
The first thing that we need to generate in PagerDuty is an API Key so that Halo can contact the PagerDuty. To generate a new API Key, go to Configuration > API Access. Press the Create New API Key button to generate a new key:
Give your key a sensible name, and ensure that the key is not read only. Once happy, hit save, and your key will be revealed. Make a note of this, as you will not be able to obtain the key value again after leaving this screen.
The integration connects your Halo instance to a service in PagerDuty. You can connect to a pre-existing service, or create one especially for the integration. Although we won’t go into much detail here, your existing services can be managed in Configuration > Services. You can also create new services from here should you need to.
Below is the configuration that must be carried out in Halo to facilitate this integration.
To enable the PagerDuty integration in Halo, go to Configuration > Integrations, and enable the module. Once the module has been enabled, click the menu icon for the module to begin configuring it.
The first option that must be completed is the PagerDuty API Key. In order to obtain a PagerDuty API Key, please follow the previous steps in this guide under the PagerDuty configuration heading.
The second option is the default ticket type for the integration. When a new incident is created in PagerDuty against the service you are connected to, a new ticket will be logged in Halo using this value as the ticket type for the new ticket.
The third option requires you to choose a default agent. This option has been added so that if you choose to allow end users to send tickets to PagerDuty from the end user portal, this default Agents email address will be used to log the Incident in PagerDuty. The email address of the default agent must match the email address of an Agent in PagerDuty.
The integration relies on being connected to a chosen service that you have created in PagerDuty. Once you have input your API Key, the service dropdown field will be populated with all of your available services from PagerDuty. Simply choose the service you’d like Halo to be connected to in order to complete this step.
Sending Incidents to PagerDuty
Now that you’ve connected Halo and PagerDuty you can begin to pass data between the systems. To be able to send an incident to PagerDuty, we need to add a field to the new ticket screen. You can do this on as many ticket types as you wish by going to Configuration > Tickets > Ticket Types > Edit > Field List.
Note: You will also need to set the "Default PagerDuty Service" in the defaults of the ticket type for tickets to post to PagerDuty:
Once added, when creating a new ticket of this type, make sure the “Send to PagerDuty” option is checked on the new ticket screen. The application will try to post this immediately. You will receive a message informing you of the success/failure of the post. For any post that fails, the NHServer program will attempt to post this again in the background.
It is also possible to send across both the Source and Severity of the issue to PagerDuty. The source can be synced by making your Source field (the one chosen in earlier configuration steps) 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.
If the incident is successfully created in PagerDuty, we can now 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. This can be done in Configuration > Tickets > Actions > Edit > Field List. Once configured, when performing this action, ensure the “Send to PagerDuty” checkbox is checked, and the action will be posted to PagerDuty.
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.
Syncing Incidents to Halo
By enabling the PagerDuty module and connecting to a service, the NHServer application will automatically start searching for open Incidents logged in PagerDuty that do not exist in Halo. When found, new tickets will be created using the default ticket type specified earlier in the setup.
If an Incident is found in PagerDuty with a resolved status, and a corresponding ticket in Halo is still open, the ticket will be automatically closed in Halo.
Turning Emails into Incidents
It is possible to turn incoming emails into Incidents in PagerDuty. To do this, you need to create a new email rule with type “Help Request”. By enabling the following setting, whenever an incoming email matches the rule you’re creating and creates a ticket, the ticket will then be pushed into PagerDuty. The email address of the default agent you specify must match the email address of a technician in PagerDuty, as this is used to create the Incident.