Add docs for legacy URL aliases#110279
Conversation
jportner
added
v8.0.0
release_note:skip
legrego
left a comment
legrego
left a comment
There was a problem hiding this comment.
Looks great overall! Just a couple of questions and suggestions from me. It's probably worth asking the docs team to review as well
| in this situation, you might want to disable the legacy URL alias completely. This leaves the saved object intact and you will not lose any | ||
| data by disabling the alias -- you just won't be able to use the old URL to access that saved object anymore. | ||
|
|
||
| To disable a legacy URL alias, you'll need three pieces of information about it: the `targetSpace`, the `targetType`, and the `sourceId`. |
There was a problem hiding this comment.
It might be good to describe exactly what these terms are. They'll likely be foreign concepts to the users who end up on this page.
There was a problem hiding this comment.
Ah, I was a bit torn on that. I do explain them on the linked API page, I thought it may be best if we don't state the same thing on two different pages. I'm interested to see what the Docs team thinks.
There was a problem hiding this comment.
@gchaps based on your comments below, it sounds like you think this is clear enough with your suggested changes?
| Legacy URL aliases are intended to be fully transparent, but there are some very rare situations where this can lead to an error. For | ||
| example, you may have a dashboard and one of the visualizations may fail to load, directing you to this page. If you encounter an error | ||
| in this situation, you might want to disable the legacy URL alias completely. This leaves the saved object intact and you will not lose any |
There was a problem hiding this comment.
This explains the symptom of the error, but not what caused the error. Do you think it would be helpful to give an example of that causes these types of errors, or would that be TMI?
There was a problem hiding this comment.
I'm afraid that an example of the causes would be a bit too much. You can't get into that situation through "normal" usage of Kibana (simply by virtue of upgrading to 8.0, or by sharing objects, or by importing objects) -- we believe the only way to get into this situation is by using third-party integrations.
I did toy with the idea of showing a screenshot of an error that you might see as an example, but that's not been implemented yet. Also interested to hear what the Docs team thinks about this.
There was a problem hiding this comment.
I think the text is good as it is, especially since the only way to get into the situation is by using third-party integrations. I don't feel a screenshot is necessary.
| (Required, object array) The aliases to disable. | ||
| + | ||
| .Properties of `aliases` | ||
| [%collapsible%open] |
There was a problem hiding this comment.
How about formatting with a box as in this doc .
There was a problem hiding this comment.
I'm not sure what is making that one show in boxes but this one isn't. Perhaps the sub-properties end in ::: instead of ::? It doesn't make a difference in my IDE previewer, but I'll make the change and see if it changes how it's rendered in the docs website.
There was a problem hiding this comment.
I wouldn't spend too much time on this. The formatting also works find as it is.
There was a problem hiding this comment.
I tried one more thing and it's fixed now 😄
Needed to add [role="child_attributes"] before the section.
gchaps
left a comment
gchaps
left a comment
There was a problem hiding this comment.
LGTM with one minor edit.
I updated the UI components in #114172 and backported it to 7.x, and I added doc links to these docs in that PR. So I need to backport this too. |
jportner
added
v7.16.0
auto-backport
💔 Backport failed
To backport manually run: |
# Conflicts: # docs/developer/advanced/index.asciidoc
4 participants
Resolves #110145.
I do not intend to backport this as it is not applicable to pre-8.0 versions of Kibana.
Docs preview links: