LexEVS 5.0 Value Domain and Pick List November, 2009.

LexEVS 5.0

Value Domain and Pick List

November, 2009

• Overview:

• Provide the user with an overview of Value Domain Definition and Pick List Definition of the LexGrid model.

• Talks about Value Domain and Pick List Services that are available in LexEVS API.

Session Details: Value Domain and Pick List Course Outline

Session Details: Value Domain and Pick List Course Objectives

When you complete this course, you will be able to: • Understand and define the core structure of Value Domain and Pick List

Definitions of the LexGrid Model.

• Define all the Value Domain and Pick List services in LexEVS API.

Session Details: LexGrid 2009 Model Lesson Syllabus

• Lesson 1: Value Domain Definition

• Lesson 2: Pick List Definition

• Lesson 3: Value Domain API

• Lesson 4: Pick List API

Lesson 1: Value Domain Definition

• When you complete this lesson, you will be able to: • Understand and define Value Domain Definition of the LexGrid Model.


What Is It?

• The Value Domain Definition of the LexGrid Model is the proposed mechanism for describing the contents of Value Domain.


Value Domain Definition Model

Value Domain Definition Model • Diagram showing value domain definition of the LexGrid model.



• valueDomains : Collection of Value Domain Definitions• mappings : A list of all of the local identifiers and defining URI's that are used in the

associated resource• changedEntry : A top level versionable entry• Properties : A collection of properties• valueDomainDefinition : A definition of a given value domain


Value Domain Definition Class

• source : The local identifiers of the source(s) of this value domain definition. Must match a local id of a supportedSource in the corresponding mappings section.

• representsReamsOrContext : The local identifiers of the context(s) in which this value domain applies. Must match a local id of a supportedContext in the corresponding mappings section.

• valueDomainURI : The URI of this value domain• valueDomainName : The name of this domain, if any• defaultCodingScheme : Local name of the primary coding scheme from which the

domain is drawn. defaultCodingScheme must match a local id of a supportedCodingScheme in the mappings section.


DefinitionEntry Class

• valueDomainDefinition can have 0 or more definitionEntry.• ruleOrder : Relative order in which this entry should be applied• Operator : Defines how this entry is to be applied to the value domain

• OR : Add the set of entityCodes described by the currentEntity to the value domain. (logical OR)• SUBTRACT : Subtract (remove) the set of entityCodes described by the currentEntity from the

value domain. (logical NAND)• AND : Only include the entity codes that are both in the value domain and the definition entry.

(logical AND)


DefinitionEntry Reference

• Each definitionEntry can reference one of the following :• codingSchemeReference : A reference to all of the entity codes in a given coding scheme

• codingScheme : The local identifier of the coding scheme that the entity codes are drawn from. codingSchemeName must match a local id of a supportedCodingScheme in the mappings section.

• valueDomainReference : A reference to the set of codes defined in another value domain • valueDomainURI : The URI of the value domain to apply the operator to. This value domain may

be contained within the local service or may need to be resolved externally.

• entityReference : A reference to an entityCode and/or one or more entityCodes that have a relationship to the specified entity code


DefinitionEntry entityReference

• entityReference : A reference to an entityCode and/or one or more entityCodes that have a relationship to the specified entity code.

• entityCode : The entity code being referenced• entityCodeNamespace : Local identifier of the namespace of the entityCode.

Must match a local id of a supportedNamespace in the corresponding mappings section. If omitted, the URI of the defaultCodingScheme will be used as the URI of the entity code.

• leafOnly : If true and referenceAssociation is supplied and referenceAssociation is defined as transitive, include all entity codes that are "leaves" in transitive closure of referenceAssociation as applied to entity code. Default: false

• referenceAssociation : The local identifier of an association that appears in the native relations collection in the default coding scheme. This association is used to describe a set of entity codes. If absent, only the entityCode itself is included in this definition.


DefinitionEntry entityReference

• entityReference• targetToSource : If true and referenceAssociation is supplied, navigate from

entityCode as the association target to the corresponding sources. If transitiveClosure is true and the referenceAssociation is transitive, include all the ancestors in the list rather than just the direct "parents" (sources).

• transitiveClosure : If true and referenceAssociation is supplied and referenceAssociation is defined as transitive, include all entity codes that belong to transitive closure of referenceAssociation as applied to entity code. Default: false.



