OH3 how view textual definition of an Item

I have been around here about 2 years and still feel like a newcomer at times, especially recently with the OH3 release.

Some if my recent discoveries have been somewhat of a culture shock for me, shattering some of what I considered basic assumptions.

The REST API in OH3 has authentication ow so things get more complicated accessing outside of API Explorer.

1 Like

This will be in the reference docs for sure (if it’s not there already). But it won’t be covered in getting started.

It’s basically exactly the same only using a more recent version of Swagger. What I find annoying is that you have to click “Try it out” before it will let you enter anything into the forms. Unfortunately that is a feature controlled be Swagger and we can’t change it.

Yes, if the HTML command is a GET. Otherwise using curl on the command line or using the API explorer would be easiest. Authentication may be required.

1 Like

Agreed!

:cry: I got through that so I care less now, but please be aware that a big turnoff for a new user is trying to follow the tutorial, having things not working as intended, and not being able to understand why - and having no tools to investigate (apart for deleting everything an rebulding hoping that it goes right without knowing why).
This is what originates “documentation is bad” or “system buggy” feelings.
Saying just because we agreed I would collaborate giving a first time user view on doc.

Not everything can go into a Getting Started Tutorial. That’s what the reference guides are for. If we put every single thing that some users might find useful at some point under some circumstances than people will be complaining that the tutorial is too long and complex to follow.

Believe it or not, the vast majority of openHAB users will never look at the JSON and wouldn’t know what to do with it if they did. So why bring in that to the Getting Started tutorial? And even here it’s not clear to me what problem you actually had and whether looking at the JSONDB entry would have been the best way to solve the problem. And you’ve already extended beyond the getting stated tutorial anyway. Defining Items textually isn’t covered by the tutorial. And as you said, it worked when you defined the Item through the UI. So I need to include low level details about how to debug a problem that only exists if you do things in a way not covered by the tutorial?

There will be something written about debugging and addressing problems along the way. But looking at the JSON is not going to be a part of that.

Collaboration doesn’t mean I have to agree with every suggestion. If my reserving super low level technical detail for the reference docs instead of getting started means the documentation is bad, then someone else can write them.

But I don’t mean that you have to add pages breaking the flow. Hyperlinks are designed for that purpose - you click on them if you are interested. We are not talking of a paper manual.
Link can also point to outdated pages, framed with a header sayng “refers to OH2 - needs upodate” better than nil.

again, I was talking of hyperlinks. In a page you can just add a sentence like “If you are interested in the underlying textual definition, you can check this out (link)” Easy peasy. I don’t think anyone can complain about that.

OK, you’re upset. You obviously have the final say - or as you did earlier, invite people to contribute writing drafts and commit on GH.
So much for VOC (voice of customer, in quality systems like VDA). No worries, I won’t annoy you further :peace_symbol: Take care :slight_smile:

It’s not a bother and I’m not upset. But the point still remains, just because I asked for suggestions does not mean I have to accept them all. I believe I’m implemented (or plan to implement) every single other suggestion you’ve made. But if I disagree with just this one suggestion I’m ignoring you and you’re out?

That statement wasn’t a throw away rhetorical one. I literally mean that if someone else disagree with me, they are welcome to write to write docs too. I don’t have any proprietary ownership of the the docs. But the person who is actually writing the docs gets final say. If you don’t like my final say, you can have your own final say by writing the docs too. Adding new content is almost never refused. I certainly won’t reverse any such edit.

But in this one case I disagree. Looking at the JSON wouldn’t have helped with a problem caused by defining Items through the UI. Looking at the JSON isn’t going to help with a problem caused by defining Things, or Rules, or Pages through the UI either. So I still maintain that adding a link in the Getting Started Tutorial to the JSONDB stuff isn’t useful. That doesn’t mean there won’t be any debugging and problem solving stuff in the tutorial. at all. But what is appropriate for those who are actually following the tutorial will be the focus.

