Relabel UI and Documentation to use new terminology

[gmmorris]

This is the fourth part of #90375.

Rename labels in the UI and documentation to match the new terminology

For details on the introduction of the terminology see notes under #90375 (comment)

[elasticmachine]

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

[mikecote]

@gmmorris, I believe this issue is good to go (unblocked) if the scope is to rename labels and user guides?

[gmmorris]

@gmmorris, I believe this issue is good to go (unblocked) if the scope is to rename labels and user guides?

Go Go Go!

[ymao1]

Proposed changes:

• On management page, Alerts and Actions -> Rules and Connectors
• Change client route from /app/management/insightsAndAlerting/triggersActions/alerts to /app/management/insightsAndAlerting/triggersActions/rules
• Change client route from /app/management/insightsAndAlerting/triggersActions/alert/${alertId} to /app/management/insightsAndAlerting/triggersActions/rule/${ruleId}
• Create/edit alert flyouts -> Create/edit rule
• in rule details page Instance column becomes Alert

Questions:

1. On the stack management page, Alerts and Actions is listed under Alerts and Insights. If we change to Rules and Connectors, should the heading stay Alerts and Insights?
2. Rules and Connectors or Rules, Alerts and Connectors so users used to seeing the word Alerts will make the connection? Or if we are not changing the Alerts and Insights heading, is that enough?

@mdefazio @gchaps Any thoughts on Rules and Connectors vs Rules, Alerts and Connectors?

[ymao1]

Are we renaming action variables?

This is something that shows up in the UI so it would be confusing if it still referenced alertId vs ruleId but it would impact existing rules that reference these action variables. Should this be a separate issue?

[pmuellr]

This is something that shows up in the UI so it would be confusing if it still referenced alertId vs ruleId but it would impact existing rules that reference these action variables. Should this be a separate issue?

Yes, we probably should, and we need to leave the existing ones as well - presumably deprecated in 8.0. Deprecated action variables, with some UI annotation! :-). Luckily these are all generic variables for all alerts, so it's a fix in one set of locations (as opposed to all alert types)

[mikecote]

• Change client route from /app/management/insightsAndAlerting/triggersActions/alerts to /app/management/insightsAndAlerting/triggersActions/rules
• Change client route from /app/management/insightsAndAlerting/triggersActions/alert/${alertId} to /app/management/insightsAndAlerting/triggersActions/rule/${ruleId}

I wonder if we should drop triggersActions part or rename it (ex: rulesAndConnectors)?

[ymao1]

I wonder if we should drop triggersActions part or rename it (ex: rulesAndConnectors)?

/app/management/insightsAndAlerting/rulesAndConnectors/rules and /app/management/insightsAndAlerting/rulesAndConnectors/connectors? I would probably prefer something more like /app/management/insightsAndAlerting/alerting/rules and /app/management/insightsAndAlerting/alerting/connectors but then if we wanted to rename the triggers_actions_ui plugin, what would we name it lol?

[mikecote]

Gotcha, I'm ok if we hold off on my suggestion since the alerting UI will eventually become its own application (leaving connectors alone). The .../alerting/connectors route seems odd to me since connectors are de-coupled from alerting and used by cases (it will be more obvious soon when you can use connectors to share things from dashboards).

[ymao1]

In the process of updating the docs, it seems like there are a lot of references to alerting that we wouldn't want to replace with rule (ruling?) and it seems a little disconnected for the UI not to mention alerting at all. How would we feel about Alerting Rules and Connectors?

[mikecote]

I'm +1 on Alerting Rules and Connectors. I thought of alternatives, but I'm accepting that the connectors should split out someday and that it would be hard to distinguish them until then.

[gmmorris]

Are we renaming action variables?

This is something that shows up in the UI so it would be confusing if it still referenced alertId vs ruleId but it would impact existing rules that reference these action variables. Should this be a separate issue?