• Diagram showing value domain definition of the LexGrid model.


Possible Forms

• Code system – all concept codes in the referencing code system

• Value Domain – all concept codes defined in the referencing Value Domain

• Code system/concept code – individual code

• Code system/concept code + relationship + additional rules (leaf only, targetToSource, ...)

• Combination of any of the above with or/and/difference operators


Value Domain Resolution

• A value domain definition has to be made against a specific version of a code system.

• But it doesn’t have to be resolved against the same version.

• Even a simple list (a, b, c, d) needs to be resolved as, at some future date, “c” might be retired.

• Resolution does not create static artifact.


Example 1

• Value Domain Definition to include all the concept codes in Code System ‘Automobiles’ :

@

Domestic Auto Maker [005]

Automobile[A0001]

General Motors [GM]hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

Code System : ‘Automobiles’

Result :

Ford Motor Company [Ford] Jaguar [Jaguar]

Chevrolet [Chevy]

Oldsmobile [73]Truck [T0001]

Car [C0001]

Tires [Tires]uses

hasSubtype

hasSubtype

hasSubtype

valueDomainDefinitionvalueDomainURI : urn:VDexample1valueDomainName : All AutomobilesdefaultCodingScheme : Automobiles

definitionEntryruleOrder : 1Operator : OR

codingSchemeReferencecodingSchemeURI : Automobiles


Automobile[A0001]

Ford Motor Company [Ford]

General Motors [GM]

Jaguar [Jaguar]

Chevrolet [Chevy]


Car [C0001]

Tires [Tires]

hasSubtype

hasSubtype

hasSubtype

hasSubtype

uses

hasSubtype

hasSubtype

hasSubtype

@


Automobile[A0001]

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype



Example 2

• Value Domain Definition to include all the concept codes except ‘General Motors’ and its children in Code System ‘Automobiles’ :

@


Automobile[A0001]


General Motors [GM]

Jaguar [Jaguar]

Chevrolet [Chevy]


Car [C0001]

Tires [Tires]

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

uses

hasSubtype

hasSubtype

hasSubtype


valueDomainDefinitionvalueDomainURI : urn:VDexample2valueDomainName : All Automobiles BUT GMdefaultCodingScheme : Automobiles


codingSchemeReferencecodingSchemeURI : Automobiles


Automobile[A0001]

Ford Motor Company [Ford] Jaguar [Jaguar]

Truck [T0001]

Car [C0001]

Tires [Tires]

hasSubtype

hasSubtype

hasSubtype

uses

hasSubtype

Result :

definitionEntryruleOrder : 2Operator : SUBTRACT

entityReferenceentityCode : GMreferenceAssociation : hasSybtypetransitiveClosure : true


Review 1

To complete the Value Domain Definition stated below to get only the leaf concepts (i.e codes : Jaguar, Chevy and 73) of Domestic Auto Maker using just one definitionEntry :

• What should be that start conceptCode ?• Should the trasitiveClosure be True or false ?• Should the leafOnly be True or false ?

@


Automobile[A0001]


General Motors [GM]

Jaguar [Jaguar]

Chevrolet [Chevy]


Car [C0001]

Tires [Tires]

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

uses

hasSubtype

hasSubtype

hasSubtype


valueDomainDefinitionvalueDomainURI : urn:VDquestion1valueDomainName : Leaf of domestic auto makerdefaultCodingScheme : Automobiles


entityReferenceentityCode :referenceAssociation : hasSybtypetransitiveClosure :leafOnly :


Answer 1

To complete the Value Domain Definition stated below to get only the leaf concepts (i.e codes : Jaguar, Chevy and 73) of Domestic Auto Maker using just one definitionEntry : What should be the start entityCode ? 005 Should the trasitiveClosure be True or false ? True Should the leafOnly be True or false ? True

@


Automobile[A0001]


General Motors [GM]

Jaguar [Jaguar]

Chevrolet [Chevy]


Car [C0001]

Tires [Tires]

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

uses

hasSubtype

hasSubtype

hasSubtype


valueDomainDefinitionvalueDomainURI : urn:VDquestion1valueDomainName : Leaf of domestic auto makerdefaultCodingScheme : Automobiles


entityReferenceentityCode : 005referenceAssociation : hasSybtypetransitiveClosure : trueleafOnly : true


Review 2