Even if they double your pay? LOL :rofl:

1 Like

nope! But please try to understand my twisted mind. I am looking at a friggin 2001 Space Odissey monolith (methaphor: translate it in OH 3 for an absolute beginner who knows 0 about OH) and I think that users like me (yes, not the user that buys a black box and expects some easypeasy step to plug it in OH - you must have understood I’m of the kind “despise black box solution, develop from scratch, it’s a life journey etc”) can be astonished at seeing that in 2020 adding a hyperlink to deep documentation is an issue. You know what I mean? Href anybody?
I can do that if I understnd where that documentation in the old repository is. Would you allow? as some branch in GIT? I just did for the Win installation. Pls do advice! I’m not a complete couch potato! Use resources! And you big fella can obviously dislike and discard the pull! I’m no foundation member!

you are probably right. But here is the good old bias: you know how to get around issues. I’m a new user (am I the target of your tutorial?! 3 days ago was the first google result for IOT automation) discovered this is a known bug. undocumented (in your tutorial). I spent 3.5 hours in friggin frustrating deleting and rebuilding to try to discriminate wheter it was

  • a bug of the system
  • something I did not do right
  • something I did not understand right

You do understand the fractal of tries which originate from the combination of those options, right? I did get to the point of considering reinstalling the whole OH3. that’s being a beginner in any IT complex platform, OH included.
It went through posting a bug report on GIt and following up with a 6 hours test.
Yes, I’m advanced (?!) - BUT don’t you feel you are there to protect ppl who have not the (limited) toolkit I can enjoy by some experience? And you board, pls ask yourself where those ppl end up when attempts do not land anywhere workable.
That’s why doc are there.
Hope this makes sense to you. Not meaning to argue - I have a quarrel open with cura settings for 3d printing now…

It’s not the creation of the href. That takes seconds. It has to do with the purpose of the tutorial over all. This specific link goes against the purpose of the tutorial. It’s a link to a page that is not relevant to getting started. And while you found it useful in your specific case, you only found it useful because you were trying to debug a problem that was caused by doing things in a way not included in the Getting Started Tutorial.

So from my side it’s including a link to material that is not “getting started” level to help people debug a problem caused by not following the Getting Started Tutorial in the first place. At best it adds noise. At worst it adds confusion.

Again, I’m not saying there shouldn’t be content and links to stuff that will help users debug problems. I disagree with specifically linking to the JSONDB from the Getting Started tutorial for that purpose.

Just to be clear, we are really talking about a page in the Getting Started Tutorial that doesn’t exist yet. Only up to Persistence has gone live (note that Persistence was not part of these wiki pages). And there are about three pages that need to be written from scratch too, one of which is “when problems occur.”

And when problems occur, new users shouldn’t be going to the JSONDB. They should be going to the forum to ask for help long before going to the JSONDB. Even suggesting otherwise is frankly a waste of those user’s time.

It’s not bias. If you had created your Item through the UI there wouldn’t have been a problem. You said it yourself that UI created Items worked. Creating Items through the UI is the only way to create Items presented in the tutorial. And if something goes wrong when creating an Item through the UI, there are a bunch of other things to look at and do, including coming to the forum for help, that would be recommended before looking at the JSONDB.

You’re right, and I know that looking at the JSONDB, especially for a new user, is not the best way to diagnose and debug these problems.

Yes I do, which is why pointing users to the JSONDB from the Getting Started Tutorial is a bad idea. It’s not protecting them, it’s throwing them to the wolves.

Again, I’m not saying we should not have debug information in the Getting Started Tutorial. We definitely need it. All I’m saying is that providing a link to JSONDB isn’t going to be part of that. There are better ways.

