OH3 how view textual definition of an Item

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!

1 Like

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

1 Like

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

Oh Bruce, thank you so much :star2:!
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!

1 Like

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

1 Like

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

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