Update persistence.md #527

bgilmer77 · 2017-10-13T03:10:35Z

updates persistence.md by adding content from old wiki article
removes references to old wiki article
Resolves persistence.md should be rewritten #524

Signed-off-by: Brad Gilmer brad@gilmer.tv (github:bgilmer77)

- updates persistence.md by adding content from old wiki article - removes references to old wiki article - addresses #524

bgilmer77 · 2017-10-13T03:14:02Z

I closed a previous PR with the same name because I had made an error, committing changes in this branch that actually were meant to be directed to sitemaps.md. This PR includes comments received on the last PR by @Confectrician

Confectrician · 2017-10-16T14:51:42Z

To get some progress here:
If no one else has to add something...

LGTM

ThomDietrich

Hey @Confectrician, thanks for jumping in!! Your help and opinion is very much appreciated and as you can see, sometimes I'm preoccupied with other things. Good thing there are you guys out there 😉 While I agree that the initial version looks good, I couldn't hold myself back with some comments...

Hey @bgilmer77,
I'm unsure if your goal was to first move the wiki article over. I've added some remarks for the first part. Let me know how you'd like to proceed.

Best! Thomas

ThomDietrich · 2017-10-16T15:48:15Z

configuration/persistence.md

-openHAB is not restricted to a single data store.
-Different stores can co-exist and be configured independently.
-For further details, please check:
+## Introduction


I can't remember by whom but I was once taught to never have two headlines following each other without at least one filler sentence. 🙃

Absolutely - otherwise why have the second heading. I will delete the heading "Introduction". It is at the beginning - it is introductory text - does not need its own header.

Oh - and to answer your initial question, when I was working on the sitemap article I clicked over to persistence and noticed it was basically a stub pointing to the wiki, so I decided to bring the wiki text into this project. I tried, in the first pass, to correct any glaring issues and to make it OH2 specific, but my main emphasis was just to get something on persistence into the documentation with everything else.

My two cents would be to merge this fairly quickly. It would be good to have it up and available. (But it needs to be factually accurate.)

ThomDietrich · 2017-10-16T15:50:28Z

configuration/persistence.md


