# Software Development Kit for app development **Category:** [Implementation](https://discourse.openehr.org/c/implem/39) **Created:** 2020-06-17 08:47 UTC **Views:** 4785 **Replies:** 45 **URL:** https://discourse.openehr.org/t/software-development-kit-for-app-development/790 --- ## Post #1 by @birger.haarbrandt Hi everybody, as you might know, we are working on an open source SDK (https://github.com/ehrbase/openEHR_SDK) with the aim to make application developers love to work with openEHR. As this is developed against the official openEHR REST API and aims to be 100% vendor-neutral, this is something that should be of general interest to the community, including other vendors. From my point of view, it is absolutely crucial that people who are new to openEHR are able to get their first application up and running within a few hours. As of now, we have functions to create DTOs from Templates, provide encapsulation of REST calls and the management of templates. We can also use the DTOs to create AQL queries. In the near future, we will also start to support the flat formats. However, before we do further steps, we would like to discuss the requirements with the community. What are the things bothering people when they want to build applications? We envision a web call where we demonstrate the functions of the SDK and then discuss what would provide value. Presentations of your (commercial) SDKs would also be welcome, if this is not an issue from a business perspective. Of course this only makes sense if there is an interest by the community, hence, I’d like to hear from you if this is of interested and you would be willing to spend 2-3 hours to get into this conversation. So please provide some feedback if this is of interest for you (or drop a comment why this might not be the right approach :slight_smile: --- ## Post #2 by @Sidharth_Ramesh Most of the clinician facing apps are web-based. While having a Java client is great, a TypeScript/Javascript project would be very useful for making REST calls and AQLs directly from the client. I think other people will be interested in this as well. Maybe with your guidance, we can explore the openEHR SDK repository and create a Javascript equivalent. Can you tell me how to get started? --- ## Post #3 by @birger.haarbrandt We considered that, but there are some things to keep in mind: the SDK heavily relies on the openEHR Reference Model implementation Archie. Hence, I assume that this library would have to be replicated in Typescript to get started. Moreover, to my understanding, the SDK uses reflections quite a lot in the template introspect, which is a key component. I'm not an expert on Javascript and Typescript but my understanding is that reflections are only poorly supported in these languages (in the end, Typescript is still Javascript). This would prevent a straight forward translation from Java. I'm quite sure there is an alternative approach but this might require some fiddling and exploration to get this right. Besides these two obstacles, I think it should be quite doable but would require ~10 months development time by a senior developer. However, this is only my perspective and I'm really open to receive some feedback from the community. We are really happy to support anyone who likes to create a port of the SDK! --- ## Post #4 by @birger.haarbrandt Hi everybody, you can get the latest build of EHRbase with beta support of flat format and webtemplates using the following docker command: docker run --name ehrbase --network ehrbase-net -d -p 8080:8080 -e DB_URL=jdbc:postgresql://ehrdb:5432/ehrbase -e DB_USER=ehrbase -e DB_PASS=ehrbase -e SYSTEM_NAME=local.ehrbase.org ehrbaseorg/ehrbase:next Remember to have postgres up and running beforehand: docker network create ehrbase-net docker run --name ehrdb --network ehrbase-net -e POSTGRES_PASSWORD=postgres -d -p 5432:5432 ehrbaseorg/ehrbase-postgres:latest Please find a postman collection with an example [Flat.postman_collection.json|attachment](upload://seVAphaSVEz2c22d2Ta1VthWX4X.json) (1.2 MB) The implementation is still subject to change and should not yet be used for production. Have fun and we are looking forward to receive your feedback and issues. If you want to take a look at the source code, check the dev branch on the openEHR SDK: https://github.com/ehrbase/openEHR_SDK PS: we are also missing an example generator which makes life a bit harder but sending via canonical JSON/XML and then getting an example in the flat format via GET is well possible --- ## Post #5 by @Dileep_V_S Thanks EHRBase team, This will make testing a lot easier for a lot of developers. In the postman collection, I do not see an API to generate a sample FLAT composition from a template. Is it not done or missed out? Is the suggested method to use Ethercis APIs for this? Also is webtemplates same as the flat JSON format or am I missing something else? I do not see any separate APIs for webtemplates in the collection. regards --- ## Post #6 by @birger.haarbrandt Hi Dileep, yes, this should be added to the example. It follows the pattern of the EHRSCAPE API. Generally, I think we should refine the official REST API to deal with webtemplates and flat. Just tried this examples: `GET http://localhost:8080/ehrbase/rest/ecis/v1/template/Corona_Anamnese` to obtain the webtemplate representation of the OPT and this works. I updated the collection in my post. As mentioned above, having the sample/example composition would be a good addition and I'm quite sure that we will add this in the somewhat near future. --- ## Post #7 by @Dileep_V_S Hi Birger, Thanks for the reply. That helps complete the loop. And yes the openEHR REST API documentation has to keep up with you now!! regards --- ## Post #8 by @Sidharth_Ramesh Hello Birger, What tool did you use to generate the Corona_Anamnese template? I tried to upload a template generated using https://tools.openehr.org/designer/ and it resulted in this [issue](https://github.com/ehrbase/ehrbase/issues/358). Until the bug is patched, I'd like to use the same tool as you to generate templates. Thank you! --- ## Post #9 by @johnmeredith We have an interest in this for our dev team in NHS Wales Informatics Service. Unfortunately we are predominantly a Microsoft .NET MVC and I am looking for ways to support them using native openEHR APIs. --- ## Post #10 by @birger.haarbrandt I think there is a difference within the description tag inside the OPT between Ocean Template Designer and ADL Designer that EHRbase does not like at the moment. Unfortunately, I don't have the time right now to take a deeper look. Hence, please try with the Ocean Template Designer and I would highly appreciate if you can report back and then we can hopefully fix the issue. --- ## Post #11 by @birger.haarbrandt Hi John, I think the best we can offer at the moment for .NET devs is the flat format and potentially the STRUCTURED format once there is some serious requests by users. --- ## Post #12 by @johnmeredith We have considered internally removing all openEHR specific syntax - even the Better flat and structured JSON has a bunch of pipes for no apparent reason - to create a lean, basic JSON payload or developer friendly syntax ;-) --- ## Post #13 by @navaneeth Hi Birger, With the postman collection you mentioned above, i am not able generate flat composition for a template. { "error": "Unexpected value of CompositionFormat: 'FLAT'", "status": "Internal Server Error" } i am getting this error --- ## Post #14 by @ian.mcnicoll Example composition is not supported (yet). --- ## Post #15 by @navaneeth HI, GET http://localhost:8080/ehrbase/rest/ecis/v1/template/Corona_Anamnese will this api give webtemplate in flat format --- ## Post #16 by @Sidharth_Ramesh Navaneeth, Are you using the `ehrbaseorg/ehrbase:next` image? You'll get the error if you're using the `ehrbaseorg/ehrbase` image instead. I am able to post compositions without any issue. --- ## Post #17 by @navaneeth i am using ehrbaseorg/ehrbase:next i am able to post composition will i be able to get compositions in flat format ,also webtemplate? --- ## Post #18 by @Sidharth_Ramesh Yes to both. To get composition in flat format use format=FLAT Example: `http://localhost:8080/ehrbase/rest/ecis/v1/composition/62839a78-b2b8-4cf8-ac4f-7af7b799534c?format=FLAT` To get webtemplate, you can just make a GET requests to the ecis template endpoint Example: `http://localhost:8080/ehrbase/rest/ecis/v1/template/` --- ## Post #19 by @navaneeth when i am using FLAT it is giving me error --- ## Post #20 by @Sidharth_Ramesh More details on the error would be helpful. --- ## Post #21 by @ian.mcnicoll Best approach is to report the error and point to a Template fileset so that we can recreate the .opt and see the original archetypes and templates. --- ## Post #22 by @navaneeth I have tested with the postman collection which @birger.haarbrandt have posted above 1. first i have done save template http://localhost:8080/ehrbase/rest/openehr/v1/definition/template/adl1.4/ 2. after that i tried to do post composition in flat format http://localhost:8080/ehrbase/rest/ecis/v1/composition/?format=FLAT&ehrId=a0cb45a7-f31b-414d-a104-dd057fa72d24&templateId=Corona_Anamnese This gave me an error { "error": "Unexpected value of CompositionFormat: 'FLAT'", "status": "Internal Server Error" } in prevoius post i have mentioned i am able to post compostion .i am able post in other formats but not in flat --- ## Post #23 by @birger.haarbrandt Unfortunately I'm not able to reproduce your issue. I used postgres:latest and ehrbase:next in docker on windows 10. --- ## Post #24 by @jendrik.richter Hello everyone, i tested the new changes and working with the FLAT format feels great. As far as i know the FLAT format is not included in the openEHR-Standard. Please correct me if i am wrong. Since we aim for interoperability and interchangeability of components i have the following question: Do you have any insight about if there are plans to include the FLAT format in the standard? Is there any overview about upcoming and planned changes to the standard? --- ## Post #25 by @ian.mcnicoll Hi Jendrick, I am just to about a CR into the REST API to allow the /composition call to allow the current Better FLAT and STRUCTURED formats to be accepted. Probably custom headers?? However this just means that you can have the current Better formats as a payload. A further piece of work is underway to incorporate the BETTER Flat format ideas as part of the formal standard https://specifications.openehr.org/releases/ITS-REST/latest/simplified_data_template.html So you are definitely not committing yourself to a 'proprietary dead-end'. My current approach is to use the formal REST API for all of the CDR interactions, apart from /composition where I use the Better Ehrscape/Ethercis API endpoint so I can use FLAT formats - slightly annoying but it works. Having said all of that, the canonical xml and json formats will remain the 'gold standard' particularly for moving data between CDRs --- ## Post #26 by @birger.haarbrandt We are aiming at 100% conformance with Better's implementation. We found some design decisions that we would like to discuss and this will be reflected in the SDT format spec that @ian.mcnicoll mentioned. I also fully endorse his push to have this format supported in the official REST API. So yes, it can be considered as part of the standard. --- ## Post #27 by @alaffet Hello @birger.haarbrandt, Thank you for building this! Will the [adl2 template endpoint](https://specifications.openehr.org/releases/ITS-REST/latest/definitions.html#definitions-adl-2-template) be supported ehrbase? if yes, is there an estimate on when it would be available? --- ## Post #28 by @Sidharth_Ramesh Seems like the docker image has changed from `ehrbaseorg/ehrbase:next` to `ehrbase/ehrbase:next` now. I was using an old version of EHRBase for a long time not realizing this. For people getting started with docker, here is a quick start `docker-compose.yml` file that will get you running on the latest version: ```yml version: "3" services: ehrbase: image: ehrbase/ehrbase:next ports: - "8080:8080" environment: - DB_URL=jdbc:postgresql://db:5432/ehrbase - DB_USER=ehrbase - DB_PASS=ehrbase - SYSTEM_NAME=local.ehrbase.org depends_on: - db db: image: ehrbaseorg/ehrbase-postgres:latest environment: - POSTGRES_PASSWORD=postgres volumes: - data:/var/lib/postgres volumes: data: ``` If you want to update, just do `docker-compose pull` --- ## Post #29 by @birger.haarbrandt It will be supported sooner or later but unfortunately we don't have this formally on the roadmap at the moment. --- ## Post #30 by @bna We have a quite mature .NET implementation of "all in openEHR". Both a .NET openEHR server, SDK, clients and lots of tooling. You might be interested in some of these. Currently we don't have any customers outside Norway and our main focus is our national customers. Anyway - I am writing this to check if there might be any interest in (some of) our software stack for your activities :-) --- ## Post #31 by @Dileep_V_S I am testing the improved FLAT composition support in 0.16.5. But I am unable to get any response from the server when I do POST. Are the paths same as per your postman collection? @birger.haarbrandt http://localhost:8080/ehrbase/rest/ecis/v1/composition/?format=FLAT&ehrId=5c9950a1-1f1d-43bf-9093-c2e7d051bcab&templateId=Corona_Anamnese I also could not find the FLAT composition APIs in the Swagger regards --- ## Post #32 by @ian.mcnicoll I have 0.16.5 working ok with FLAT. curl --location --request POST 'http://localhost:8080/ehrbase/rest/ecis/v1/composition?ehrId=d4a7af5d-4147-44ef-a567-e69e2fee214a&templateId=IDCR%20-%20Adverse%20Reaction%20List.v1&committerName=Dr%20Franke&format=FLAT' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic OWI4ZDhiMTEtYTJhNi00YzE5LWI4MGMtYWZmNzY5MWE1OTlmOiQyYSQxMCQ2MTlraQ==' \ --data-raw ' { "adverse_reaction_list/language|code": "en", "adverse_reaction_list/language|terminology": "ISO_639-1", .... }} --- ## Post #33 by @Dileep_V_S Is committerName mandatory? Regards --- ## Post #34 by @ian.mcnicoll No optional -it will default to the logged in user and actually I'm not sure that Ehrbase supports it -may well be ignored. --- ## Post #35 by @Dileep_V_S Yes FLAT composition is working. The problem was with a couple of templates and is still having same problem. It is working for all the other templates. I have managed to narrow down the problem to https://github.com/ehrbase/ehrbase/issues/512 These templates seem to have got corrupted while importing. Tried updating the template, but the problem persists --- ## Post #36 by @birger.haarbrandt Thanks for creating the ticket. We are really keen to find and resolve as much issues as possible before the 1.0 release! --- ## Post #38 by @sangeeta.nbose Hi Ehrbase team What is the best way to generate flat format composition from a template. The example generator would be really useful thanks much Sangeeta --- ## Post #39 by @joostholslag The VScode plug-in already does some example generation (using archie). It supports a.o. generate example flat json. (Not webtemplate) --- ## Post #40 by @mc1995 Hello everyone, I am a little confused by all this different statements:/ Should it now be possible to get sample collection in flat format via ` http:///ehrbase/rest/ecis/v1/template//example?format=FLAT? ` If yes, what could be wrong if the answer of this request looks like the following, although the template_id does exist: ``` {"meta":{"href":{"url":"/ehrbase/rest/ecis/v1/template/example"}},"action":"RETRIEVE","composition":} ``` I did use the updated yaml file of @Sidharth_Ramesh --- ## Post #41 by @birger.haarbrandt Looks good, which version of EHRbase are you using? Latest dev branch? --- ## Post #42 by @mc1995 Thanks for that quick reply -appreciate your support! I did the installation roughly 6 weeks ago and used the ehrbase/ehrbase:next image. Maybe I'll try to install the newest version tomorrow and give you a feedback. Do you think it's worth it or should this functionality already worked in the 6 week old image? --- ## Post #43 by @birger.haarbrandt The new feature was added around 2-3 weeks ago, so please try again with a recent version --- ## Post #44 by @mc1995 awesome! pulling the newest image and rebuilding the docker image does the job :slightly_smiling_face: This functionality makes it much more convenient to upload a composition. However, what is the best workflow for posting a new template? Right now I'm using the Archetype Designer to create an OPT file and `/definition/template/adl1.4` to post the file. Is there any way to upload in webformat? Furthermore, how does the aql query request with ehrScape work? Calling `ehrbase/rest/ecis/v1/query?explain=false'` with a body `{"aql":"Select e from EHR e"}` gives me an internal server error. --- ## Post #45 by @birger.haarbrandt At the moment, upload of a template is only possible using OPT. How would you envision the WebTemplate format to make the upload workflow more convenient? Regarding ehrscape: said query endpoint is actually deprecated and will be removed before the 1.0 release (admittedly, this is not marked properly). We recommend to use the one of the official openEHR REST API. In general, we encourage to use the official API to ensure vendor-independence: https://specifications.openehr.org/releases/ITS-REST/latest/query.html#query-execute-query --- ## Post #46 by @mc1995 Hey, I find the webtemplate much more readable, but yes, you're right, that doesn't actually affect the upload workflow. Ok thanks for that info. By the way, will sophisticated sql structures like JOINS be supported in AQL in the near future? --- ## Post #47 by @birger.haarbrandt Joins are already possible in Better, but not yet standardized (there are some interesting choices around permutations within the result set). We are currently focussing on smoothing the edges in EHRbase, but are keen to add subselects, joins and group-by and contribute to the spec. I hope that we can get there within 12 months or so. --- **Canonical:** https://discourse.openehr.org/t/software-development-kit-for-app-development/790 **Original content:** https://discourse.openehr.org/t/software-development-kit-for-app-development/790