Using the previous reviews Value Domain Definition (VDQuestion1), complete the Value Domain Definition stated below to exclude entity code ‘Jaguar’ :

• What should be that start entityCode ?• Should the trasitiveClosure be True or false ?• Should the leafOnly be True or false ?• What should be the the Operator (OR, ADD or SUBTRACT) ?

@


Automobile[A0001]


General Motors [GM]

Jaguar [Jaguar]

Chevrolet [Chevy]


Car [C0001]

Tires [Tires]

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

uses

hasSubtype

hasSubtype

hasSubtype


valueDomainDefinitionvalueDomainURI : urn:VDquestion2valueDomainName : Leaf auto maker MINUS JaguardefaultCodingScheme : Automobiles


valueDomainReferencevalueDomainURI : VDQuestion1

definitionEntryruleOrder : 2Operator :

entityReferenceentityCode : referenceAssociation : hasSybtypetransitiveClosure :leafOnly :


Answer 2

Using the previous reviews Value Domain Definition (VDQuestion1), complete the Value Domain Definition stated below to exclude entity code ‘Jaguar’ : What should be that start entityCode ? Jaguar Should the trasitiveClosure be True or false ? false Should the leafOnly be True or false ? false What should be the the Operator (OR, ADD or SUBTRACT) ? SUBTRACT

@


Automobile[A0001]


General Motors [GM]

Jaguar [Jaguar]

Chevrolet [Chevy]


Car [C0001]

Tires [Tires]

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

hasSubtype

uses

hasSubtype

hasSubtype

hasSubtype


valueDomainDefinitionvalueDomainURI : urn:VDquestion2valueDomainName : Leaf auto maker MINUS JaguardefaultCodingScheme : Automobiles


valueDomainReferencevalueDomainURI : VDQuestion1

definitionEntryruleOrder : 2Operator : SUBTRACT

entityReferenceentityCode : JaguarreferenceAssociation : hasSybtypetransitiveClosure : falseleafOnly : false


Questions?

Lesson 2: Pick List Definition

• When you complete this lesson, you will be able to: • Understand and define Pick List Definition of the LexGrid Model.


What Is It?

• The Pick List Definition of the LexGrid Model is the proposed mechanism for describing the contents of Pick List.


Pick List Definition Model




• pickListDefinition is versionable.

• pickLists : Collection of Pick List Definitions

• mappings : A list of all of the local identifiers and defining URI's that are used in the associated resource

• changedEntry : A top level versionable entry

• properties : A collection of properties

• pickListDefinition : A definition of a given Pick list


pickListDefinition class

• source : The local identifiers of the source(s) of this pick list definition. Must match a local id of a supportedSource in the corresponding mappings section.

• defaultPickContext : The local identifiers of the context used in the definition of the pick list

• pickListId : An identifier that uniquely names this list within the context of the collection

• representsValueDomain : The URI of the value domain definition that is represented by this pick list

• defaultEntityCodeNamespace : Local name of the namespace to which the entry codes in this list belong. defaultEntityCodeNamespace must match a local id of a supportedNamespace in the mappings section.


pickListDefinition class

• defaultLanguage : The local identifier of the language that is used to generate the text of this pick list if not otherwise specified. defaultLanguage must match a local id of a supportedLanguage in the mappings section.

• defaultSortOrder : The local identifier of a sort order that is used as the default in the definition of the pick list

• completeDomain : True means that this pick list should represent all of the entries in the domain. Any active entity codes that aren't in the specific pick list entries are added to the end, using the designations identified by the defaultLanguage, defaultSortOrder and defaultPickContext. Default: false


pickListEntryNode class

• Each pickListDefinition can have 0 or more pickListEntryNode.• pickListEntryNode is versionable.• pickListEntryNode can contain properties.• pickListEntryId : Unique identifier of this node within the list


pickListEntryNode class

• Each pickListEntryNode can either have• pickListEntryExclusion or• pickListEntry


pickListEntryExclusion class

• An entity code that is explicitly excluded from a pick list.• entityCode : Entity code associated with this entry• entityCodeNamespace : Local identifier of the namespace of the entity code if

different than the pickListDefinition defaultEntityCodeNamespace entityCodeNamespace must match a local id of a supportedNamespace in the mappings section.


pickListEntry class

• An entity code and corresponding textual representation. • pickText : The text that represents this node in the pick list. Some business rules may

