SOAP Webservices - HISTORICAL

The SOAP-based CKM webservices described on this page are no longer in use and only kept here for historical reasons.

As of CKM Release 1.10.0 (July 2018), please use the new CKM REST API described at https://ckm.openehr.org/ckm/rest-doc/ (or the respective URL for other CKM instances).



Usage

Formal Specification (WSDL): http://openehr.org/ckm/services/ArchetypeFinderBean?wsdl

Examples using access directly via HTML: 

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) | getArchetypeXMLURL(String archetypeId)
         Retrieves the URL to the ADL|XML representation of the Archetype.

String[]

getArchetypeADLURLs(String[] archetypeIds) | getArchetypeXMLURLs(String[] archetypeIds)
         Retrieves the URLs to the ADL|XML representation of the Archetypes.

String

getArchetypeInADL(String archetypeId) | getArchetypeInXML(String archetypeId)
          Retrieves the archetype in ADL-Form|XML-Form and gives it back as a String.

String[]

getArchetypesInADL(String[] archetypeIds) | getArchetypesInXML(String[] archetypeIds)
          Retrieves the archetypes in ADL-Form|XML-Form and gives them back as a String-array.

String

getArchetypeInADLFromCiteableId(String cidArchetype, Integer assetVersion) | getArchetypeInXMLFromCiteableId(String cidArchetype, Integer assetVersion)

         Retrieves an archetype in ADL|XML from its citeable identifier and asset version. You can see the citeable identifier of an archetype for example in the direct URL provided on the "Share with Colleague" tab of each archetype (when signed in - e.g. 1013.1.130)

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 (i.e. the concept specified in the text of the concept - usually the at0000 code. This doesn't consider the concept label of the archetype id - use getArchetypeIdsFromPartialId for this purpose.
    • 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