The get_children message returns all the children of a particular term. A client may want a list of all the children in order to expand a node of the vocabulary tree when a user is browsing through the tree.


Populating Children of Tree Nodes

The get_children message is used to populate tree nodes in the ontology Navigate Terms and Find Terms views. In both of these cases the table / path (root) to search are known.
The sequence of events is as follows:

  1. The client sends a message with the following settings:

max = 200 (or higher)
type = core

  • Note

    The default for the "max" setting is 200. If you wish to set this default higher you can do this by adding the following parameter to the Ontology cell:
    Parameter Name: ONTMAX
    Parameter Value: enter a number that represents the maximum number of terms to return.



  1. ONT server performs the following steps:
    1. Parses <parent> to obtain the table key and path. Queries the table of tables to confirm that the user / role can access the table that is reference by the table key passed in. This call returns the table name referenced by that key. If not, return coded error. The client receives error message with code "TABLE_ACCESS_DENIED".
    2. If max is set, the database is queried for that number of children associated with the parent passed in.
    3. (New in 1.7.13) If numLevel is set, the query will return up to and including the number of levels specified by numLevel (eg. numlevel=2 returns two levels of descendants, numLevel=4 returns four levels of descendants). By default, the function assumes numLevel = 1 and will return the direct descendants of the concept, which is one level of children.  When the numLevel = -1 the function will return ALL descendants of the concept... 
    4. If count < max or no mas set, the database is queried for the entire list of children that meets the parent criteria.
    5. If count > max a coded error message is sent back.


  1. If no errors, the client receives a list of children and populates the tree.
  2. If max exceeded, the client receives an error message with the code "MAX_EXCEEDED". A dialog box is displayed to ask if the user wants to see all nodes. If no – done. If yes – client sends another message with max=empty.



get_children Request Message

Possible "hiddens" Settings

Some ontology terms exist but for various reasons are not displayed in the query tree.

Value

Description

false

Do not return data categorized as "hidden"

true

Include data categorized as "hidden"



Possible "synonyms" Settings

Some ontology terms are listed as synonyms for other terms.

Value

Description

false

Do not return data categorized as "synonym"

true

Include data categorized as "synonym"



Possible "type" Settings


Value

Description

default

Return all data except system / date information

core

Return all data except system / date information (same as default)

all

Return all data



Possible "blob" Settings


Value

Description

Example

false

Do not return data stored as a blob or clob

xml, comments

true

Return xml and comments



Possible "numLevel" Settings


Value

Description

1

The direct descendants of the concept, which is one level of children, the default.

integer >1

up to and including the number of levels specified by numLevel (eg. numlevel=2 returns two levels of descendants, numLevel=4 returns four levels of descendants)
-1ALL descendants of the concept

get_children Response Message

The request has the following settings:
type=default
blob=true
Response Message:
<message_body>
<concepts>
<concept>
<level>1</level>
<key>\\i2b2\RPDR\Diagnoses\Circulatory system (390-459)\Acute Rheumatic fever (390-392)</key>
<name>Acute Rheumatic fever</name>
<synonym_cd>N</synonym_cd>
<visualattributes>FA </visualattributes>
<totalnum/>
<basecode/>
<metadataxml/>
<facttablecolumn>concept_cd</facttablecolumn>
<tablename>concept_dimension</tablename>
<columnname>concept_path</columnname>
<columndatatype>T</columndatatype>
<operator>LIKE</operator>
<dimcode>\ RPDR\Diagnoses\Circulatory system (390-459)\Acute Rheumatic fever (390-392)</dimcode>
<comment/>
<tooltip>Diagnoses \ Circulatory system \ Acute Rheumatic fever</tooltip>
</concept>
</concepts>
</message_body>