OK, but please suggest in the tutorial what these debugging tools should be. Pls consider adding a debugging tools page then to encapsulate your experience targeted at newcomers maybe?
I tried with JSONDB not for fun but because it was the best thing which came to my mind since there was no directions to understand what the OH system made out of my gazillion attempts to make a stuff work. Question being ok - what’s the current system status after all the stuff I did? Should I truncate the whole installation to be sure there is not something I did and - I don’t understand yet -is breaking things?
So what’s the practical recommendation for “better ways”? I did not find them in your tutorial (maybe my bad).
In my case, I was trying to add an additional item later on instead of creating all of them at the same time. Because, you see (I’m Italian?! lazy italian? :blush:), when you try to follow a tutorial, you tend not to create three items to follow the flow - you just create one (thinking yadayada what’s the point to create the others if it’s just typing and understandin nil more??)
Doesn’t sound that crazy to me. Is it crazy? So how is the gap between literally following your tutorial and actually walking your own steps meant to be filled? Because if there’s no path, the tutorial becomes a set of tweaks to get to a result - but just in that specific setup.
Not really good for a newcomer who need to be educated to be able to walk his own steps.

As I’ve said, there will be a whole page dedicated to this. It’s just not written yet.

There is not enough details here to say one way or the other but I doubt you have anything that is that broken. Beyond the issue with persistence that you identified and there’s a bug filed, are you seeing anything else that is not working?

Because of all the layers of abstraction between Things and Items and such, it’s pretty hard to completely mess it up to the point where you have to start over. And if that happens, there are automatic backups created on every change. So a restoration of a backup would probably be all that’s required.

It greatly depends on the context. For Rules, Items and Pages the YAML view in the code section is sufficient. For Items, the JSON is directly reflected in the configuration pages. Looking at the event stream in the Developer Sidebar is a way to see if an Item is updating. Creating a scratch pad rule to run me code (also from the Developer Sidebar) to exercise a Rule.

Your specific problem had to do with Persistence. If your Item appeared in the list of Items then it exists and is correctly defined. If not, there will be errors in openhab.log indicating there is a syntax error with your file. So the problem would be either that the Persistence configuration is wrong, the Item is not updating, there is something wrong with persistence, there is something wrong with charting. Testing for and eliminating each of these possibilities would not involve looking at the JSONDB.

Persistence configuration wrong:

  • do other items update?
  • errors in opehab.log?

Item not updating:

  • Developer Sidebar event stream
  • events.log

Something wrong with persistence

  • Errors in openhab.log
  • Errors in the database’s logs
  • lack of any logs whatsoever (indicating maybe the binding isn’t installed)

Something wrong with charting

  • use the native database tools to query and see if data exists
  • use the API explorer to query and see if data exists

Via text files though, which ends up putting you outside the Getting Started Tutorial. Also using a persistence database that is outside the Getting Started Tutorial.

And there was apparently a bug that was the root of your problem. There should be no problem creating Items at any time and in any number for any supported purpose.

1 Like

I wish you folks could embrace temporary placeholder doc pages, where you say “this page is just temporary placeholder doc” and just link to threads you know are relevant in the community like these. Really. I understand does not look posh. But really for a newcomer is better than looking in the community, and wondering if the proposed solution applies to OH3 Again, without the knowledge of a folk like you board fella. We are talking newcomer here. who goes to next and finds doc pages talking about OH2 as if it were business as usual and not even a warning on top of the page saying “WARNING: OH2.x doc to be updated-for reference only”. Come on, how hard is that? You can put a bot on that task when you clone the old doc.
going back:

I feel forum should be the very last resort. I am thinking of it like that: how long does it take for one of you board member to interact on a forum to discuss/encapsulate info like this? wouldn’t it be better for both sides to put a placeholder page where, once for all, you list the relevant forum entries to fix issues? Easy to update - in anycase it will require the contribution of you board fellas, but just once with a big sticky forum topic to inform users to go and read doc first?

