PagerDuty and ticketing integrations

Monitaria can open a ticket or page on-call when a problem starts, add a note when it changes, and close it when it recovers. Nobody has to read alert emails and type up tickets. Acknowledgements travel both ways: a ticket someone starts work on, or a page acknowledged in PagerDuty, acknowledges the problem in Monitaria, and an acknowledgement in Monitaria is passed on.

What you need

• PagerDuty: in the service, choose Integrations › Add an integration › Events API v2 and copy the integration key. Accounts in the EU service region set Events address to https://events.eu.pagerduty.com/v2/enqueue.
• ConnectWise PSA: an API member (System › Members › API Members) with a public and private key, your company ID and a client ID from developer.connectwise.com. To close tickets on recovery it also needs a Status to close with.
• Autotask: an API-only user (security level API User, with Monitaria as its integration vendor), its API secret and API tracking identifier, and the company ID tickets belong to. The API zone is looked up from the user name.
• HaloPSA: an API application (Configuration › Integrations › HaloPSA API) that signs in with a client ID and secret and can read and edit tickets, and the customer ID tickets belong to.
• ServiceNow: an integration user with the itil role, or an OAuth client, and a resolution code your instance accepts.
• Jira Cloud: an account email, an API token from id.atlassian.com › Security › API tokens, and the project key.

1. Add the integration

1. Open Settings › Integrations. Under Collector address, enter the address people use to open this collector, such as https://monitoring.example.com, and choose Save address. Tickets and pages link back to it. It's the same address as in Settings › Alerts, so alert emails link there too.
2. Under Integrations, pick the service in the Add list and choose Add integration.
3. Give it a Name and fill in the Connection fields. For a ticketing service, also fill in Where tickets go: the company, board, queue, customer, assignment group or project that tickets belong to.
4. Under When to send, tick Down, Warnings or both, set Wait before sending (minutes) and choose what happens When the problem recovers. By default the wait is 5 minutes for tickets and none for pages.
5. To narrow it down, tick boxes under Only for these device types and Only for these sites. None ticked means all.
6. Choose Save. You can save an integration switched off while you finish it.

2. Test it and switch it on

1. Choose Test connection. It checks the sign-in and changes nothing; for PagerDuty it sends a test event that pages nobody.
2. Choose Send a test ticket. It opens a real ticket, adds a note and closes it. For PagerDuty, Send a test page triggers a real test incident that notifies whoever is on call, so resolve it in PagerDuty afterwards.
3. Tick Switched on and choose Save. From then on, new problems open tickets or pages.
4. Check the Delivery log at the bottom of Settings › Integrations. It lists recent attempts and whether each one worked.

Tip: To take acknowledgements back from PagerDuty, add a generic webhook (V3) for the service's incident events in PagerDuty, pointing at the address shown under Acknowledgements from PagerDuty (your collector address followed by /hooks/pagerduty). Paste its signing secret into Webhook signing secret. PagerDuty must be able to reach that address; a reverse proxy that passes only /hooks/ is enough. It's the only part of integrations that needs an inbound connection.

How it behaves

• When a sensor goes Down, or to Warning if you ticked Warnings, Monitaria waits out the delay, then opens one ticket or page. A problem that recovers within the delay sends nothing.
• A ticket names the problem, its site, device and sensor, the message, when it started and any note an operator added. It ends with an Open in Monitaria link and a Monitaria reference (mon-…).
• While the problem lasts, a change between Warning and Down, or an acknowledgement in Monitaria, adds a note. When it recovers, the ticket gets a note and is closed, or only noted, as you chose. A PagerDuty alert is resolved, or left for a person.
• Each problem gets one ticket at most. If a reply goes missing, Monitaria looks the ticket up by its reference before trying again.
• Open tickets are checked every 5 minutes by default. A ticket closed there is no longer updated. A ticket moved on from new, or assigned to someone, acknowledges the problem in Monitaria with the ticket number.
• Problems in a maintenance window, or behind an upstream device that is Down, wait. One still Down when the window ends gets its ticket then.
• If the service can't be reached, nothing is lost and monitoring isn't slowed: deliveries wait and are retried for up to a day. A request the service refuses, such as one naming a missing board, waits under Waiting to send with the reason. Fix the cause, then choose Retry now, or Drop.

Operators and admins see Open ticket and Page on-call in a sensor's details while it has a problem and an integration of that kind is switched on, and can add a Note. If the problem already has a ticket, they get its link instead of a second one. A device's details list its Tickets and pages, and its timeline shows when each was opened and closed.

Tip: MSPs can open Map sites to … under Where tickets go and give each customer's sites their own company, board, queue, customer or project. Sites you don't map use the defaults. For PagerDuty, add one integration per customer service and limit each to that customer's sites.

Security and limits

• Keys, passwords, tokens and the webhook secret are write-only. They're never shown again, and a box left empty keeps the saved value. A saved secret is only sent to the address it was saved for: change an API address and you type the secrets again.
• What leaves the network is what a ticket or page says. Untick Include addresses (IP addresses and host names) in what's sent to leave out IP addresses and the sensor's target, even from device names: RB-WH-PRN01 (198.51.100.50) is sent as RB-WH-PRN01.
• Requests never go to link-local or cloud metadata addresses, and redirects aren't followed. There's no HTTP proxy support, and the service's certificate must be trusted by the system.
• Every change, test, manual ticket and page is recorded in Settings › Audit log.
• Ticket status is checked by polling, up to 50 open tickets per integration each time, not by webhooks from the ticketing service.
• HaloPSA can't be searched by reference, so after a lost reply a HaloPSA integration may open a second ticket.
• PagerDuty has no notes: changes are repeat triggers that PagerDuty merges into the open alert. If PagerDuty groups several Monitaria alerts into one incident, acknowledging it there acknowledges only the first problem in Monitaria.
• Problems that started before an integration was switched on don't open tickets by themselves; use Open ticket. Per incident (grouped problems) needs incident tracking, which is on by default (see the incidents guide).