require that this string match a presentation associated with the entityCode• pickContext : The local identifiers of the context(s) in which this entry applies

entryOrder : Relative order of this entry in the list• entityCode : Entity code associated with this entry• entityCodeNamespace : Local identifier of the namespace of the entity code if

different than the pickListDefinition defaultEntityCodeNamespace


pickListEntry class

• propertyId : The property identifier associated with the entityCode and entityCodeNamespace that the pickText was derived from. If absent, the pick text can be anything. Some terminologies may have business rules requiring this attribute to be present.

• isDefault : True means that this is the default entry for the supplied language and context

• matchIfNoContext : True means that this entry can be used if no contexts are supplied, even though pickContext is present

• Language : The local name of the language to be used when the application/user supplies a selection language matches. If absent, this matches all languages. language must match a local id od of a supportedLanguage in the mappings section.





Possible Forms

• Value Domain – all concept codes in the value domain• completeDomain = true

• Code system/concept code – individual code (inclusion and exclusion)

• And/or combination of both


Pick List Resolution

• A Pick List definition has to be made against a specific value domain.

• Even a simple list (a, b, c, d) needs to be resolved as, at some future date, “c” might be retired.

• Resolution does not create static artifact.


Example 1

• Pick List Definition to include all the preferred designations from valueDomainURI : urn:VDexample1 (Value Domain Definition ‘urn:VDexample1’ includes all the concept codes in code system ‘Automobiles’) :

pickListDefinitionpickListId : PLexample1representsValueDomain : urn:VDexample1completeDomain : true


Example 2

• Pick List Definition to include all the preferred designations from valueDomainURI : urn:VDexample1 (Value Domain Definition ‘urn:VDexample1’ includes all the concept codes in code system ‘Automobiles’) but exclude code ‘Tires’:

pickListDefinitionpickListId : PLexample2representsValueDomain : urn:VDexample1completeDomain : true

pickListEntryNodepickListEntryId : PLE1

pickListEntryExclusionentityCode : TiresentityCodeNamespace : Automobiles


Review 1

To complete the below Pick List Definition to include all the preferred designations from valueDomainURI : ‘urn:VDexample2‘ (Value Domain Definition ‘urn:VDexample1’ includes all the concept codes in code system ‘Automobiles’ except ‘GM’ and its children) and include pick text ‘Car’ from code ‘C0001’ text ‘ and code system ‘Automobiles’ :

• Should the completeDomain be True or False ?• How to include new pick text to the definition ?

pickListDefinitionpickListId : PLquestion1representsValueDomain : urn:VDexample2completeDomain :


Answer 1

To complete the below Pick List Definition to include all the preferred designations from valueDomainURI : ‘urn:VDexample2‘ (Value Domain Definition ‘urn:VDexample1’ includes all the concept codes in code system ‘Automobiles’ except ‘GM’ and its children) and include pick text ‘Car’ from code ‘C0001’ and code system ‘Automobiles’ :

Should the completeDomain be True or False ? True How to include new pick text to the definition ? Add pickListEntry to the

definition

pickListDefinitionpickListId : PLquestion1representsValueDomain : urn:VDexample2completeDomain : true

pickListEntryNodepickListEntryId : PLE1

pickListEntrypickText : CarentityCode : C0001entityCodeNamespace : Automobiles


Questions?

Lesson 3: Value Domain API

• When you complete this lesson, you will be able to: • Understand the Value Domain Services available in LexEVS API.


What is it ?

• Value Domain API will provide ability to load Value Domain Definitions into LexGrid repository.

• Provides ability to apply user restrictions.

• Dynamically resolve the definitions during run time.

• Value Domain API is available as an extension to LexEVS 5.0 release.

Here are the classes that implements Value Domain in LexEVS API :

VDSServices – class to handle list of Value Domain Definitions Object to and fro databaseVDServices - Class to handle individual Value Domain Definition objects to and fro database.VDEntryServices - Class to handle Value Domain Entry objects to and fro database.LexEVSValueDomainServices - Primary interface for LexEVS Value Domain APILexEVSValueDomainServicesImpl - Implementation of LexEVSValueDomainServices which is primary

interface for LexEVS Value Domain API.LoadValueDomain - Imports the value Domain Definitions in the source file, provided in LexGrid canonical

format, to the LexBIG repository.ResolvedValueDomainCodedNodeSet - Contains coding scheme version reference list that was used to

