PagerDuty Connector's key name

[arisonl]

PagerDuty offers two ways to integrate: Through "Global routing" (with a "routing" key) and through a Service (with an integration key). While playing around with PD, I have managed to set up connectors using the integration key but not with the "routing" key. While I am unsure at this point if the "routing key" path is possible, the integration key option works. However, we refer to the key on our Connectors UI as the “routing” key. This might cause confusion to the user that sets up the Connector.

PagerDuty:

Our Connector:

cc: @YulNaumenko @pmuellr

[elasticmachine]

Pinging @elastic/kibana-alerting-services (Team:Alerting Services)

[pmuellr]

Sadly, the PD APIs make this a little confusing.

Technically, we only support the Events API v2. Under "Getting Started", you'll see the following:

You will need to include the integration key for your new integration, as a routing_key in the event payload.

So, it's both an "integration" key, and a "routing" key, depending on how you look at it.

I wasn't familiar with "Global routing", but some GOOGling yielded this page: Global Event Rules API. Which has this bit of text in it, under Parameters / Other Fields:

external_id The global event rules routing key.

Which sounds like in this case, the property name is external_id but is described as a "routing" key.

Sigh.

[pmuellr]

Just to make it a little more confusing, the link in the connector editor points to some watcher docs:

The "Configure a PagerDuty account." link takes you here: https://www.elastic.co/guide/en/elasticsearch/reference/current/actions-pagerduty.html#configuring-pagerduty

Steps 1, 2, and 3 are all correct there, but then it starts talking about a keystore, and is then venturing into Watcher action specifics.

[pmuellr]

Our current doc I think gets it about right:

https://www.elastic.co/guide/en/kibana/7.7/action-types.html#pagerduty-action-type

Routing Key
A 32 character PagerDuty Integration Key for an integration on a service or on a global ruleset.

[pmuellr]

Here are my current thoughts on changes:

• change the copy in the connector editor from "Routing key" to "Integration key"
• change the link in the connector editor from the watcher docs to the alerting docs for the PD actions
• change the alerting docs for the PD action to point to the watcher docs (in terms of directions on how to create an integration key), and change the referenced "Routing key" name to "Integration key". Probably also mention that in the Pagerduty v2 event API, the "Integration key" is used as the value of the routing_key property.

[arisonl]

Thank you @pmuellr! That makes sense. On your third point and partly on the second as well: We are putting together integration documentation for PD, here is the draft: https://docs.google.com/document/d/19wsl6uqXiBfNSD6hArVzrSYnyoD2E4agd-eSKvRErBM/edit#heading=h.dnnu0dp93okx It is to an extent why we need this split: #62445

[pmuellr]

I was going to start in on this, but it seems like a 7.7.1 thing, and we need to wait for the action doc pages to be split before changing them, so moving back to unassigned.

[mikecote]

Action types split PR is now merged and backported.