- The list of supported [Persistence Services]({{base}}/addons/persistence.html)
- [The openHAB 1.x wiki persistence article](https://github.com/openhab/openhab/wiki/Persistence)
+openHAB has the ability to save item states according to rules you have configured.


"rules" could be misunderstood as a relation to openHAB rules.

The most important info in the first sentence should be storing of data over time, not the way that is achieved, imho.

Yep - see next comment.

ThomDietrich · 2017-10-16T15:51:27Z

configuration/persistence.md

+Persistence can have several important uses.
+For example, persistence allows an openHAB system to restore itself to the state it was in prior to a restart (if you have configured it to do so).
+Persistence may also be used to store values that are subsequently displayed in a graph.
+(For an excellent graphing tutorial see [InfluxDB+Grafana persistence and graphing](https://community.openhab.org/t/influxdb-grafana-persistence-and-graphing/13761).


Feels like this paragraph can be shortened.

As much as I feel honored that you want to highlight the InfluxDB example here, please leave it out. The documentation should stay with the facts.

The use case description is imho a bit inside out.

Here's my go on it: Persistence allows to store data time; Data can be retrieved; e.g. inside rules, for graphs or to restore on startup.

Okay - but it is a super great article.

How about this...
openHAB can store data over time; this is known as persistence.
The data may be retrieved at a later time, for example to restore your system after startup, or to prepare graphs for display on a UI.

Sounds good.

ThomDietrich · 2017-10-16T15:58:58Z

configuration/persistence.md

+Examples of available persistence add-ons include relational databases, NoSQL databases, round-robin databases, Internet-of-Things (IoT) cloud services, simple log files, etc.
+All of these options are available in openHAB, and they are all configured in the same way.
+Note that the type of database(s) you use for persistence may be influenced by your requirements for exporting data (e.g. IoT services or log files), or your requirement to make queries against the database to retrieve historical data (e.g. MySQL and MongoDB).
+A complete list of supported persistence add-ons may be found in the [persistence]({{base}}/addons/persistence.html) section of the on-line openHAB documentation.


Feels like this paragraph can be condensed considerably

The last sentence should be its own paragraph

Yep. I will delete all the stuff about example databases, etc.

The whole thing reduces to three sentences. See my next commit.

ThomDietrich · 2017-10-16T15:59:59Z

configuration/persistence.md

+Therefore, it is important to select a default persistence service.
+You should do this even if you have only one persistence add-on installed.
+
+To select a default persistence service, in paperUI, select Configuration and then System from the side menu.


ThomDietrich · 2017-10-16T16:02:18Z

configuration/persistence.md

+You can choose how your persistence service operates, which item states it persists, and under what conditions it persists them.
+These things and more are configured in a file named `<persistenceservice>.persist`, where "persistenceservice" is replaced by the name of your add-on (e.g. `rrd4j.persist`).
+This folder is located in `$OPENHAB_CONF/persistence`.
+The configuration defines persistence "strategies" which are very similar to [triggers]({{base}}/configuration/rules-dsl.html#rule-triggers) in openHAB rules.


A weird comparison I can't agree with. It's from the wiki and if you agree, I'd vote to remove it.

Made no sense to me - it's gone. See below.

ThomDietrich · 2017-10-16T16:03:21Z

configuration/persistence.md

+These things and more are configured in a file named `<persistenceservice>.persist`, where "persistenceservice" is replaced by the name of your add-on (e.g. `rrd4j.persist`).
+This folder is located in `$OPENHAB_CONF/persistence`.
+The configuration defines persistence "strategies" which are very similar to [triggers]({{base}}/configuration/rules-dsl.html#rule-triggers) in openHAB rules.
+These strategies may be used to persist an item state when some bus event has occurred (e.g. an item state has been updated or changed), or on a schedule or at a specific time of day (e.g. through a [cron expression](http://www.quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/crontrigger).


please remove bus.

Again this paragraph seems too long and can probably be condensed.

Entire Configuration section now as follows:

Persistence Strategies are configured in a file named <persistenceservice>.persist, stored in $OPENHAB_CONF/persistence ("persistenceservice" is replaced by the name of your add-on (e.g. rrd4j.persist)).

Strategies may be used to persist an Item state when some event has occurred (e.g. an Item state has been updated or changed), on a time schedule, or at a specific time of day (e.g. through a cron expression.

Persistence configuration files consist of several sections:

ThomDietrich · 2017-10-16T16:09:19Z

configuration/persistence.md

+The configuration defines persistence "strategies" which are very similar to [triggers]({{base}}/configuration/rules-dsl.html#rule-triggers) in openHAB rules.
+These strategies may be used to persist an item state when some bus event has occurred (e.g. an item state has been updated or changed), or on a schedule or at a specific time of day (e.g. through a [cron expression](http://www.quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/crontrigger).
+
+Persistence configuration files consist of several sections:


Instead of the two code blocks in the below sections how about one less abstract example here.
In the Items and the Transformations article I've switched over to simple examples rather than non intuitive formal definitions. We should strive for a good middle path...

Yep - the point is to improve comprehension, not prove how clever one can be. People can go to the Community and tutorials for more complex examples. Generally speaking, it is my feeling that this documentation should aim to get people up and running with a basic system.

ThomDietrich · 2017-10-16T16:11:16Z

configuration/persistence.md

+}
+```
+
+Note that the `Strategies` section must be included, and that it must define a default, or the persistence service will not work.


I can tell you for a fact that default is not needed 😄

ThomDietrich · 2017-10-16T16:12:18Z

configuration/persistence.md

+
+- everyChange: persist the item state whenever its state has changed
+- everyUpdate: persist the item state whenever its state has been updated, even if it did not change
+- restoreOnStartup: load and initialize the last persisted item state on openHAB startup (if the item state is undefined (`UNDEF`)).  This strategy is extremely useful for items that are not updated through a Thing with a Binding to something in the real world.


Add "see below" instead of the extra sentence?

Definitely.

Confectrician · 2017-10-16T16:20:56Z

While I agree that the initial version looks good, I couldn't hold myself back with some comments...

That's why I asked and i think that's one reason for double checking everything. :)

bgilmer77 · 2017-10-17T21:01:44Z

Question - search and replace "item" with "Item"?

- See GitHub Conversation page for comments addressed.

ThomDietrich · 2017-10-18T00:10:36Z

Yes please :)

- Capitalized all instances of "Item" - Did NOT capitalize all instances of "items"

bgilmer77 · 2017-10-19T22:07:00Z

All instances of "Item" capitalized. Did not capitalize all instances of "items". Okay?

ThomDietrich · 2017-10-20T11:34:10Z

Hey @bgilmer77,
in one of your comments you said that it would be good to merge this article as soon as possible. I agree and will do that now. Thanks for the addition and the great improvement of this article!! 🎉

That said, I think it would be good if you could open a new PR with these and more changes:

Second paragraph: "that" -> "than"
Clashing headlines: "Persistence Add-on Configuration" vs "Configuration"
Strategies section: default missing (yes it is not mandatory but should still be part of the syntax description)
Example: I would vote to remove the ALL example. Many users do that and it is my honest opinion that this is bad system design. Users should select items to be persisted, not blindly persist the state of every light switch...
Add a section to justify cron settings (when can what be recommended)
persistence extensions: move to itemization rather than being a code block
...

Best! Thomas

bgilmer77 · 2017-10-20T11:46:11Z

@ThomDietrich, perfect. I agree more changes are definitely required. I will start working on your list above. I have a few things myself.

Addressing comments left over from openhab#527 - Changed that -> than - Resolved clashing headlines - Strategies section: added `default` and explained its operation - Changed persistence extensions from code block to itemized list

@Confectrician

* Additional improvements to persistence article Addressing comments left over from #527 - Changed that -> than - Resolved clashing headlines - Strategies section: added `default` and explained its operation - Changed persistence extensions from code block to itemized list * Improve readability of Strategies and Items sections - Reworded some of tne introductory material - Reorganized and changed some sub-section titles in Strategies and Items area to improve comprehension. - Item Persistence Configuration -> Persistence Configuration - Added Persistence Trigers section - Strategies section -> Strategies - Items section -> Items - Addressed comments by @Confectrician * Address numerous comments from @ThomDietrich - Deleted one configuration headline - Added intro sentence to configuration section - Combined all text about default in one section of the document - corrected cronexpression angle bracket error - added code fence around everyChange, etc. - Removed detail of Quartz stuff and just added a pointer to Rules article - Replaced "persist everything" example to persisting Heating_Mode, etc..." - Added example of how default works. * Finishes "nit" pass through Persistence article - Numerous small changes to improve readability * Expand explanation of how one may specify persistence for an Item - Existing text was not clear about the syntax one would use with a Persistence Extension in order to specify a persistence store in cases where multiple stores are available. - Clarified language and added an example. * Correct formating of Persistence Extensions - Removed extra lines - Added code fences Signed-off-by: Brad Gilmer <brad@gilmer.tv> (github: bgilmer77) * Format Persistence Extensions as a table - Changed Persistence Extensions section from a non-enumerated list to a table - Fixed a spelling error in the section on restoring items after a restart Signed-off-by: Brad Gilmer <brad@gilmer.tv> (github: bgilmer77) * Fix markdown table style Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich)

Update persistence.md

d58cd3d

- updates persistence.md by adding content from old wiki article - removes references to old wiki article - addresses #524

ThomDietrich reviewed Oct 16, 2017

View reviewed changes

Address comments from @ThomDietrich

6e75233

- See GitHub Conversation page for comments addressed.

Capitalize all instances of "Item"

1a28074

- Capitalized all instances of "Item" - Did NOT capitalize all instances of "items"

ThomDietrich merged commit 177101f into openhab:gh-pages Oct 20, 2017

bgilmer77 deleted the persistence-from-wiki branch October 20, 2017 11:52

bgilmer77 mentioned this pull request Oct 20, 2017

Additional improvements to persistence article #535

Merged

Confectrician added this to the 2.x.x milestone Nov 18, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update persistence.md #527

Update persistence.md #527

bgilmer77 commented Oct 13, 2017 •

edited by ThomDietrich

bgilmer77 commented Oct 13, 2017 •

edited

Confectrician commented Oct 16, 2017 •

edited

ThomDietrich left a comment

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

bgilmer77 Oct 17, 2017

ThomDietrich Oct 16, 2017 •

edited

bgilmer77 Oct 17, 2017

ThomDietrich Oct 16, 2017

ThomDietrich Oct 16, 2017

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

Confectrician Oct 17, 2017

ThomDietrich Oct 16, 2017

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

ThomDietrich Oct 16, 2017

ThomDietrich Oct 16, 2017

bgilmer77 Oct 17, 2017

Confectrician commented Oct 16, 2017

bgilmer77 commented Oct 17, 2017

ThomDietrich commented Oct 18, 2017

bgilmer77 commented Oct 19, 2017

ThomDietrich commented Oct 20, 2017 •

edited

bgilmer77 commented Oct 20, 2017

Update persistence.md #527

Update persistence.md #527

Conversation

bgilmer77 commented Oct 13, 2017 • edited by ThomDietrich

bgilmer77 commented Oct 13, 2017 • edited

Confectrician commented Oct 16, 2017 • edited

ThomDietrich left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ThomDietrich Oct 16, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Confectrician commented Oct 16, 2017

bgilmer77 commented Oct 17, 2017

ThomDietrich commented Oct 18, 2017

bgilmer77 commented Oct 19, 2017

ThomDietrich commented Oct 20, 2017 • edited

bgilmer77 commented Oct 20, 2017

bgilmer77 commented Oct 13, 2017 •

edited by ThomDietrich

bgilmer77 commented Oct 13, 2017 •

edited

Confectrician commented Oct 16, 2017 •

edited

ThomDietrich Oct 16, 2017 •

edited

ThomDietrich commented Oct 20, 2017 •

edited