resolve the value domain and the coded node set.ResolvedValueDomainDefinition - A resolved Value Domain definition containing the coding scheme

version reference list that was used to resolve the value domain and an iterator for resolved concepts.


Classes implementing Value Domain API

Class Name Description

VDSServices Class to handle list of Value Domain Definitions Object to and fro database

VDServices Class to handle individual Value Domain Definition objects to and fro database.

VDEntryServices Class to handle Value Domain Entry objects to and fro database.

LexEVSValueDomainServices Primary interface for LexEVS Value Domain API

LexEVSValueDomainServicesImpl Implementation of LexEVSValueDomainServices which is primary interface for LexEVS Value Domain API.

LoadValueDomain Imports the value Domain Definitions in the source file, provided in LexGrid canonical format, to the LexBIG repository.

ResolvedValueDomainCodedNodeSet Contains coding scheme version reference list that was used to resolve the value domain and the coded node set.

ResolvedValueDomainDefinition A resolved Value Domain definition containing the coding scheme version reference list that was used to resolve the value domain and an iterator for resolved concepts.


Load Services

There are three methods that could be used to load Value Domain Definitions :• loadValueDomain(ValueDomainDefinition vddef, String systemReleaseURI) - Loads supplied

valueDomainDefinition object

• loadValueDomain(InputStream inputStream, boolean failOnAllErrors) - Loads valueDomainDefinitions found in inputStream

• loadValueDomain(String xmlFileLocation, boolean failOnAllErrors) - Loads valueDomainDefinitions found in input xml file

loadValueDomain(String xmlFileLocation, boolean failOnAllErrors)

Description: Loads valueDomainDefinitions found in input xml file

Input: java.lang.Stringboolean

Output: none

Exception: LBException

Implementation Details:

Implementation:Step 1: Call this method on the associated LexEVS Value Domain Service instance to load all Value Domain Definitions found in an XML file that is in LexGrid format. Sample Call:Step 1 : Using existing LexBIGInstance, get the generic extension LexEVSValueDomainServicesorg.lexgrid.extension.valuedomain.LexEVSValueDomainServices vds = lbs.getGenericExtension(“LexEVSValueDomainServices”);Step 2 : Call load method by passing the inputfile location and boolean flag whether to stop on load errors. :vds.loadvalueDomain(inputXMLFile, true);


Query Services

• isConceptInDomain(String entityCode, URI valueDomainURI) - Determine if the supplied entity code is a valid result for the supplied value domain and, if it is, return the particular codingSchemeVersion that was used

• isConceptInDomain(String entityCode, URI entityCodeNamespace, CodingSchemeVersionOrTag csvt, URI valueDomainURI) - Similar to previous method, this method determine if the supplied entity code and entity namespace is a valid result for the supplied value domain when resolved against supplied Coding Scheme Version or Tag

isConceptInDomain(String entityCode, URI entityCodeNamespace, CodingSchemeVersionOrTag csvt, URI valueDomainURI)

Description: Similar to previous method, this method determine if the supplied entity code and entity namespace is a valid result for the supplied value domain when resolved against supplied Coding Scheme Version or Tag.

Input: java.lang.String,java.net.URI,org.LexGrid.LexBIG.DataModel.Core. CodingSchemeVersionOrTagjava.net.URI

Output: org.LexGrid.LexBIG.DataModel.Core. AbsoluteCodingSchemeVersionReference

Exception: org.LexGrid.LexBIG.Exceptions.LBException


Implementation:Step 1: Call this method on the associated LexEVS Value Domain Service instance to determine if the supplied entity code and its entity namespace is a valid in the supplied Value Domain URI when resolved against supplied Coding Scheme Version or Tag. If it is, return Coding Scheme URI and the Version that was used to resolve, other wise, returns null. Sample Call:Step 1 : Using existing LexBIGInstance, get the generic extension LexEVSValueDomainServicesorg.lexgrid.extension.valuedomain.LexEVSValueDomainServices vds = lbs.getGenericExtension(“LexEVSValueDomainServices”);Step 2 :Call isConceptInDomain method:AbsoluteCodingSchemeVersionReference acsvr = vds.isConceptInDomain(“conceptA”,”conceptAEntityNamespace”,”codingSchemeVersion”,”valueDomainURI”);


Query Services

