handling openEHR Templates about specifications-its-rest HOT 11 CLOSED

I think it is a no brainer to have this template knowledge service, but it probably wasn't on our priority list. I also think it will be very simple to define using the standard REST methods POST/GET/PUT/DELETE, so we may as well just do it if we all agree there is a need to do this in a standard manner, which I think there is.

from specifications-its-rest.

In the SEC call June 17 we agreed that template handling should be included form the first verion of the REST API. (Anybody is free to add suggestions for templat handling call to the apiary file...

from specifications-its-rest.

The key calls IMO are..

1. Upload .opt xml
2. List available templates
3. Download .opt xml (useful in the context of demoing moving data from one system to another)

The simplified template usage and 'web templates' are very useful and I would love to see these as part of the std. spec (along with TDS2/3 etc but I think that is probably part of a separate discussion as this will involves some current IP issues and relates to simplified JSON formats.

I would be happy to restrict scope to basic .opt handling for now. I would definitely like to add support for other formats but it probably needs to be part of a broader discussion.

One other potential get is the ability to retrieve a dummy data instance based on a template. Very helpful for training purposes and for 3rd-party devs Whether it makes sense in the context of canonical xml instances, I am not sure but the principle of sample instance generation baed on a template works very well for TDS/TDD and json equivalents IMO.

I understand the concern that these should be admin functions in production environments and we should discuss how that might be done.

from specifications-its-rest.

@freshehr I am not sure I understand the API need for your 1-3 list - it looks more like it is about knowledge governance/storage/retrieval than EHR server content. For those things we could probably just use something existing, like webdav, FTP, a normal upload/download-webpage or a service like GitHub, rather than include it in the core EHR REST API.

Or do you mean that the template service will be tightly connected to the EHR and only list the templates actually used in EHR content of this system (if they are available)?

The 'web templates' or TDS-related stuff is easier to understand an API need for - and for that you also need upload/download of templates and archetypes connected to the EHR implementation. For tool-supported building of AQL queries, user interfaces etc too I guess... (So there the need in you r 1-3 Points re-appear).

Interested in thoughts from others too

from specifications-its-rest.

@ErikSundvall -
"Or do you mean that the template service will be tightly connected to the EHR and only list the templates actually used in EHR content of this system (if they are available)?"

Exactly, this is purely about EHR server management. All of the major openEHR implementers use this approach (AFAIK), though some use an admin facility rather than expose as a public API. Having the public API is really helpful in training contexts and for scripting e.g. pre-population with dummy data, transferring data between different servers but I appreciate that in production environments people might want to lock this down.

from specifications-its-rest.

@ErikSundvall

1. +1
2. I'm not sure what simplifying means, less data?

IMO the best approach is to commit only full compositions or versions and do that in one transaction instead of partial updates to a composition. E.g. XML instances of compositions or versions instead of key/value pairs (I think this is the approach suggested by "names/fields/attributes").

I would say we need transactional "full" commits for EHR backend systems, and maybe the non-transactional / partial updates / key value approach is better for an app backend. I'm thinking of an architecture like this:

                      EHR Backend <--- App Backend <--- End User App

I'm talking about what happens here ^

In the other hand, most of the key/value approaches I know use a pseudo path as the key, pseudo because those are not valid archetype or template paths, and most are custom made. I would say we need to avoid using custom data if we can, and this might not be so simple for developers since they need to figure out which paths to use and how to create them. If the API is providing the paths, it is simpler for developers, but again they are working with something custom and vendor-dependant.

This is avoided by just committing full XML versions (or JSON), that can be easily validated by the XSD and is using 100% compliant formats that are vendor independent.

1. If we call this "data API" and we think of a template management API, we need to separate those because are pointed to different kinds of users. But...

On the EHRServer we took the approach of managing OPTs from a management console and do not allow API clients to manage OPTs through the API, since they would be able to change or delete an OPT that other users might need, or that are used to index data for queries. If a query is based on a path contained in an OPT and that OPT gets updated, maybe removing that path, the query will get affected.
I'm considering that OPTs are part of the configuration of the system and should be handled carefully, are not part of the personal data space, nor part of a specific EHR, so it depends on the implementation if they allow API clients to manage that.

Because of this, I would lower the priority of designing an API for template / OPT management and analyze if that is a general requirement or is just for some vendors.

from specifications-its-rest.

@ppazos : The Marand Web template format and related flattened data formats are akin to TDS/TDD. They do resolve to complete canonical Composition instances but use knowledge of the template structure to apply default values, hide boilerplate RM attributes and flatten out the more complex canonical data structures. Having these flattened formats is immensely helpful when working with integration and newbie openEHR-based app developers, so I am very keen to see at least one flattened format available via the standard service API. I understand that Marand have agreed to open-source thier flattening algorithm and Christian Chevalley of Ethercis can also provide a candidate 'standard' flattened form as open source.

Template handling: I understand your concersn about the importance of secure template handling, and that in many cases in live environments, this should be carefully controlled.

However, having access to the /template API, independent og a specific admin tool has been hugely beneficial (indeed critical) in establishing th idea of the openEHR CDR as a platform as it allows:

1. Clear indication that the developer has full control over data-handling irrespective of admin tools
2. Allows third parties to create data provisioning tools, testing tools.
3. Allows third parties to create scripts that demonstrate the non-transform transfer of data from one vendor CDR to another.
4. Hugely helpful in teaching and training purposes, again easily being able to show this critical part of the openEHR eco-system in a vendor and tooling neutral fashion.

I am quite happy for implementers to take the view that these APIs should be locked down in production but they are IMO absolutely necessary for an cloud-based environment like NHS Code4Health.

Ian

from specifications-its-rest.

On the call (2016-06-23) we decided to indeed include template handling calls in the API. It's up to vendors whether to include this also in the production setups, but we will specify it in the REST API so we all have same API.

from specifications-its-rest.

Would this be handled by /template?
If /template would only handle only .opt(s) can we consider (at least in the future) the /archetype for archetypes?

from specifications-its-rest.

I think the needs in the thread above are now addressed by https://openehr.org/releases/ITS/latest/docs/definitions.html and can be closed.

from specifications-its-rest.

Ian wrote:

"I am very keen to see at least one flattened format available via the standard service API. I understand that Marand have agreed to open-source thier flattening algorithm and Christian Chevalley of Ethercis can also provide a candidate 'standard' flattened form as open source."

This part of #9 is now treated in issue #56

Now closing #9 considering template handling implemented in https://openehr.org/releases/ITS/latest/docs/definitions.html and the "flat" form to be treated in issue #56

from specifications-its-rest.