A description of the webservices provided by the Archetypefinder.
Usage
Formal Specification (WSDL): http://openehr.org/knowledge/services/ArchetypeFinderBean?wsdl
Examples using access directly via HTML:
http://openehr.org/knowledge/services/ArchetypeFinderBean/getArchetypeADLURL?archetypeId=openEHR-EHR-OBSERVATION.blood_pressure.v1
http://openehr.org/knowledge/services/ArchetypeFinderBean/getDescriptionForArchetype?archetypeId=openEHR-EHR-OBSERVATION.blood_pressure.v1&language=de&descriptionTerms=archetypePurpose&descriptionTerms=archetypeDescription&descriptionTerms=archetypeConcept
http://openehr.org/knowledge/services/ArchetypeFinderBean/getArchetypeInADL?archetypeId=openEHR-EHR-OBSERVATION.blood_pressure.v1
http://openehr.org/knowledge/services/ArchetypeFinderBean/getArchetypeIdsFromPartialId?archetypeIdPart=blood
http://openehr.org/knowledge/services/ArchetypeFinderBean/getArchetypeIdsFromPartialIdWithPositioning?archetypeIdPart=openEHR-EHR-OBSERVATION&cursor=1&size=10
http://openehr.org/knowledge/services/ArchetypeFinderBean/getAllArchetypeIds
http://openehr.org/knowledge/services/ArchetypeFinderBean/getAllArchetypeIdsWithPositioning?cursor=1&size=10
Overview of Webservices
| String[] | getDescriptionForArchetype(String archetypeId, String language, String[] descriptionTerms) Retrieves the desired elements of the Description of the Archetype. |
| String[] | getDescriptionForArchetypes(String[] archetypeIds, String language, String[] descriptionTerms) Retrieves the desired elements of the Description of a selection of Archetypes. |
| String[] | getDescriptionForAllArchetypes(String language, String[] descriptionTerms) Retrieves the desired elements of the Description for all active archetypes. |
| String[] |
getArchetypeIdsSimple(String searchParamName, String searchParamValue) Retrieves the archetype-ids that fit the search query |
| String[] DEPRECATED |
getArchetypeIds(String[] searchParams) Retrieves the archetype-ids that fit the search query in searchParams This is the most flexible method, exposing most of the functionality of the Archetype Finder in one method. |
| String[] | getArchetypeIdsFromPartialId(String archetypeIdPart) Searches for Archetype Ids based on a part of that Id (sorted by archetype id in ascending order) |
| String[] |
getArchetypeIdsFromPartialIdWithPositioning(String archetypeIdPart, int cursor, int size) Searches for Archetype Ids based on a part of that Id taking into account a cursor position and max number of results (sorted by archetype id in ascending order) |
| String[] | getAllArchetypeIds() Gets all active trunk archetypes sorted by archetype id in ascending order |
| String[] | getAllArchetypeIdsWithPositioning(int cursor, int size) Gets all active trunk archetypes taking into account a cursor position and max number of results (sorted by archetype id in ascending order) |
| String | getArchetypeADLURL(String archetypeId) Retrieves the URL to the ADL representation of the Archetype |
| String[] | getArchetypeADLURLs(String[] archetypeIds) Retrieves the URLs to the ADL representation of the Archetypes |
| String | getArchetypeInADL(String archetypeId) Retrieves the archetype in ADL-Form and gives it back as a String |
| String[] | getArchetypesInADL(String[] archetypeIds) Retrieves the archetypes in ADL-Form and gives them back as a String-array |
| String |
getArchetypeMindmap(String archetypeId, String language, String locale) Retrieves the archetype in a freemind mindmap format as a String |
| String |
getParentArchetypeId(String archetypeId) Retrieves the archetype id of the parent of this archetype if any. |
Webservice Details
getDescriptionForArchetypes
public String[] getDescriptionForArchetypes(String[] archetypeIds, String language, String[] descriptionTerms)
Description: Retrieves the desired elements of the Description of a selection of Archetypes.
Parameters:
- archetypeIds String[] - The Archetype Ids of the archetypes for which the descriptions are sought.
- language String - The language the description is requested in. If not available, the english description is returned.
- descriptionTerms String[]- An Array of requested description elements (properties) as specified in the ontology. See getDescriptionForArchetype for full details.
Returns: String[] An array of archetypeId=propertyName:propertyValue entries, e.g. for
archetypeIds =[openEHR-EHR-OBSERVATION.blood_gases.v1, openEHR-DEMOGRAPHIC-ADDRESS.address_iso.v1],
language=en,
descriptionTerms=[archetypeConcept, archetypePurpose]
the following Array of size 4 would be returned.
[0]=openEHR-EHR-OBSERVATION.blood_gases.v1=archetypeConcept:Blood gas assessment
[1]=openEHR-EHR-OBSERVATION.blood_gases.v1=archetypePurpose:For recording the arterial or venous blood gases and respiration products.
[2]openEHR-DEMOGRAPHIC-ADDRESS.address_iso.v1=archetypeConcept:Address
[3]openEHR-DEMOGRAPHIC-ADDRESS.address_iso.v1=archetypePurpose:Representation of data about a personal/organizational address
getDescriptionForArchetype
public String[] getDescriptionForArchetype(String archetypeId, String language, String[] descriptionTerms)
Description: Retrieves the desired elements of the Description of the Archetype.
Parameters:
- archetypeId String - The Archetype Id of the archetype for which the description is sought.
- language String - The language the description is requested in. If not available, the english description is returned.
- descriptionTerms String[] - An Array of requested description elements (properties) as specified in the ontology.
Supported elements include:- archetypeID -- the archetype id
- archetypeConcept -- the concept name
- archetypeDescription -- the concept description
- archetypePurpose -- the purpose of this archetype
- archetypeUse
- archetypeMisuse
- parentArchetypeID
Returns: String[] An array of propertyName:propertyValue entries, e.g. archetypeConcept:Blood pressure measurement
getDescriptionForAllArchetypes
public String[] getDescriptionForAllArchetypes(String language, String[] descriptionTerms)
Description: Retrieves the desired elements of the Description of a selection of Archetypes.
Parameters:
- language String - The language the description is requested in. If not available, the english description is returned.
- descriptionTerms String[]- An Array of requested description elements (properties) as specified in the ontology. See getDescriptionForArchetype for full details.
Returns: See getDescriptionForArchetypes
getArchetypeIdsSimple
public String[] getArchetypeIdsSimple(String searchParamName, String searchParamValue)
Description: Searches for archetype ids based on a param name and value.
Parameters:
- searchParamName the name of the search parameter
- archetypeConcept: search within the archetype concept
- archetypeDescription search within the archetype meta data
- fullSearch: search within the complete archetype
- searchParamValue the string to be searched for.
Returns: String[] An array of retrieved archetype ids.
getArchetypeIds (DEPRECATED)
public String[] getArchetypeIds(String[] searchParams)
Description: Retrieves the archetype-ids that fit the search query in searchParams. This method is there for compatibility reasons only with the ArchetypeEditor. However, it is not fully implemented, i.e.
- it only takes into account the first param1=value1 - nothing more
- it only uses archetypeConcept, archetypeDescription, archetypeTermsCollect (i.e. "complete search" in CKM)
- archetypeDescription now refers to all archetype meta data - instead of just the concept description
NB: This used to be the most flexible method, exposing most of the functionality of the ArchetypeFinder in one method. However, the parameters were based flexibly on the OWL Ontology - if the properties in the ontology change, the searchParams-query may need to be adapted. CKM uses a different model.
Parameters:
- OLD searchParams String[] - An array of string in the form:
old Example 1: param1=value1,value2 e.g. archetypeID=report,diagnosis _(NB: These are Datatype properties from the OWL Ontology)_old Example 2: param2=value3 e.g. hasEHRClass=ObservationEHRClass _NB: This is an Object property from the OWL Ontology)_searchParams may include all datatype and object properties defined in the Archetype Ontology.The string may also contain andor=AND for example to say that ALL searchParams must be fulfilled, not only one. - NEW: searchParams String[] - An array of string in the form:
- param1=value1 e.g. archetypeConcept=blood or archetypeDescription=blood or archetypeTermsCollect=blood
Returns: String[] An array of retrieved archetype ids.
getArchetypeIdsFromPartialId
public String[] getArchetypeIdsFromPartialId(String archetypeIdPart)
Description: Searches for Archetype Ids based on a part of that Id (sorted by archetype id in ascending order)
Parameters:
- archetypeIdPart - String The part of the Id, e.g. report
Returns: String[] A String[] of Archetype-Ids that fit with the archetypeIdPart.
getArchetypeIdsFromPartialIdWithPositioning
public String[] getArchetypeIdsFromPartialId(String archetypeIdPart, int cursor, int size)
Description: Searches for Archetype Ids based on a part of that Id taking into account a cursor position and max number of results (sorted by archetype id in ascending order)
Parameters:
- archetypeIdPart - String The part of the Id, e.g. report
- cursor - int The cursor position within the result set. To start at the beginning use 1
- size - int The maximum number of results to be retrieved
Returns: String[] A String[] of Archetype-Ids that fit with the archetypeIdPart. If no (more) results this array is empty.
getAllArchetypeIds
public String[] getAllArchetypeIds()
Description: Searches for all Archetype Ids that are active and on the trunk (sorted by archetype id in ascending order)
Parameters:
- none
Returns: String[] A String[] of Archetype-Ids
getAllArchetypeIdsWithPositioning
public String[] getAllArchetypeIds(int cursor, int size)
Description: Searches for all Archetype Ids that are active and on the trunk taking into account a cursor position and max number of results (sorted by archetype id in ascending order)
Parameters:
- cursor - int The cursor position within the result set. To start at the beginning use 1
- size - int The maximum number of results to be retrieved
Returns: String[] A String[] of Archetype-Ids
getArchetypeInADL
public String getArchetypeInADL(String archetypeId)
Description: Retrieves the archetype in ADL-Form and gives it back as a String
Parameters:
- archetypeId - String The complete and correct archetype-id, e.g. openEHR-EHR-OBSERVATION.laboratory-glucose.v1
Returns: String the Archetype in ADL-Form
getArchetypesInADL
public String[] getArchetypesInADL(String[] archetypeIds)
Description: Retrieves the archetypes in ADL-Form and gives them back as a String-array
Parameters:
- archetypeId - String The complete and correct archetype-id, e.g. openEHR-EHR-OBSERVATION.laboratory-glucose.v1
Returns: String the Archetype in ADL-Form
getArchetypeADLURLs
public String[] getArchetypeADLURLs(String[] archetypeIds)
Description: Retrieves the URLs to the ADL representation of the Archetype
Parameters:
- archetypeIds- String[] The complete and correct Id of the archetype to be represented in ADL
Returns: String the URL to the ADL representation of the archetype
getArchetypeADLURL
public String getArchetypeADLURL(String archetypeId)
Description: Retrieves the URL to the ADL representation of the Archetypes
Parameters:
- archetypeId - String The complete and correct Id of the archetype to be represented in ADL
Returns: String the URL to the ADL representation of the archetype
getArchetypeMindmap
public String getArchetypeMindmap(String archetypeId, String language, String locale)
Description: Retrieves the archetype in a freemind mindmap format as a String
Parameters:
- archetypeId - String The complete and correct Id of the archetype to be represented as a freemind mindmap
- language - String The language of the archetype if existing. If not specified or if the language does not exist for this archetype, a default is used (english or the original_language of the archetype)
- locale - String The locale to be used for text that is NOT from the archetype. Currently en and de are supported. Defaults to en.
Returns: String the URL to the ADL representation of the archetype
getParentArchetypeId
public String getParentArchetypeId(String archetypeId)
Description: Retrieves the archetype id of the parent of this archetype if any.
Parameters:
- archetypeId - String The complete and correct Id of the archetype
Returns: String the archetype id of the parent archetype if any
Comments (11)
Sep 20
Seref Arikan says:
Great job Sebastian! I'll be extending the Eclipse plugins with a new view t...Great job Sebastian! I'll be extending the Eclipse plugins with a new view to use these services. I'll post the results when I'm done.
Oct 04
Seref Arikan says:
Has this been tested with a Java web services stack as client? I'm having troubl...Has this been tested with a Java web services stack as client? I'm having trouble with Apache CXF, Apache Axis 1 & 2 and whatever web services stack that comes with Netbeans 6.7.1
The client stub generators seem to generate java.io.xsd namespaces for some types, which makes the classloader to throw an exception during runtime. I'd really like to get the name of a tested Java web services stack as a client to this web service.
Funny thing is: the open source .NET development environment Sharpdevelop works with this service as expected.
Oct 05
Sebastian Garde says:
Hi Seref, I believe there is a problem with java.io.IOException and MalformedUR...Hi Seref,
I believe there is a problem with java.io.IOException and MalformedURLException in the services
getArchetypeInADL
getArchetypesInADL
These exception shouldn't really be exposed to the webservice (at least not in the way they are), so consider this a bug.
.NET wouldn't care about java.io and java.net exception and this is probably the reason why it works fine there.
I have fixed it locally and it will be deployed in the next release.
Thanks
Sebastian
Oct 05
Seref Arikan says:
Thanks Sebastian, I'd appreciate an update to this page when the next release i...Thanks Sebastian,
I'd appreciate an update to this page when the next release is deployed, so that I can give it a go.
Nov 04
Richard Kavanagh says:
Not sure exactly which service this would fit within in, but it would be usefull...Not sure exactly which service this would fit within in, but it would be usefull to know whether an archetype is a specialised form of another archetype, and if so what the parent archetype is. This would save having to parse each archetype ADL file to derive this information.
Nov 05
Thomas Beale says:
Richard, In future, archetypes will move to be more like files in any object pr...Richard,
In future, archetypes will move to be more like files in any object programming language, where you can't tell from the file name /archetype id what the inheritance lineage is. This is a good thing from the identification point of view, and falls into line with how all programming languages work today. See http://www.openehr.org/wiki/display/spec/Development+and+Governance+of+Knowledge+Artefacts (two document downloads) for details. I believe these principles are relevant for managing all semantic artefacts, including ref sets, in openEHR.
The latest ADL tools (for some time now) generate complete inheritance lineage information from a repository of archetypes. From a services point of view, it means having functions like getAncestors(an_archetype_id), getDescendants(an_archetype_id).
Nov 05
Richard Kavanagh says:
Thanks for the reply Thomas. I am aware of how the archetype specialisation is b...Thanks for the reply Thomas. I am aware of how the archetype specialisation is being implemented within the ADL and agree that going forwards this is indeed the correct thing to do. My concern relates more to how the web services can support the development of systems.
Say for an example you had an application that wanted to create a tree list of archetypes akin to that displayed in the current Ocean tools. You can use the existing services to get the complete list of archetypes, but where you would position them in the tree is not so clear. The current tools have all specialised archetypes as a leaf node of its parent. That would mean that even if the getAncestors(an_archetype_id) function existed you would have to execute it for each archetype to see where it would fit in the tree - that would be a lot of calls to the webservice.
Nov 05
Sebastian Garde says:
Hi, yes - I agree that there is value in having webservices for this. One way ...Hi,
yes - I agree that there is value in having webservices for this.
One way is to add the parent archetype id to the getDescriptionForArchetype(s).
Also, there could be a getParent(s) (or getAncestors) service where you can get this information for one archetype as well as a selection of archetypes.
All not that hard to do from a CKM point of view once we decide.
Sebastian
Nov 05
Richard Kavanagh says:
Sebastian - how about something similar to the "getAllArchetypeIds" that accepts...Sebastian - how about something similar to the "getAllArchetypeIds" that accepts parameters stating the metadata it wants returning in addition to the ArchetypeIds, this would save a large number of future calls for ths information. Obviously the other services would be still be required for more targetted usecases.
Nov 05
Sebastian Garde says:
Richard - I think you are right - get DescriptionForAllArchetypesRichard - I think you are right - get DescriptionForAllArchetypes
Nov 05
Thomas Beale says:
Another thing to consider a function that returns a set of triplets, with ...Another thing to consider a function that returns a set of triplets, with parent/child specialisation relationships (slot relationships would also be a possible thing to return).