Improve documentation for Runtime Data for use in integrations

[rob-fi]

I'd like to see some improvements in the documentation for Runtime Data. I note the disclaimer on the documentation (https://docs.getontime.no/api/data/runtime-data) that states that the documentation will get out of sync as features are added, but I feel it's now at a point where it needs a bit of a refresh.

For example, I was wishing to use the custom fields for integrations. and I was almost lead to believe that it wasn't possible, until I found this closed issue that seems to be the only reference to using custom fields for such: https://github.com/cpvalente/ontime/issues/1190

I couldn't find any references in the linked type definitions or instantiations, and as not much of a developer myself, it's hard to know exactly where to find the information in the code base.

It would be very helpful if that (and any other pieces of data that are available) could be added to the documentation.

Another caveat I found which got me stuck for a long time is the fact that {{eventNow.custom.mycustomfield}} data objects must be in lower case, even if the custom field has uppercase letters in it. This might be something that's inherent to the code, but as I'm not a developer, this wasn't obvious at all, and I was lead to believe the function just didn't work until I eventually had the idea to try it lowercase.

Thanks for the great software.

[lukestein]

Taking the liberty of transferring this over to the documentation repo.

I'm really not familiar with what's necessary for this bit, but since it seems to be code related (rather than documentation related) it may belong in a separate issue:

Another caveat I found which got me stuck for a long time is the fact that {{eventNow.custom.mycustomfield}} data objects must be in lower case, even if the custom field has uppercase letters in it. This might be something that's inherent to the code, but as I'm not a developer, this wasn't obvious at all, and I was lead to believe the function just didn't work until I eventually had the idea to try it lowercase. However, maybe this is related to (and hopefully resolved by?) cpvalente/ontime#1242

[cpvalente]

Hi @lukestein , good initiative, this is the correct place for documentation discussions.

You are also correct that the PR is aimed to improve the specific use case of custom fields. In short, the lower case requirement was something that we did not see when implemented the custom fields feature. This is now being worked on and we are aiming to have an improvement out very soon

I couldn't find any references in the linked type definitions or instantiations, and as not much of a developer myself, it's hard to know exactly where to find the information in the code base. It would be very helpful if that (and any other pieces of data that are available) could be added to the documentation.

@rob-fi I recognise this is an issue. We have historically found it difficult to balance the time between features and documentation. Keeping in mind that all of us work with Ontime on our spare time. I am hoping we will eventually circle back to seeing where the documentation is failing but, for now, maybe you could point us to some data you are missing?

I believe the correct, and more useful version of the documentation, would actually be making code examples for custom-view and integrations. This to say that it could be useful for us to understand your case, and perhaps leverage it as documentation as we help you

[rob-fi]

Hi @cpvalente, sorry for the delay, things are quite hectic right now. Also thanks for moving this to the correct repo @lukestein, I wasn't aware there was a docs specific one, my apologies. Perhaps now I know this repo exists I can look at doing some improvements myself (when I get time, I understand completely about that @cpvalente, I have so many unfinished projects...).

So, in this particular situation, I was looking to utilise the custom fields for using in the integrations. Similar to the closed issue I referred to, I wanted a field where I could specify a button to press in Bitfocus Companion using a custom field called Companion to start off an external action. With the current documenation, I was struggling to find out how to do this, because it wasn't clear to me that I should use "{{eventNow.custom.companion}}". That was then compounded by the fact that the companion had to be in lower case, which initially lead me to believe that it just didn't work.

My route was from https://docs.getontime.no/api/integrations/ which lead to https://docs.getontime.no/api/data/runtime-data which suggested looking at https://github.com/cpvalente/ontime/blob/master/packages/types/src/definitions/runtime/RuntimeStore.type.ts.

Now I'm more informed, I can see that I should have paid attention to the includes and had a look at https://github.com/cpvalente/ontime/blob/master/packages/types/src/definitions/core/OntimeEvent.type.ts which may have given me the hint I needed. However, not being much of a developer, it wasn't so obvious.

I understand now there's a lot of possible data sources to use for the integrations so perhaps it's not reasonable to expect everything to be laid out clearly, but maybe some updates to include examples for the most common fields could be good.

[cpvalente]

Hi @rob-fi , I understand this and am hoping that we can improve

I have reviewed the documentation and added some more information In my experience, more text usually has a contrary effect to documentation readability, but I am hoping that in this case it helps

Unfortunately I got excited and pushed straight to master 😎 , can you please let me know if you think this is helpful and whether we can improve? https://docs.getontime.no/api/integrations/#using-variables-in-integrations

As for the custom fields, as I have explained, the lower case issue was an oversight from our side and will be rectified in our next release

[rob-fi]

@cpvalente Thanks a lot for this, from my brief look it looks like more than I could have hoped for. While it may begin to get out of sync before too long, it's now a great reference point to get started with integrations.

So to answer your question yes I think it is helpful and I'm not sure it's worth you dedicating any more time to it for now.

Thanks for the update about the lower case issue.

[cpvalente]

That is great to hear. We are aiming to have a release soon with the changes to the lower case custom fields

I will leave this ticket open for now until we can confirm that the release solves the issue

Meanwhile, thank you for all your feedback. If you have any thoughts please feel free to reach out or open more tickets