• resolveValueDomain(URI valueDomainURI, AbsoluteCodingSchemeVersionReferenceList csVersionList) - Resolve a value domain using the supplied set of coding scheme versions

• ResolvedValueDomainDefinition : A resolved Value Domain Definition containing the Coding Scheme Version reference list that was used to resolve the Value Domain and an iterator for resolved concepts

resolveValueDomain(URI valueDomainURI, AbsoluteCodingSchemeVersionReferenceList csVersionList)

Description: Resolve a value domain using the supplied set of coding scheme versions.

Input: java.net.URI,org.LexGrid.LexBIG.DataModel.Core. AbsoluteCodingSchemeVersionReferenceList

Output: org.lexgrid.extension.valuedomain.dto.ResolvedValueDomainDefinition



Implementation:Step 1: Call this method on the associated LexEVS Value Domain Service instance to resolve supplied value domain against list of Coding Scheme versions if supplied. If Coding Scheme Versions list is not supplied, API will resolve against any version of the loaded Coding Scheme that is referenced by the Value Domain. Returns, object ResolvedValueDomainDefinition which contains AbsoluteCodingSchemeVersionReferenceList which tells which all Coding Scheme and the versions were used for this resolve, plus the ResolvedConceptReferencesIterator, which is an iterator for all the valid concepts that belongs to the Value Domain and Value Domain Definition itself.Sample Call:Step 1 : Using existing LexBIGInstance, get the generic extension LexEVSValueDomainServicesorg.lexgrid.extension.valuedomain.LexEVSValueDomainServices vds = lbs.getGenericExtension(“LexEVSValueDomainServices”);Step 2 :Create AbsoluteCodingSchemeVersionReferenceList:AbsoluteCodingSchemeVersionReferenceList csvList = new AbsoluteCodingSchemeVersionReferenceList();csvList.addAbsoluteCodingSchemeVersionReference(Constructors.createAbsoluteCodingSchemeVersionReference("Automobiles", "2.0"));csvList.addAbsoluteCodingSchemeVersionReference(Constructors.createAbsoluteCodingSchemeVersionReference("AutomobilesParts", "2.0")); Step 3 :Call resolveValueDomain method:ResolvedValueDomainDefinition rvdDef = vds.resolveValueDomain (“valueDomainURI”,csvList);


Query Services• getValueDomainEntitiesForTerm(String term, URI valueDomainURI, String matchAlgorithm) - Resolves

the value domain supplied and restricts to the term and matchAlgorithm supplied • ResolvedValueDomainCodedNodeSet : Contains the codingScheme URI and Version that was

used to resolve and the CodedNodeSet. Note : the CodedNodeSet is unresolved

getValueDomainEntitiesForTerm(String term, URI valueDomainURI, String matchAlgorithm)

Description: Resolves the value domain supplied and restricts to the term and matchAlgorithm supplied. Return object ResolvedValueDomainCodedNodeSet contains the codingScheme URI and Version that was used to resolve and the CodedNodeSet.Note : the CodedNodeSet is unresolved

Input: java.lang.String,java.net.URI,java.lang.String

Output: org.lexgrid.extension.valuedomain.dto.ResolvedValueDomainCodedNodeSet



Implementation:Step 1: Call this method on the associated LexEVS Value Domain Service instance to get the resolved Value Domain Entries as CodedNodeSet that is restricted to supplied term and the match algorithm. Returned CodedNodeSet is not resolved.Sample Call:Step 1 : Using existing LexBIGInstance, get the generic extension LexEVSValueDomainServicesorg.lexgrid.extension.valuedomain.LexEVSValueDomainServices vds = lbs.getGenericExtension(“LexEVSValueDomainServices”);Step 2 :Call getValueDomainEntriesForTerm method:ResolvedValueDomainCodedNodeSet vdvns = vds.getValueDomainEntriesForTerm("General Motors", new URI("AUTO:AllDomesticANDGM"), MatchAlgorithms.exactMatch.name());


Query Services

• isSubDomain(URI childValueDomainURI, URI parentValueDomainURI) - Check whether childValueDomainURI is a child of parentValueDomainURI

• getValueDomainDefinition(URI valueDomainURI) - Returns value domain definition for supplied value domain URI

• listValueDomains(String valueDomainName) - Return the URI's for the value domain definition(s) for the supplied domain name

