OH3 how view textual definition of an Item

[edolis]

OH 3.0.0.RC1
Hi guys,
I’ve got a MQTT generic thing connected to a MQTT bridge and working to configure its channels.
I’m trying to troubleshoot why linking an item I created brings me to an item with Analyze chart empty while having the item created by the UI during linking makes the chart populated. (and in general an Item I create manually does not show up in charts)
Apparently the set up of the Item looks the same to me. Numeric temperature, point,
To troubleshoot, I’d like to read the different textual definition of the two items.

Could not find a way to do that. Is it possible?
Please bear with me.
Thanks!

[edolis]

update:
still did not figure out how to see that textual definition.
However, the issue with charting is solved as I discovered that, for a known issue, charting with manually made items get done with a delay of some hours. Nice to know. Wish I could read that in the doc somewhere. I spoiled lot of time to try to troubleshoot it.
Ref https://github.com/openhab/openhab-core/issues/1972#issuecomment-748926708

[Bruce_Osborne]

You should be able to get the Item definition using API Explorer and the REST API. That is how HABapp accesses and creates Items.

[edolis]

Oh Bruce, thank you so much !
I discovered that under Developer tools>API explorer, you can do this

getting this

which was exctly what I was looking for.

@rlkoshak I suggest you add at least a reference to this: for a new user being able to compare the core language behind objects is so important to understand, fix issues and start navigating OH!

[Bruce_Osborne]

That is similar to the old restdocs interface.
In fact the APi is what the Main UI uses to communicate with OH.

[edolis]

Thanks again Bruce - fact is that being a newcomer I’m lacking history and in general all the Ariadne’s threads required to get around things. This helped a lot.
Very interesting the url stuff. I assume that, with some understanding, you could just point your browser to http://localhost:8080/rest/SomeThing/SomeThingInsanceID

[Bruce_Osborne]

@edolis

being a newcomer

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.

[rlkoshak (Rich Koshak)]

@edolis

I suggest you add at least a reference to this

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

@Bruce_Osborne

That is similar to the old restdocs interface.

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.

@edolis

Very interesting the url stuff. I assume that, with some understanding, you could just point your browser

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.

[Bruce_Osborne]

@rlkoshak

What I find annoying is that you have to click “Try it out” before it will let you enter anything into the forms.

Agreed!

[edolis]

@rlkoshak

But it won’t be covered in getting started.

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.

[rlkoshak (Rich Koshak)]

@edolis

having no tools to investigate

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.

@edolis

Saying just because we agreed I would collaborate giving a first time user view on doc.

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.

[edolis]

@rlkoshak

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.

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.

@rlkoshak

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?

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.

@rlkoshak

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.

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 Take care

[rlkoshak (Rich Koshak)]

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?

@rlkoshak

then someone else can write them.

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.

[Bruce_Osborne]

@rlkoshak

But the point still remains, just because I asked for suggestions does not mean I have to accept them all.

Even if they double your pay? LOL

[edolis]

@rlkoshak

But if I disagree with just this one suggestion I’m ignoring you and you’re out?

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!

@rlkoshak

Looking at the JSON wouldn’t have helped with a problem caused by defining Items through the UI

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…

[rlkoshak (Rich Koshak)]

@edolis

can be astonished at seeing that in 2020 adding a hyperlink to deep documentation is an issue. You know what I mean? Href anybody?

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.

@edolis

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!

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.

@edolis

you are probably right. But here is the good old bias

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.

@edolis

you know how to get around issues

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.

@edolis

BUT don’t you feel you are there to protect ppl who have not the (limited) toolkit

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.

[edolis]

@rlkoshak

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? ), 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.

[rlkoshak (Rich Koshak)]

@edolis

OK, but please suggest in the tutorial what these debugging tools should be

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

@edolis

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?

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.

@edolis

So what’s the practical recommendation for “better ways”?

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

@edolis

I was trying to add an additional item later on instead of creating all of them at the same time.

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.

[edolis]

@rlkoshak

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

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:

@rlkoshak

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.

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?

@rlkoshak

Just to be clear, we are really talking about a page in the Getting Started Tutorial that doesn’t exist yet.

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

@rlkoshak

Via text files though, which ends up putting you outside the Getting Started Tutorial

ahem, not really. using UI

[rlkoshak (Rich Koshak)]

@edolis

I wish you folks could embrace temporary placeholder doc pages

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.

@edolis

Come on, how hard is that? You can put a bot on that task when you clone the old doc.

I look forward to the PR that implements this.

@edolis

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?

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.

@edolis

with a big sticky forum topic to inform users to go and read doc first?

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.

@edolis

are the only ones I am reading to understand how get started in OH3?

As of the release today Introduction | openHAB are the latest now.

@edolis

My win github pull:no idea when I’ll see that in next.oh.

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

@edolis

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 lacking.

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.

@edolis

doc is lacking.

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.”