Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Discuss] Rename Saved Objects to Kibana Assets #84777

Closed
alexfrancoeur opened this issue Dec 2, 2020 · 19 comments
Closed

[Discuss] Rename Saved Objects to Kibana Assets #84777

alexfrancoeur opened this issue Dec 2, 2020 · 19 comments
Labels
discuss Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc

Comments

@alexfrancoeur
Copy link

alexfrancoeur commented Dec 2, 2020

Saved Objects have evolved to be so much more than they used to be. They are now being leveraged in a variety of different areas through out Kibana and are no longer limited to entities like visualizations and saved searches. Cases are SO's, alerts are SO's, Tags are SO's, etc.

We now ship integrations with both Elasticsearch assets (ILM / SLM policies, etc.) and Kibana assets (dashboards, visualizations, etc.). The number of Kibana assets will grow as we can begin to support alerts for instance.

Screen Shot 2020-12-02 at 9 52 54 AM

We also plan to convert our visualization application into a visualization library (#62834). However, when you're building a dashboard now you have the ability to add more than a visualization. You can add maps, ML swimlanes and more in the future (#70513) as embeddables take off. Should we consider an "Asset Library" instead of a "Visualization Library"?

"Saved Objects" as a name is not very descriptive, and while "Kibana Assets" is fairly generic, it's a bit more self explanatory. Every entity that falls under this umbrella are assets of Kibana.

There are also technical considerations here as well. Should we also change the name in the 'public' HTTP API and related documentation? Are there other changes we should make or expectations we should set with this change?

Questions we want to answer

  • Does it make sense to rename Saved Objects to Kibana Assets in 8.0?
  • If so, should we lean into "Kibana assets" more?
  • What are the technical ramifications of this simple name change?

Let's time-box this discussion for two weeks and try to get an answer before the winter holidays. We'll aim to close this issue on December 16th.

cc: @elastic/kibana-core @elastic/kibana-pm @alexh97

@alexfrancoeur alexfrancoeur added discuss Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc labels Dec 2, 2020
@timroes
Copy link
Contributor

timroes commented Dec 2, 2020

While I like the general idea of having "Kibana assets" I am wondering if Saved Objects should be renamed to that. The problem I see with this is that we have a lot of saved object types, that are more "technical" nature (like the config/advanced settings). I am not sure if they would be perceived as "assets" from a user's perspective.

Here a list of all saved object types atm:

screenshot-20201202-162321

So I have the feeling, that "assets" might just be a subset of saved objects and if we would have an "Asset Library" instead of a "Visualization library" (which by itself I think might be a good idea), I think a user would not expect to have a tag or an apm-index show up there.

If we would join those two concepts completely (asset library and saved objects), i.e. give them one UI to work of, I think we should have at least some notion of "system assets" to hide more technical saved objects from the users.

That said I would be pro "Kibana assets" as a wording in general (whether it's all saved objects or a subset) and using this wording more across Kibana, but think the merge of a "Visualization library" (or better "Asset library") into saved object management might need more than just renaming.

@elastic-jb
Copy link

I like where Tim is going. It might make sense to have two concepts, an internal system type and one intended to be shared, managed, templated from, etc.

This morning we were talking about this for drilldown templates that are only used to create new instances of a drilldown. That feels more like an asset to me. It would be nice of the "read-only" concept that we have talked about several times aligns with one and not the other. Feels more like assets would be more flexible and system object types would be more rigid and mostly hidden from users.

@VijayDoshi
Copy link

Thanks for getting this discussion going Alex.

I agree that Assets are likely a subset of Saved Objects and that we should think of an Asset Library vs. a Visualization Library. IMO attributes like read-only would be at the SO level and "Assets" would inherit that property. For example, a dashboard installed by am Integration Package or Solution might be read only, or a system generated tag might be read only (really only mutable by the system). I'm definitely ++ to "Asset Library" regardless.

@clintandrewhall
Copy link
Contributor

clintandrewhall commented Dec 7, 2020

My gut reaction is that this is a good idea... there are a few things I think we should consider:

  1. Canvas already has "assets", which are base64-encoded images stored within the Canvas Workpad. Since Canvas can embed "Kibana assets", we'll need to rename this, (e.g. "images").
  2. I think there's an important distinction between user-created-and-saved assets and ships-with-Kibana-(or-Fleet) assets. Should we be referring to a Visualization of data with the same term as a Canvas Workpad template?

I think we might consider having both "Kibana Assets" and "Your (or My) Assets", ("your" allows us to include objects created by others in the org/space). It helps draw the line between things I've created and saved and what Kibana/Elastic provides. Personally, I'm always a fan of using language that give someone ownership over their content within a product.

But on the whole-- especially considering #1 above-- I think we should be prepared for different collections of assets, e.g:

  • Canvas Assets (images saved with the workpad, templates, etc)
  • Your Assets (visualizations, Canvas Workpads, embeddables that have been created using Kibana)
  • Kibana Assets (templates, tags, sample data, expressions, etc)
  • [whatever] Assets

@ThomThomson
Copy link
Contributor

I agree with Tim & Clint, about the need to provide separation between more technical assets, and user generated assets. The concept of 'your assets' / 'my assets' particularly appeals to me when paired with better metadata.

That said, having multiple listing pages, or separate libraries for each category could lead to a bit of redundancy or confusion from the user so I would be in favour of a single unified view, the Asset Library being capable of showing all types of Kibana Assets, but having a 'category' filter which by default filters out all technical / non-user generated assets.

Over-all, I am definitely in favor of renaming SavedObjects to Kibana assets.

@kobelb
Copy link
Contributor

kobelb commented Dec 10, 2020

Initially, I was in-favor of using the word assets to describe all of Kibana's "things". However, I think that @timroes and others raised a good concern about assets inaccurately portraying these "things" as being static in nature. For example, I've previously used the word assets to describe the non-code parts of a web-application: images, css, fonts.

I like what @clintandrewhall suggested, where we choose a primary noun and then use a noun adjunct or adjective to further classify the "things".

In my opinion, everything that we've discussed is conceptually a "Kibana entity", as they're all entities that are specific to Kibana. The subset of the entities that are provided by an integration manager package, that in the future end-users won't be able to modify are "Kibana protected entities".

Screen Shot 2020-12-10 at 1 48 31 PM

Are there other groups of these entities that we need to classify, or are we comfortable just referring to them by their names?

@clintandrewhall
Copy link
Contributor

clintandrewhall commented Dec 14, 2020

@kobelb I like this a lot. I'd add the following, as 1/ we could expand the use of this taxonomy to other Elastic applications, and 2/ these entities exist in ES (and perhaps elsewhere?) and could be referred to in bugs/posts/etc.

2

@kobelb
Copy link
Contributor

kobelb commented Dec 14, 2020

@clintandrewhall, I don't think that we should rename "Kibana entities" to just "Entities". This doesn't leave us room to distinguish between "Kibana entities" and "Elasticsearch entities". I think this differentiation is important, because Kibana's entity model differs significantly from Elasticsearch's. For example, Kibana has the concept of Spaces and Elasticsearch doesn't.

I also think that we should refrain from using the phrase "My Entities". This conflicts with the future where we have OLS and saved-objects will have an owner.

@alexfrancoeur
Copy link
Author

Thanks all for the suggestions, thoughts and feedback. Some comments below.

+1 on splitting between system generated "things" and user generated "things". Some of that discussion is happening here in relation to assets packaged with an integration #70461. Even though there are technical limitations at the moment to make these read only, the integration team is already thinking through guidelines for how these are identified elastic/integrations#327 (comment)

If we were to use the asset naming convention, I agree that we'll need to update Canvas.

With #82725 being prioritized, laying the foundation for true OLS (#39259), preparing for a concept of "your things" makes sense to me.

+1 on having an all encompassing library with filters. This is how we approach adding a visualization to a dashboard today. The embeddables are filterable by category.

I also like the idea of alignment across the stack on this nomenclature. Integrations (cc: @ruflin @mostlyjason) will be packaged with "things" from both Elasticsearch and Kibana.

I view these "things" being consumed in a few different areas, and it's possible I've been conflating them, but a common noun (with classifying adjectives) feels like the best approach here. The end user facing experiences that I've been thinking through can be found below. I realize there is some debate now about assets, but I'll use that noun here to provide some examples.

  • Visualization / embeddable library - An area where you can view all supported embeddables under the analytics umbrella. Analytics assets or simply Assets in the navigation / dashboarding experience.
  • Saved Object / SO Management - The primary "thing" in Kibana and supporting UI, Kibana assets
  • Integration packages - Turn key experiences with our stack that include pre-built "things". Within a package there would be Assets, but if we needed to categorize further, we'd have Elasticsearch assets and Kibana assets.

As for the term itself, I'd aim to provide one that is more user friendly than not. While Saved Objects are probably technically accurate, it is clear the origins of this naming convention were derived more from its implementation than with the consumer in mind. For its current state, I think that's fine. If we agree we want to standardize on a term that can be used interchangeably across Kibana (and the Stack) with different leading adjectives, then I think we need to define that primary noun with our end users in mind. Seeing how we want to have this library as a primary experience for dashboarding in addition to providing pre-packed content from integrations, I think that audience will be a good one to start with.

To me, assets fits the bill here for these end users. While the end result is dynamic in nature, an existing visualization / embeddable is a pre-configured object that is either packaged with an integration or created by a user. I agree that entity feels correct by technical definition, but if the intention is that this noun lives throughout Kibana, I'm not sure I agree that we should be promoting the term as originally proposed. If we were to go down this route, I think we'd have to abstract away this noun from end user / non-administrative experiences. Using the above examples again:

  • Visualization / embeddable library becomes Analytics library or Library
  • Saved Object / SO Management becomes Kibana entities
  • Integration package content will be grouped by Elasticsearch and Kibana to the end users adding the integration, not explicitly stating entities.

My personal feeling is that entity feels rather technical in nature and assets is easier to grasp as an end user. If the only places you see entity are in the API or administrative management UI, I could see entity as an option.

Given the liveliness of the discussion (thank you, naming is hard). I'll extend the discussion timebox to the end of the week, December 18th

@clintandrewhall
Copy link
Contributor

@alexfrancoeur 💯 ...and this quote 🤣

@kobelb
Copy link
Contributor

kobelb commented Dec 15, 2020

My personal feeling is that entity feels rather technical in nature and assets is easier to grasp as an end user. If the only places you see entity are in the API or administrative management UI, I could see entity as an option.

Fair enough, I've been convinced that using the term "asset" is reasonable.

@VijayDoshi
Copy link

VijayDoshi commented Dec 17, 2020

I'm +1 for "asset" to describe "things" and that it should be used consistently. To me it feels less technical, more user friendly and understandable.

WRT to "generated" assets, could that be handled via "created by" Created by: Vijay Doshi | System | Integration ...

@rudolf
Copy link
Contributor

rudolf commented Dec 18, 2020

Aren't we just exchanging one vague term for another vague one?

object: "a thing"
asset: "something of value"

I want to question the assumption that this will be easier for users to understand. I am not aware of any other products using this terminology? When a term has such a vague definition, the only way users can attach meaning to it is if that meaning comes from our own definition, so I think this will just become new Kibana/Elastic-specific nomenclature. Over time users will learn that "Kibana assets" are actually "Saved objects" are actually "fleet-enrollment-api-keys, exception-lists, background-session, api_key_pending_invalidation, cases-connector-mappings".

If we use terminology which only has a vague definition, I wonder if the term is really useful in allowing users to construct a mental model of our product. As an example, once we have an "Asset Library" users might assume that any "Kibana asset" will show up in the "Asset library" but some "assets" like "spaces", "advanced settings" or "tags" would never make sense to embed into a dashboard. So what exactly constitutes an "asset" starts depending on the context where it's used more than anything else.

Saved objects is Kibana's database, users don't know and shouldn't need to know what's inside

"Saved objects" is Kibana's database and I think it's pointless to try to come up with terminology for everything Kibana wants to persist. Kibana has become so much more than just "dashboards, visualizations and index patterns", most of our saved objects are actually system data which users shouldn't have to understand or care about. Here is a complete list of saved object types:

core-usage-stats 
 config 
 task 
 telemetry 
 ui-counter 
 ui-metric 
 application_usage_totals 
 application_usage_daily 
 application_usage_transactional 
 url 
 query 
 kql-telemetry 
 index-pattern 
 search-telemetry 
 sample-data-telemetry 
 file-upload-telemetry 
 visualization 
 tsvb-validation-telemetry 
 background-session 
 canvas-element 
 canvas-workpad 
 canvas-workpad-template 
 graph-workspace 
 timelion-sheet 
 dashboard 
 search 
 space 
 spaces-usage-stats 
 tag 
 maps-telemetry 
 map 
 lens 
 lens-ui-telemetry 
 exception-list-agnostic 
 exception-list 
 upgrade-assistant-reindex-operation 
 upgrade-assistant-telemetry 
 ingest_manager_settings 
 fleet-agents 
 fleet-agent-actions 
 fleet-agent-events 
 ingest-agent-policies 
 fleet-enrollment-api-keys 
 ingest-outputs 
 ingest-package-policies 
 epm-packages 
 enterprise_search_telemetry 
 app_search_telemetry 
 workplace_search_telemetry 
 ml-job 
 ml-telemetry 
 action 
 action_task_params 
 alert 
 api_key_pending_invalidation 
 siem-ui-timeline-note 
 siem-ui-timeline-pinned-event 
 siem-detection-engine-rule-actions 
 siem-detection-engine-rule-status 
 siem-ui-timeline 
 endpoint:user-artifact 
 endpoint:user-artifact-manifest 
 security-solution-signals-migration 
 cases-comments 
 cases-configure 
 cases-connector-mappings 
 cases 
 cases-user-actions 
 infrastructure-ui-source 
 metrics-explorer-view 
 inventory-view 
 monitoring-telemetry 
 apm-indices 
 apm-telemetry 
 uptime-dynamic-settings

Users can't currently see most of these types anywhere in the UI and they shouldn't need to either. Most of this data is only relevant when making a backup/restore.

Do we need a term encompassing everything Kibana stores in it's database?

What would happen if we just dropped "saved objects" altogether?

"Saved objects management" -> Backup / Restore Kibana

Integration "assets"

In the context of the screenshot where we highlight what an integration provides. It makes sense to highlight some saved objects, but as an example for SIEM, users probably don't want the details of every SIEM-related saved object that gets added. And plugins don't expose all the saved object types in their UI. As an hypothetical example siem-connector-mappings-invalidation-list could be a valid saved object type, but it doesn't show up anywhere in the SIEM UI.

Kibana Assets:
siem-ui-timeline-note (2)
siem-ui-timeline-pinned-event (1)
siem-detection-engine-rule-actions (5)
siem-detection-engine-rule-status (10)
siem-ui-timeline (1)
siem-connector-mappings-invalidation-list (1) // extreme hypothetical example

Are there other contexts in our product where users need one word to describe all the data that Kibana creates/saves?

@kobelb
Copy link
Contributor

kobelb commented Dec 18, 2020

I think you have some really good points, @rudolf. My only criticism is that saved-object management isn't just backup / restore, at the moment. There's some functionality currently available in saved-object management that I really think we need to remove (editing the raw JSON of a saved-object); however, I think we should continue to provide a single UI that lists all of Kibana's user-facing "things" and allows them to be deleted. I don't think that we should require users to navigate to the individual Kibana applications to be able to "clean up" a mess that they or others made. This seems like a really painful experience. This is what makes me think that we'll continue to need a "things" management UI.

@VijayDoshi
Copy link

I want to question the assumption that this will be easier for users to understand. I am not aware of any other products using this terminology?

@rudolf I've seen this term in many products. Generally, something intended for reuse is the qualifying criteria. Here are some examples:

Adobe:
https://www.adobe.com/experience-cloud/topics/digital-asset-management.html
https://helpx.adobe.com/illustrator/using/creative-cloud-libraries-sync-share-assets.html

Microsoft Sharepoint:
https://docs.microsoft.com/en-us/sharepoint/organization-assets-library

Salesforce:
https://help.salesforce.com/articleView?id=admin_files_asset_files.htm&type=5

Google Studio:
https://support.google.com/richmedia/answer/6011683?hl=en

IBM:
https://www.ibm.com/support/knowledgecenter/SSUS84_7.5.4/com.ibm.ram.web.doc/topics/t_collaborate.html

@rudolf
Copy link
Contributor

rudolf commented Jan 7, 2021

@kobelb

I think we should continue to provide a single UI that lists all of Kibana's user-facing "things" and allows them to be deleted. I don't think that we should require users to navigate to the individual Kibana applications to be able to "clean up" a mess that they or others made. This seems like a really painful experience. This is what makes me think that we'll continue to need a "things" management UI.

Being able to peek into Kibana's database is powerful and makes otherwise painful processes simpler, but the power is also dangerous making it easy to break Kibana or loose data by deleting something that seemed like an unnecessary/unused saved object. I don't have a strong opinion on this, but I lean towards removing more power and protecting users (and keeping the API as an escape hatch).

@VijayDoshi
I'm not familiar with all these products, but from a surface reading of the linked documentation assets seems to be static files, media, packaged applications etc. You can replace an asset with a new one but these products don't describe something like Kibana's Advanced Settings where you can toggle individual fields as an "asset". I think these examples confirm @kobelb 's comment:

Initially, I was in-favor of using the word assets to describe all of Kibana's "things". However, I think that @timroes and others raised a good concern about assets inaccurately portraying these "things" as being static in nature. For example, I've previously used the word assets to describe the non-code parts of a web-application: images, css, fonts.

If we need one generic word to describe everything Kibana stores in Elasticsearch my vote would go towards "Kibana data".

@alexfrancoeur
Copy link
Author

Thank you all for your thoughts around this topic and apologies for dropping the ball on closing the loop here. I've had a few follow up discussions on this topic recently and I think generally there is still a need to differentiate user generated / user consumed entities vs. Kibana entities. Saved objects can mean something different depending who you talk to or where you are in Kibana.

For a new user who is simply looking to install an integration, copy a dashboard to another space, or in the not too distant future, share across spaces, a saved object is not an obvious description. And while referring to SO's may not always be necessary in product, we'll never completely be able to get away from it. We don't necessarily need to call these entities "assets", but we should have a consistent description across our products. At the moment, integrations refer to these as "Kibana assets".

I realize we're closing in on 8.0 here, so I'm not suggesting we make changes to the underlying endpoints, but I think there is there an opportunity to differentiate terminology that describes end user facing saved objects and "system" generated saved objects. We can formerly iterate, brainstorm and vote on what this naming convention is, but if we want to be consistent across the UI, it'd be good to finalize this discussion soon. If there's general agreement that we need this split, I'm happy to refocus on terminology with some additional options.

cc: @thesmallestduck

@rayafratkina
Copy link
Contributor

+1 to formalizing the split and coming up with better user-facing names. SOs is an Elastic term that does not mean what we think it means to end users and does not add value to understanding our product. Let's change our tools to speak our users' language instead of forcing them to learn ours.

@alexfrancoeur
Copy link
Author

Thank you everyone for your input and patience on this topic. After syncing with a number of folks, I think we're all in agreement that we should not "burden" our end users with nomenclature that is not obvious to them. The best way to do this, is through the user experiences for Kibana users. The bulk of SO's today live under the umbrella of Analytics. With the introduction of the Visualize Library in 7.12, we are adding a new layer of abstraction to SO's for most end users. If we wanted to, it is possible this could evolve into an Asset Library in the future.

Naming is hard and we've gone in circles on this issue behind the meaning of certain words and how they relate to the entities that are most crucial to Kibana. I'll close out this issue with the decision to keep the status quo and continue to add layers of abstraction to our end users, assuming the terminology will diminish as more in-app experiences are introduced.

I'm happy to discuss this topic in more detail if anyone is interested, but with the recent focus on improving SO's, it felt like we needed to come to a decision sooner than later. And in this case, there was not enough benefit to formally change the name. Thank you all again for your participation in this lively discussion!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
discuss Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc
Projects
None yet
Development

No branches or pull requests

9 participants