• getAllValueDomainsWithNoNames() - Return the URI's of all unnamed value domain definition(s)

• getCodingSchemesInValueDomain(URI valueDomainURI) - Returns list of coding scheme summary that is referenced by the supplied value domain

• isDomain(String entityCode, String codingSchemeName, CodingSchemeVersionOrTag csvt) - Determine if the supplied entity code is of type valueDomain in supplied coding scheme and, if it is, return the true, otherwise return false


Remove Services

• removeValueDomain(URI valueDomainURI) - Removes supplied value domain definition from the system

• removeAllValueDomains() - Removes all value domain definitions from the system


Review 1

True or False : Using Value Domain API you can : Load Value Domain Definition ? Resolve Value Domain Definition ? Author Value Domain Definition ? Version Value Domain Definition ? Delete Value Domain Definition ?


Answer 1

True or False : Using Value Domain API you can : Load Value Domain Definition ? True Resolve Value Domain Definition ? True Author Value Domain Definition ? False Version Value Domain Definition ? False Delete Value Domain Definition ? True

Value Domain Definition model does support versioning, but it has not been implemented in LexEVS 5.0 release.


Review 2

True or False : Is the CodedNodeSet resolved in the ResolvedValueDomainCodedNodeSet ?


Answer 2

True or False : Is the CodedNodeSet resolved in the ResolvedValueDomainCodedNodeSet ?False

ResolvedValueDmainCodedNodeSet contains the codingScheme URI and Version that was used to resolve Value Domain and the unresolved CodedNodeSet.


Review 3

True or False : Resolved Value Domain Data are persisted ?


Answer 3

True or False : Resolved Value Domain Data are persisted ? False

Value Domain Definition is resolved dynamically at the runtime and the resulted data are never saved.


Questions?

Lesson 4: Pick List API

• When you complete this lesson, you will be able to: • Understand the Pick List Services available in LexEVS API.


What is it ?

• Pick List API will provide ability to load Pick List Definitions into LexGrid repository.

• Provides ability to apply user restrictions.

• Dynamically resolve the definitions during run time.

• Pick List API is available as an extension to LexEVS 5.0 release.


Classes implementing Pick List API

Here are the classes that implements Pick List in LexEVS API :

Class Name Description

PickListsServices Class to handle list of Pick List Definitions.

PickListServices Class to handle individual Pick List Definition objects to and fro database.

PLEntryServices Class to handle Pick List Entry objects to and fro database.

LexEVSPickListServices Primary interface for LexEVS Pick List API.

LexEVSPickListServicesImpl Implementation of LexEVSPickListServices which is primary interface for LexEVS Pick List API.

LoadPickList Imports the Pick List Definitions in the source file, provided in LexGrid canonical format, to the LexBIG repository.

ResolvedPickListEntyList Class to hold list of resolved pick list entries.

ResolvedPickListEntry Bean for resolved pick list entries.


Load Services

There are three methods that could be used to load Pick List Definitions :• loadPickList(PickListDefinition pldef, String systemReleaseURI) - Loads supplied Pick List

Definition object

• loadPickList(InputStream inputStream, boolean failOnAllErrors) - Loads Pick List Definitions found in inputStream

• loadPickList (String xmlFileLocation, boolean failOnAllErrors) - Loads Pick List Definitions found in input xml file

loadPickList (String xmlFileLocation, boolean failOnAllErrors)

Description: Loads Pick List Definitions found in input xml file

Input: java.lang.Stringboolean

Output: none

Exception: Exception


Implementation:Step 1: Call this method on the associated LexEVS Pick List Service instance to load all Pick List Definitions found in an XML file that is in LexGrid format. Sample Call:Step 1 : Using LexBIGService instance, get the LexEVSPickListServices interface org.lexgrid.extension.valuedomain.LexEVSPickListServices pls = lbs.getGenericExtension(“LexEVSPickListServices”);Step 2 :Call load method by passing the inputfile location and boolean flag whether to stop on load errors. :pls.loadPickList(inputXMLFile, true);


Query Services

• getPickListDefinitionById(String pickListId) - Returns pickList definition for supplied pickListId• getPickListDefinitionsForDomain(URI valueDomainURI) - Returns all the pickList definitions

that represents supplied valueDomain URI• getPickListValueDomain(String pickListId) - Returns an URI of the represented valueDomain of

