How to use the Web API tile with PagerDuty

This article covers how to use the Web API tile to display live API data from PagerDuty on a dashboard or perspective.

SquaredUp uses the PagerDuty account that you configure, and queries will be updated as the page updates, by default every minute.

This article covers several areas:

1. Adding a PagerDuty provider in SquaredUp
2. Walkthrough: Adding a Web API tile to a dashboard to show PagerDuty alerts
3. Walkthrough: Adding a Web API Scalar tile to a dashboard to show PagerDuty incident counts

Prerequisites

• The SquaredUp server must have access to your PagerDuty instance, since it is the server that connects to PagerDuty, and not your users' browser.
• If you use a proxy server you may need to configure the proxy to allow the SquaredUp server to communicate with PagerDuty.
• A PagerDuty account. You may need some help from a PagerDuty admin to get an account with the correct privileges.

Adding a PagerDuty provider in SquaredUp

Before you configure the tile you need to create a PagerDuty provider in SquaredUp.

Adding a provider is a one-time configuration task, and once the provider has been configured it can be used each time you configure a tile.

For PagerDuty the provider must be created as a simple provider, as described below:

1. Log on to SquaredUp and navigate to the right-hand menu ☰ then system and then click on the web api perspective.
2. Click Add new provider.

3. Leave the provider type as simple

4. In the service name box type in a suitable name, e.g. PagerDuty

5. The base URL should be the current PagerDuty API URL, for example:
   https://api.PagerDuty.com/

6. Under default headers click add
   
7. Add the following information to the boxes as shown below:
   
   First box (name): authorization
   Second box (value): Token token=<API token from PagerDuty>
   
   You can create an API access key (token) by logging in to PagerDuty > Developer Tools (top right) > API Access > Create New API Key, and ticking Read-only API Key.
   
   Copy the API access key from PagerDuty before closing the window:
   
   Paste into the authorization value box in SquaredUp, prepended by Token token= as shown above.
8.  Click add provider.

Walkthrough: Adding a Web API tile to a dashboard to show PagerDuty alerts

It is important to use http get mode and to set the key path in the response data section to alerts. This is described in the steps below.

1. On the top navigation bar in SquaredUp click the + to create a new dashboard, and give your dashboard a title.

2. Click on the Web API tile.
   
   

3. Select Web API (Grid).
   
   

4. Leave the scope section blank for this walkthrough.

5. In the provider section select the PagerDuty provider that you created earlier.

   

6. In the http mode section leave the http method set to get.

7. Type alerts in the box after the URL. The URL shown here is the URL you specified when you created the PagerDuty Web API provider.
   

8. In the response data section type alerts into the box.

   
   At this point you should see some data returned.

9. Click next to move to the grid columns section.

10. Click hide next to some of the columns you might not wish to show, e.g. id, type, summary, self, html_url, resolved_at, alert_key, suppressed, service, incident, first_trigger_log_entry, body, integration, privilege.
11. You may like to rename the columns to make them more readable, e.g. created_at to Created, status to Status and severity to Severity
    
12. To make the created date and time more readable you can use mustache syntax with timeago in the custom template. Click edit next to Created and paste the following in to the custom template box:

    {{timeago(value)}}

    This shows how long ago the alert occurred.
    
    
    You may like to add further columns for additional data. For help customizing the columns of data see How to use the Grid designer when configuring tiles.

13. Click Add, give the column a name, such as Service, and in the custom template box click the mustache helper button  and select the value you require, for example {{value.service.summary}} then click done. Leave data key path empty.
    
    

14. Other columns you might like to add include:
    name: Message with custom template: {{value.body.cef_details.message}}
    name: Website with custom template: {{value.body.cef_details.details.hostname}}
    name: Related Incident with custom template: {{value.incident.summary}}

15. You may wish to change the order the columns by dragging them into position.
    
16. The Grid Options Row Link property allows you to automatically link each row to a parameterised hyperlink. Click on the mustache helper button and then select {{incident.html_url}} from the drop down list.
    
17. Click done.
    
    

Walkthrough: Adding a Web API Scalar tile to a dashboard to show PagerDuty incident counts

It is important to use http get mode and to set the key path in the response data section to incidents.

1. Click the orange plus button to add a new tile to the dashboard.

2. Click on the Web API tile.
   
   

3. Select Web API (Scalar).
   
   

4. Leave the scope section blank for this walkthrough.

5. In the provider section select the PagerDuty provider that you created earlier.

6. In the http mode section leave the http method set to get.

7. In the box following the URL you need to type incidents 
   
   

8. The headers & data section is where you can pass key variables through to PagerDuty. Click the add button under data to add the following data name and value settings:
   name: statuses%5B%5D value: resolved
   

9. In the response data section, type incidents into the box, and a number will show in the tile.

   

10. Click next to move to the scalar section where you can change the font size if you wish.

11. Click done.
    
12. Repeat the above steps to create two new tiles, one for Triggered and another for Acknowledged substituting the following data name and value settings in lower case in the headers & data section:
    name: statuses%5B%5D value: triggered
name: statuses%5B%5D value: acknowledged
    
    

Hints and Tips

• Look at the PagerDuty API documentation or speak to your PagerDuty expert.
• Use custom labels to improve data formatting see How to use custom labels