Do you believe me if I say that your page[s] (maybe my failure in my quest on the topic “latest doc for OH3”) are the only ones I am reading to understand how get started in OH3? doc in next.openhab…(I think) is outdated. Not sure how often commit happen. My win github pull:no idea when I’ll see that in next.oh. I have thought of going to GIT to read the doc to be sure it’s the latest, even if not commited to the web server yet. How can I be sure? No idea!
So as a new user what should I do? any pdf? any official page? any flag in the community to identify forum entries with official help for OH3?
You guys please give newcomers an entry point. Otherwise it’s really hard&messy unless you are one of the highlanders. -> translated on a new user perspective: doc is lack
EDIT

ahem, not really. using UI

We’re doing the best we can. Honestly, doing that would take as much work as writing it in the first place. And I knew up front I didn’t have time to get it all done before the release. And I didn’t get any help so it’s not done before the release.

I look forward to the PR that implements this.

It’s an ever changing list of “relevant” entries. Bugs occur and are fixed. Features are added. Changes to the way things can be done occur. Breaking changes are introduced. Are you signing up to keep up with the forum and maintaining that list? There are over 350! (that’s factorial, roughly 1e714 or a 1 with 714 zeros after it) combinations of ways you can install just bindings. That doesn’t even include Items, Things, Rules and all the rest. Can you keep up with all that because I sure can’t.

We had it. It’s still there. How to ask a good question / Help Us Help You People get pretty angry when we point them at that post. It doesn’t help. They don’t read them anyway.

As of the release today www.openhab.org/docs are the latest now.

I thought your PR was merged so it should show up next time there is a rebuild of the latest docs.

You have at this point everything that exists. If it’s not good enough then new comers will have to wait until the few of us who have volunteered what time we have to devote to this can get the docs written.

To use a common idiom, no shit sherlock. But do you believe me when I say we are doing the best we can? Because outside of the few constructive comments all I’m really getting is “I’m frustrated, and your shitty docs are at fault.”

:cry: Gosh. Wish I could help. This can be scripted.

Vbscript or whatever, you don’t have to do that manually.

I have always been on the user side of this… I’ll have a look. It’s a script gosh. You branch, apply script, review changes, pull, commit. done. :fearful: Client side. bot is your butler. After all, you just need to inject a div in HTML, with a css class you control once for all formatting everywhere across the site, it’s SO trivial!