I think we should consider not changing - but adding the new ones and deprecating the old ones.
That way we don't need to change existing alerts, but users won't add new ones with the old keys as we can hide the deprecated ones from the list.

Is that possible? 🤔

[ymao1]

I will look into somehow deprecating old action variables. It will get a little tricky as alertId -> ruleId but alertInstanceId should become alertId and then how will we know if {{alertId}} references the new or old variable 😬

[mdefazio]

I'd also like to see Connectors broken out to the same menu level, instead of buried in a tab. If the section heading is Alerts and Insights, and Connectors is broken out, then perhaps we can make it just Rules or Rule Management? With the section heading saying 'Alerting', my thought was we didn't need to repeat it for this menu item

[gchaps]

To me, Alerting Rules and Connectors sounds a little awkward. I was thinking along the same lines as @mdefazio. Since Alerts and Insights is in the left side nav, is Alerting needed in the page title?

[gmmorris]

I will look into somehow deprecating old action variables. It will get a little tricky as alertId -> ruleId but alertInstanceId should become alertId and then how will we know if {{alertId}} references the new or old variable 😬

Oh, damn, you're right...
Sounds like we'll need a migration 😫
Perhaps, if the migration gets really hairy, we can use the meta.versionApiKeyLastmodified field to decide which param set to use?

Probably better just to migrate... 😬

[gmmorris]

I'd also like to see Connectors broken out to the same menu level, instead of buried in a tab. If the section heading is Alerts and Insights, and Connectors is broken out, then perhaps we can make it just Rules or Rule Management? With the section heading saying 'Alerting', my thought was we didn't need to repeat it for this menu item

When you say "broken out" do you mean not have tabs anymore, but rather separate pages all together? 🤔

[mdefazio]

do you mean not have tabs anymore, but rather separate pages all together?

I do. Likely still within Alerts and Insights though, but admit there's plenty of room for debate here.

[mikecote]

I do. Likely still within Alerts and Insights though, but admit there's plenty of room for debate here.

Side note: this is probably where the connectors will land after alerting becomes its own application in Kibana.

[ymao1]

As long as it's enough that Rules is tied to Alerting by being under the Alerts and Insights header, I'm good with using Rules and Connectors. My main concern was the lack of the term alert/alerting in the context. Using Rules and Connectors now will make it more straightforward to split out Rules from Connectors later.

Interested to get @arisonl's thoughts as well on this

[pmuellr]

I will look into somehow deprecating old action variables. It will get a little tricky as alertId -> ruleId but alertInstanceId should become alertId and then how will we know if {{alertId}} references the new or old variable 😬

Oh, you're right...
Sounds like we'll need a migration 😫

Another idea - we have all these "top-level" variables for mustache that are alert-related:

• alertId
• alertName
• alertInstanceId
• alertActionGroup
• alertActionGroupName
• alertActionSubgroup
• spaceId
• tags
• state
• params

Perhaps we should deprecate these, and create a new top-level variable - alert or rule - or maybe both? And then put these variables under there.

The remaining top-level variables seem very generic for any connector usage, if connectors ever get used outside of alerting

• date
• kibanaBaseUrl

[ymao1]

I will look into somehow deprecating old action variables. It will get a little tricky as alertId -> ruleId but alertInstanceId should become alertId and then how will we know if {{alertId}} references the new or old variable 😬

Oh, you're right...
Sounds like we'll need a migration 😫

Another idea - we have all these "top-level" variables for mustache that are alert-related:

• alertId
• alertName
• alertInstanceId
• alertActionGroup
• alertActionGroupName
• alertActionSubgroup
• spaceId
• tags
• state
• params

Perhaps we should deprecate these, and create a new top-level variable - alert or rule - or maybe both? And then put these variables under there.

The remaining top-level variables seem very generic for any connector usage, if connectors ever get used outside of alerting

• date
• kibanaBaseUrl

@pmuellr I started down that path with this PR: #93836 using rule as the top level variable.

I didn't move all the variables under rule. but I think you're right that they should be. I will update the PR