Improve clarity around what is being shared in share UI

[spalger]

See #4022 for some context, and #7899 for some discussion on possible solutions.

In #8022 the option to convert the states in the URL to hashes was will likely be added, which creates URLs that are no longer copy-paste sharable. I imagine this will lead more people to the share UI and as such I think we should evaluate how it can be improved.

Here's my proposal:

• if the object to share is unmodified
  • offer a link/embed code to the saved object without the app state
  • offer a short version of the link/embed code
• if the object to be shared has been modified
  • hide the normal share links
  • encourage the user to save the object so that people they share with can see their modifications
  • offer to create a temporary saved vis/dashboard/search that they can share
    • their modifications will be included
    • warn that temporary saved objects _cannot_ be edited
    • These temporary objects are actually just short URLs to the current entire URL

[spalger]

@tbragin @jimmyjones2 @cjcenizal @tylersmalley @rashidkpc @w33ble @Bargs your feedback would be especially appreciated

[w33ble]

These temporary objects are actually just short URLs to the current entire URL

I was quite worried about what these temporary saved objects would be until I read that. Seems legit.

This is actually the same workflow that's in Reporting, except if you don't save your changes, you can't do anything, there's not "temporary state" step.

if the object to share is unmodified ....

Would that mean that users COULD share that URL without the share UI? Since the state is all in the saved object already, I assume yes. I just want to confirm, since that's an interaction we've encouraged in the past, copying and pasting the URL directly to share something in Kibana should still work most of the time, specifically when the user hasn't changed anything.

[spalger]

@w33ble Today, yes, copy-pasting the URL will work.

In 5.0 I suggest that we switch on state-hashing by default so that everyone has a consistent user experience and to drive usage of the Share UI, which will be one more click for people who know what they're doing, and will lead all the people who don't know about the states in the URL to a place where they can get the right link for sharing.

[cjcenizal]

I think this is a really great flow, Spencer! I'd love to design and implement the UI portion of this, or at least prototype it so we can see what this will look like in the browser.

This proposal has my 👍

[Bargs]

In 5.0 I suggest that we switch on state-hashing by default so that everyone has a consistent user experience and to drive usage of the Share UI

But if someone does copy paste that URL, I assume Kibana would ignore the unknown hash and load up the unmodified saved object?

What are the benefits of the "temporary" object? Is it just that users won't have to save? If so, is that advantage worth the additional complexity of a new concept users have to wrap their heads around? I think this temporary object concept might cause a lot of confusion.

I think I prefer the simplicity of "unsaved changes can't be shared". It makes things black and white, either your changes are unsaved and unshareable or they're saved and you can share them simply by sending someone a link to the viz/dashboard. If the answer to my first question is positive (unknown hashes are ignored), this means users can even share the viz they're looking at simply by copy pasting the URL. All the user needs to know is: save, then share.

[cjcenizal]

@Bargs We know users still have uses for these "temporary" (aka cloned, forked, copied, duplicated) objects. For example, some users create these URLs dynamically to build unique dashboards which they email out to their users. We know Kibana will need to accept these URLs, but if we don't surface them in the UI somewhere too, then this feature will become inaccessible.

If we could do things all over I think I would also like to create a UX which emphasizes the saved objects, but given where we are now, I think Spencer's messaging does a good job at managing users' expectations of the URL while giving us flexibility on to how we move forward after 5.0 is out.

[Bargs]

some users create these URLs dynamically to build unique dashboards which they email out to their users

What's wrong with simply asking these users to save their work before sharing?

[tylersmalley]

For sharing an unmodified objects, do we actually need to provide a short URL? Won't the URL already be short if it's not including app state?

I like the simplicity of using the short URL to save a modified object.

[tylersmalley]

@Bargs, these users have a task which dynamically generates the URL for a visualization which is sent to users. The only way for them to save the visualization programmatically would be to insert the record into ES, which is not a clean or supported interface. Creating an API for this would make this easier.

[Bargs]

Ah, thanks @tylersmalley, you have to say things twice before I actually comprehend them.

However, I guess the part I still don't get is this:

We know Kibana will need to accept these URLs, but if we don't surface them in the UI somewhere too, then this feature will become inaccessible.

Kibana can accept the full URLs without providing this "temporary saved object" functionality. If these users are generating the URLs programmatically, what benefit does a UI element for creating temporary saved objects give them?

[tylersmalley]

I believe the thinking is that if they don't have a URL to start with, it's hard to make modifications to it. Maybe we could still expose the URL but default to the short URL for objects which modifications?

[cjcenizal]

Right, that was pretty much my thinking, @tylersmalley . Imagine being a first-time user who has a use case for these programmatically-generated URLs. If we don't surface them somehow (via the UI, or in our docs somewhere), then it's unlikely that user will discover how Kibana can satisfy that use case.

I think defaulting to the short URL is a good idea. We can have a button labeled "Expand to editable URL" for users who want the full, editable URL.

[Bargs]

But we should discourage that programmatic use case, shouldn't we? The URL structure is undocumented and we've always instructed users not to rely on it. We're only in this situation because some users didn't heed that warning. We're doing our best to maintain backwards compatibility, but that doesn't mean we should add UI elements that encourage these bad practices. If someone wants to use a private, undocumented API, they can dig for it.