the pickList• listPickListIds() - Returns a list of pickListIds that are available in the system

listPickListIds()

Description: Returns a list of pickListIds that are available in the system.

Input: none

Output: java.util.List<java.lang.String>



Implementation:Step 1: Call this method on the associated LexEVS Pick List Service instance to get all the PickListIds that are loaded in the system. Sample Call:Step 1 : Using LexBIGService instance, get the LexEVSPickListServices interface using generic extension :org.lexgrid.extension.valuedomain.LexEVSPickListServices pls = lbs.getGenericExtension(“LexEVSPickListServices”);Step 2 :Call listPickListIds method:List<String> plList = pls.listPickListIds();


Query Services

• resolvePickList(String pickListId, boolean sortByText) - Resolves pickList definition for supplied pickListId

• resolvePickListForTerm(String pickListId, String term, String matchAlgorithm, String language, String[] context, boolean sortByText) - Resolves pickList definition by applying supplied arguments

ResolvedPickListEntryList : Contains the list of resolved Pick List Entries. Also provides helpful features to add, remove, enumerate Pick List Entries.

resolvePickListForTerm(String pickListId, String term, String matchAlgorithm, String language, String[] context, boolean sortByText)

Description: Resolves pickList definition by applying supplied arguments.

Input: java.lang.String,java.lang.String,java.lang.String,java.lang.String,java.lang.String[],boolean

Output: org.lexgrid.extension.valuedomain.dto.ResolvedPickListEntryList



Implementation:Step 1: Call this method on the associated LexEVS Pick List Service instance to get list of Pick List Entries that matches the term supplied and meets other supplied restrictions. Sample Call:Step 1 : Using LexBIGService instance, get the LexEVSPickListServices interface org.lexgrid.valuedomain.LexEVSPickListServices pls = lbs.getGenericExtension(“LexEVSPickListServices”);Step 2 :Call resolvePickListForTerm method:ResolvedPickListEntryList pleList = pls.resolvePickListForTerm (“AUTO:DomesticAutoMakers”,”Jaguar”, MatchAlgorithms.exactMatch.name(), “en”, null, true);


Remove Services

• removePickList(String pickListId) - Removes supplied Pick List Definition from the system

removePickList(String pickListId)

Description: Removes supplied Pick List Definition from the system.

Input: java.lang.String

Output: none

Exception: org.LexGrid.LexBIG.Exceptions.LBException,org.LexGrid.managedobj.RemoveException


Implementation:Step 1: Call this method on the associated LexEVS Pick List Service instance to remove Pick List Definition from the system that matches the supplied pickListId. Sample Call:Step 1 : Using LexBIGService instance, get the LexEVSPickListServices interface org.lexgrid.valuedomain.LexEVSPickListServices pls = lbs.getGenericExtension(“LexEVSPickListServices”);Step 2 :Call removePickList method:vds.removePickList ("AUTO:AllDomesticANDGM");


Review 1

True or False : Does the Pick List API provides authoring capability ?


Answer 1

True or False : Does the Pick List API provides authoring capability ? False

Though PickListDefinition and PickListEntryNode are Versionable, LexEVS 5.0 release do not have support for authoring.


Review 2

True or False : Is Pick List API available in lbRuntime.jar in LexEVS 5.0 release ?


Answer 2

True or False : Is Pick List API available in lbRuntime.jar in LexEVS 5.0 release ? False

Value Domain and Pick List API are available as an generic extension to LexEVS 5.0 release.


Review 3

True or False : Using Pick List API you can : Load Pick List Definition ? Resolve Pick List Definition ? Author Pick List Definition ? Version Pick List Definition ? Delete Pick List Definition ?


Answer 3

True or False : Using Pick List API you can : Load Pick List Definition ? True Resolve Pick List Definition ? True Author Pick List Definition ? False Version Pick List Definition ? False Delete Pick List Definition ? True

Pick List Definition model does support versioning, but it has not been implemented in LexEVS 5.0 release.


Questions?

Demo

NOTE : The GUI tool that will be used for demo is under development and is built on top of LexEVS 5.1 release. So this tool is not available in LexEVS 5.0 release.

LexEVS 5.0 Value Domain and Pick List November, 2009.

Documents

value domain definition

value domain valuedomainuri

contents of value domain

value domain valuedomainname

value domain api lesson

given value domain slide

core structure of value

pick list definition