persistable state docs #105202
persistable state docs #105202
Conversation
|
Pinging @elastic/kibana-app-services (Team:AppServices) |
ppisljar
added
the
release_note:skip
stacey-gammon
left a comment
stacey-gammon
left a comment
There was a problem hiding this comment.
Only reviewed a little bit because I have some code change suggestions I'd like to discuss before we merge this.
Co-authored-by: Stacey Gammon <gammon@elastic.co>
…ibana into persistablestate/docs
Co-authored-by: Stacey Gammon <gammon@elastic.co>
…istablestate/docs
| and reference extraction and injection methods correctly use the correct `PersistableStateService` implementation. | ||
|
|
||
| If a saved object contains state from another plugin, the <DocLink id="kibCoreSavedObjectsPluginApi" section="iaf33fb81-e64a-11eb-8631-9d6e17a74ca4" text-"SavedObjectType.migrations"/> parameter should be a function, which returns a list of migrations. | ||
| These migration functions will need to merge the migration functions returned from <DocLInk id="" section="" text="PersistableStateServices.getAllMigrations"/> with any migrations provided by the plugin. |
There was a problem hiding this comment.
DocLink id and section need to get filled in.
There was a problem hiding this comment.
those docs don't exist yet so i'll remove it
There was a problem hiding this comment.
I'm talking about linking to the API docs for that function. Do the API docs need to be re-generated? If so, I can do that. I'm assuming the function exists, otherwise, we shouldn't be adding documentation recommending its usage. :)
Co-authored-by: Stacey Gammon <gammon@elastic.co>
…istablestate/docs
| ## Exposing state that can be persisted but is not owned by plugin exposing it (registry) | ||
|
|
||
| Any plugin that owns collection of items whose state/configuration can be persisted should implement `PersistableStateService` | ||
| interface on their `setup` contract as well as make each item in the collection implement `PersistableStateDefinition` interface. |
There was a problem hiding this comment.
make each item in the collection implement
PersistableStateDefinitioninterface.
Is it the plugin that is registering the item that will have to implement the PersistableStateDefinition interface on the item? Or is it the plugin that owns the collection?
There was a problem hiding this comment.
its the plugin providing the registry that defines how the items that are added to the registry look like
| stores a bunch of embeddable panels input in its saved object and URL. Embeddable plugin setup contract implements `PersistableStateService` | ||
| interface and each `EmbeddableFactory` needs to implement `PersistableStateDefinition` interface. | ||
|
|
||
| note: if your plugin doesn't expose the state and is thus the only one storing state but still owning the registry |
There was a problem hiding this comment.
Might be worth rewording this to something like:
if your plugin doesn't expose state, then your plugin doesn't need to implement PersistableStateServiceinterface on thesetupcontract. If your plugin provide registration functionality for items it will not own the state for, the items should still implementPersistableStateDefinition`.
| and reference extraction and injection methods correctly use the correct `PersistableStateService` implementation. | ||
|
|
||
| If a saved object contains state from another plugin, the <DocLink id="kibCoreSavedObjectsPluginApi" section="iaf33fb81-e64a-11eb-8631-9d6e17a74ca4" text-"SavedObjectType.migrations"/> parameter should be a function, which returns a list of migrations. | ||
| These migration functions will need to merge the migration functions returned from with any migrations provided by the plugin. |
There was a problem hiding this comment.
This sentence is a bit confusing to me. Is the These migration functions referring to the function parameter in the previous sentence or the list of migrations that the previous sentence is talking about?
Is this trying to say: the parameter function needs to call a call the plugin that owns the state it is trying to persistent and merge the result of that call into an array of migration functions with any migration logic that the parameter function will provide for state it also exposes?
An example might be helpful here.
| If a saved object contains state from another plugin, the <DocLink id="kibCoreSavedObjectsPluginApi" section="iaf33fb81-e64a-11eb-8631-9d6e17a74ca4" text-"SavedObjectType.migrations"/> parameter should be a function, which returns a list of migrations. | ||
| These migration functions will need to merge the migration functions returned from with any migrations provided by the plugin. | ||
|
|
||
| For reference injection and extraction matching methods on PersistableStateService should be called and merged with plugins own array of references. |
There was a problem hiding this comment.
A code example here might be helpful.
|
|
||
| ### Storing persistable state as part of URL | ||
|
|
||
| When storing persistable state as part of URL you must make sure your URL is versioned. When loading the state `migrateToLatest` method |
There was a problem hiding this comment.
When storing persistable state as part of URL you must make sure your URL is versioned
Do we have suggestions on how to version the URL? Is it simply adding some field that has a version value in it?
There was a problem hiding this comment.
nothing, its completely up to the app how it does that.
| ### Storing persistable state as part of URL | ||
|
|
||
| When storing persistable state as part of URL you must make sure your URL is versioned. When loading the state `migrateToLatest` method | ||
| of `PersistableStateService` should be called, which will given the original version of state migrate it to latest. |
There was a problem hiding this comment.
of
PersistableStateServiceshould be called, which will given the original version of state migrate it to latest.
Maybe switch this to:
of PersistableStateService should be called, which will migrate the state from its original version to the latest.
|
|
||
| ### Migrations and Backward compatibility | ||
|
|
||
| As your plugin evolves, you may need to change your state in a breaking way. If that happens, you should write a migration to upgrade the any state that existed prior to the change. |
There was a problem hiding this comment.
nit: the any -> the or any
migration to upgrade the any state that existed prior to the change. -> migration to upgrade the state that existed prior to the change.
|
@elasticmachine merge upstream |
stacey-gammon
left a comment
stacey-gammon
left a comment
There was a problem hiding this comment.
Some nits and links added, otherwise, LGTM
examples/embeddable_examples/server/searchable_list_saved_object.ts
Outdated
Show resolved
Hide resolved
Co-authored-by: Stacey Gammon <gammon@elastic.co>
jloleysens
left a comment
jloleysens
left a comment
There was a problem hiding this comment.
Thanks for adding this Peter! I'm sure this will be a helpful reference for working with persistable state.
| stores a bunch of embeddable panels input in its saved object and URL. Embeddable plugin setup contract implements `PersistableStateService` | ||
| interface and each `EmbeddableFactory` needs to implement `PersistableStateDefinition` interface. | ||
|
|
||
| Embeddable plugin exposes this interfaces: |
There was a problem hiding this comment.
| Embeddable plugin exposes this interfaces: | |
| Embeddable plugin exposes these interfaces: |
| Any plugin that stores any persistable state as part of their saved object should make sure that its saved object migration | ||
| and reference extraction and injection methods correctly use the matching `PersistableStateService` implementation for the state they are storing. | ||
|
|
||
| Take a look at [example saved object](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/server/searchable_list_saved_object.ts#L32) which stores an embeddable state. Note how the `migrations`, `extractReferences` and `injectReferences` are defined. |
There was a problem hiding this comment.
I followed this link (in the context of PR changes) and I did not see extractReferences or injectReferences there. I see this PR contains changes that introduce extract and inject in examples/embeddable_examples/public/migrations/migrations_embeddable_factory.ts. Is this what is being referred to here?
| When storing persistable state as part of URL you must make sure your URL is versioned. When loading the state `migrateToLatest` method | ||
| of `PersistableStateService` should be called, which will migrate the state from its original version to latest. | ||
|
|
||
| note: Currently there is no recommended way on how to store version in url and its up to every application to decide on how to implement that. |
There was a problem hiding this comment.
Are there some ways we specifically don't recommend plugins store the version in the URL. Like as a param in the path: /my-path/8.0.0/the-rest-of/my-path based on feedback we got on this point? (I'm thinking of things like product-level concerns).
Perhaps we can borrow the structure of the LocatorParams which has a containing object: { version: 'a.b.c', state } as our recommendation?
There was a problem hiding this comment.
we leave it completely up to the plugins how they want to do this.
…ibana into persistablestate/docs
|
@elasticmachine merge upstream |
|
@elasticmachine merge upstream |
ppisljar
force-pushed
the
persistablestate/docs
branch
from
f88c98b to
a987ce9
Compare
💚 Build SucceededMetrics [docs]Public APIs missing comments
History
To update your PR or re-run it, just comment with: |
stacey-gammon
added
the
auto-backport
💚 Backport successful
This backport PR will be merged automatically after passing CI. |
8 participants
Summary
adds initial guide doc for persistable state
resolves #103105