As @tylersmalley mentioned, these programmatic users would ideally create new objects via a documented, public API. I can see that being the end goal, eventually deprecating the old URL format entirely. But if we encourage more and more users to rely on the long URL, that's going to be impossible.

Let me elaborate some more on why I think these temporary saved objects will be confusing.

Let's say I'm a basic Kibana user, and someone sends me a link to a dashboard. Is this a saved Dashboard? Was it based on a saved dashboard, with some modifications? Is it a totally ephemeral dashboard? Can I edit it? How do I save my edits? Will anyone else be able to see my edits? I have no clue! There are a crazy number of states this thing could be in, and I'd have to be a Kibana engineer to understand them all. To make things worse, it depends entirely on how the sender chose to share it with me. So I either have to ask the sender what this thing is, or try to read their mind, or hope there's some indication on the page that's clear enough that I'll actually understand it.

Compare that with the situation I'm proposing. A dashboard can be in one of two states - Saved and shareable, or modified with unsaved edits that are unshareable. That's it. If someone shares a link with me, I know exactly what it is. If I want to make edits that everyone else with this link will see, I just edit and save. If I want to "fork", I simply make edits and save under a new name ("save as", the original fork). These are ancient workflows that everyone understands.

[cjcenizal]

(@Bargs Out of curiosity, where do we instruct users not to rely on this URL structure?)

Re your 4th paragraph, I 100% agree with you that the current UX behind how state is represented in our URLs is totally bananas (and not in the good way). I would be surprised if anyone is actually happy with it.

I also think your solution in your 5th paragraph is the right one. I feel pretty confident we should/will evolve Kibana until we get there.

What is backwards compatibility?

I think the question is: what current undesirable behavior is worth supporting? Backwards compatibility is important, but I don't think we all have the same understanding of what that means in this situation. So far, I've heard backwards compatibility defined as:

1. Consuming the super-long URL format without breaking.
2. Retaining the current browser history undo/redo functionality.

I think these are items up for debate, but I also think there are reasons we should include them in our definition of backwards compatibility:

1. The ability to share visualizations that aren't saved, and instead have the state encoded in the URL. Our current UI makes it very difficult to manage a large number of saved visualizations, so maybe people share unsaved visualizations to avoid polluting the UI with a ton of visualizations. If we don't improve our visualization-management UI, then forcing everyone to save a visualization before sharing it could make managing your visualizations a really bad UX.
2. The ability to programmatically build visualization URLs (without an API). If we don't support an API to users before removing this ability, then some users who depend on this functionality for their work/business will be really screwed.

In both of these cases, I think we need to put in significant amounts of work to build a viable alternative before removing the functionality in question.

[cjcenizal]

@Bargs and I talked a bit and decided that Spencer's proposal makes sense. We think the point is really to apply some clarifying language to a concept which is currently very unclear, namely, "What is the difference between our two types of URLs, saved vs unsaved?"

We propose using the term "Original URL" for the URL to the saved visualization, and the term "Snapshot URL" for the URL that contains an encoded visualization state.

I made some mockups illustrating how I think the share UI should look to communicate these concepts.

When the visualization has been saved

Regardless of whether the visualization has been modified or not, the user should have the option of sharing the Original URL or the Snapshot URL. By presenting both side by side, we are educating the user on the difference between the two.

When the visualization hasn't been saved

If there is no saved visualization to share via an Original URL, then we should disable the controls (but keep them visible so the user can infer what functionality could be available), and display a helpful warning.

Love to hear everyone's thoughts (CCing @alt74 for design input).

[spalger]

"Snapshot URL" for the URL that contains an encoded visualization state

Oh man, that is the perfect name for this

[Bargs]

For the record, I'll write down a few of the things that led @cjcenizal and I to this solution:

We both agreed that requiring users to save objects before sharing them would come with a lot of advantages:

• It would reduce the number of concepts regular users need to comprehend
• Bookmarks and links wouldn't go stale since all shared links refer to a saved object
• Users could continue to share by copy pasting from the URL bar, since the URL simply refers to the saved object. They just need to save first.
• The friction of the save step could even be reduced by auto-saving things with auto-generated names by default.

However, there would be a major increase in the number of saved objects if everything that's shared needs to be saved. Our current object management UIs don't provide the tools necessary for users to manage this complexity. Ideally we'd just improve these management tools, but in the interest of time and getting a fix for the IE issue into 4.x, it's simpler to go with the solution CJ outlined above.

Hopefully we can avoid too much confusion by carefully choosing how we present these new options to users. We realized the concepts aren't really new, we're just formalizing the choices that are already available to users today, but are somewhat hidden.

[Bargs]

A couple notes on the descriptive text (in blue boxes) for snapshots and originals:

Snapshots: I think it needs to mention something about capturing the "current state" of the viz. Something like: "Snapshot URLs encode the current state of the visualization in the URL itself. Edits to the visualization accessed via this URL won't be visible to other users."

Original: needs some mention of saved state, like: "Original URLs provide a link to saved visualizations. An Original URL will always load the most recent version of a visualization"

[epixa]

Closed by #8172