Woah. I did not read it because, from the title, it sounded like the usual duplicate of the similar items when you create a new post. Change the title maybe? Like “What to do first if you have a problem”? The how to ask a good question can be queued to the content - frankly it sounds cosmetic (reading the title i thought it must be [specify os, OH version, JAva version] etc etc. -read in so many forums. Title not really fitting an Italian translation into "move your lazy axx to this next.yada.com doc homepage first and come back saying “I read x and does not cover my issue y”)

surprised. I thought www.openhab.org/docs was for OH2 and next.openhab.org/docs for OH3 :sob: :scream: :confounded:

I do. I really do. I would not have so much patience asyou proof to have. Wish you could enroll some helping hands, wish I could help more. feel free to ask.
Unfortunately I don’t know how OH team is structured (frontend docend corehand etc) and interact and cannot help much :slightly_frowning_face: Well, I’ll keep tuned in nd do what I can-help when I’m enrolled.

But here’s the thing. It has to be something that can be included as part of the build system for the docs. It’s actually quite complex to create the docs pages because so much of it comes from multiple repos, they have to be compiled, there are tests that are run and all that.

I guess what I’ve been trying to say is if it really were that easy, don’t you think we would have done it already? So the above was a snarky way to say “since you think it’s so easy clearly you must know more than we do so please show us how to do it.” Just about everyone here who contributes to OH is technically competent. When we see “it’s so easy, just do X” it means either there really is something technical we’ve missed in which case we need help, the poster is ignorant about the technical problems or how much effort it will take, or the poster is discounting our own expertise and assume we are just stubborn or don’t care.

next.openhab.org was always and ever intended as a staging area for us to work prior to OH 3 release without disrupting the 2.5 docs too much. The default version of the docs one sees when they go to the docs is always for the current release version of OH. OH 3 wasn’t released until today.

There really isn’t much of a structure. Most of the time the really technical stuff gets updated by the developers themselves (not always :frowning: ). For the rest, it’s a self selected group of a few people who choose something and start work on it. Open an issue to say you are working on something and if something isn’t already in work for that content, you basically can get to work. I wasn’t assigned the Getting Started Tutorial. I didn’t even write most of it. Yannick wrote most of it. I’ve taking over much of the work so Yannick can focus on the code. I saw a need, stepped up and started doing. That’s how it works.

Someone needs to see a need and jump in and contribute. You’ve already gone through the GitHub pain to get started (I’m sorry it was so hard) and you’ve already started contributing. And I for one appreciate it immensely. But I don’t want you to think someone will come along and assign you something to contribute. You’ll have to figure what, when, and how much you want to contribute. Some people only answer questions on the forum. Others just do translations of the UIs. Some code add-ons or script libraries. Far too few of us write on the docs.

My primary contributions are the forum, with the docs and my own set of scripts and rules libraries being secondary.

1 Like

well, ok, I did not mean that, of course. I don’t know about the interaction between the engine room geeks and the doc frontend - that’s what/why I mentioned it earlier. I just cannot understand why doc pages published in the OH3 next site cannot be modified injectng a div. Maybe there is something difficult, I assumed that the openhab-doc repo was the one used as a source for the doc, whose file you can branch and modify. manually or running a script. the GIT repo will only see a commit request, after you review them. md are md. Cannot understand how that is not possible, but it sounds obscure and I’ll shut up then.

Well well, I understand the project is quite complex and I would’t like to be a nuisance instead of helping.
Just saying I am an available resource to help for what I can. Not sure if there is any enrollment mechanism, I’m telling you and see if you/you guys turn my (potential) efforts/resources in something useful for the project. Let’s say it like that: I could be a marginal resourced available for use. Like a computer in the old time SETI@home project. In the meanwhile I obviously have a lot of fishes to fry on my own, I won’t get bored for sure.

yeah, it was hard, with no support. But since you are a constant presence in the forum- as I can read- you could for instance use me as a support resources for anyone starting from scratch with the same attempt to modify a GIT doc (in Win obviously) Resource available.

They are not written in HTML for one.

Not all. A lot comes from the other repos as well. In fact, most of the technical stuff (e.g. binding docs) comes from other repos.

Nope, just raise your hand and say I want to do X. Just like you did with giving the new user’s perspective of the docs as they are. If you see something you can do, enrollment is pretty much tell others you are doing it through an issue if it’s code or a big change and if there is no pushback or redirection start doing it. A lot of things like helping on the forum you don’t even need to do that. Just start answering questions where you are able. Writing tutorials is another way to just start contributing (which you’ve done).

In short, you are already enrolled! Now you get to pick and choose when, what, and how much.

One thing that would be really useful is to keep posting tutorials like that MySQL one. Lessons learned. Or just show off what you are doing. Letting people see what’s possible is also very useful.

We definitely appreciate you as a resource. But you’ll have to be a self directed resource. There is no boss around here. We all volunteer for everything we do.

But, if you do want some direction I can offer the following ideas:

  • Look at the open issues on the docs repo and see if you can address any of those.
  • File issues where you think you have a good suggestion but can’t implement it yourself (note, not every issue gets addressed, filing an issue is no guarantee it will be implemented by someone else)
  • Read the forum and help out on threads where you think you can. You will get it wrong from time to time, even in the log run (I get stuff wrong all the time) but someone will be along and correct that most likely and you will learn.
3 Likes

Just for reference there is a new guide now at [Wiki] How to contribute to the openHAB Documentation that explains a lot of this.

Thanks, should have thought of looking for post by Confectrician - being the Guy of commits.