Best Practices for Including Enumerated Value Domains in UML Models What are the mechanics of creating CDEs associated with enumerated value domains in applications developed in caBIG?

Questions from VCDE How does a modeler do add a enumerated Value Domains in a UML model? How does the SIW support enumerated Value Domains? How do you find permissible value lists to re-use? Are there other manual steps that need to be performed by caDSR content curators? Using a real life example (e.g., AE CDEs from BRIDG/caAERS) provide a real-life example of how enumerated Values from Modeling world are translated into the metadata world?

Available Resources SIW Guide_v401v2.pdf Guide_v401v2.pdf Enumerated Value Domains Best Practices for UML Models Wiki mL+Models caCORE Software Development Kit (SDK) Documentation ammersGuide.pdf

What are enumerated vs non- enumerated value domain types? Enumerated – the permissible values to be used in the value domain are registered in the caDSR Non-enumerated – 1) the permissible values to be used in the value domain are not specifically registered in the caDSR; the permissible values may be defined ‘by reference’ to a source of the values, such as a parent concept, a file or a web site; 2) a non-enumerated value domain may also describe the type of information to be collected by a data element without providing specific values.

Use Case Examples of Value Domains Case 1: There a list of specific values needed for the model attribute. For example, Yes or No; Male or Female (this is an enumerated value domain) Case 2: There is specific guidance needed for population of the attribute. For example, provide a 500 character or less summary of the additional treatments provided in the emergency room. (this is a non-enumerated value domain) Cases 3 and 4: There a list of permissible values that can be specified by a parent EVS concept. – Case 3: Use all the values under a parent concept (this is a non-enumerated value domain) – Case 4 : *Use some of the values under a parent concept (this is an enumerated value domain) Case 5: *There a list that can be found at a linked web site or in a linked document. (this is a non- enumerated valued domain with a reference document that includes the link) Case 6: There is no a list of values or description for the attribute. (Register with a generic value domain that matches the datatype of the model attribute) * Requires manual curation after model registration

Use Case Case 1: There a list of specific values needed for the model attribute. For example, Yes or No; Male or Female (this is an enumerated value domain)

Using Value Domains (VD) in UML Models – Reuse of Existing VD Determine if an attribute needs a value domain : –does the attribute have a specific set of permissible values or a description of the type of information to be collected? – Is there an existing VD that can be reused? - YES Find a VD for reuse – search for a similar CDE or VD using the CDE Browser or Curation Tool – search CDE, VD, VM and/or PV by term or concept; use the Compare function in CDE Browser to review Modify/Version existing VD – contact VD owner – manual curation will be needed Link the VD to be used by a UML Model attribute using the SIW – link to an existing Value Domain by public ID and version *New resource?: a decision tree to help users with VD selection and creation process

Using Value Domains (VD) in UML Models – Using Local VDs (LVD) Determine if an attribute needs a value domain : –does the attribute have a specific set of permissible values or a description of the type of information to be collected? – Is there an existing VD that can be reused? - NO Define the type of LVD needed – enumerated or non-enumerated Create the LVD in the UML model

Creating Local Value Domains (LVD) in a UML Model Create a package named ValueDomain Create a class in the package with the stereotype of ‘CADSR Value Domain’ or ‘enumeration’ Assigned a name to the class – this name will become the name of the LVD Complete a definition for the LVD Add all required tags to the LVD class – this should done with the SIW

UML Model Example Package Class

Using SIW to Add Value Domain Class Tags

Example - Using the SIW to Find a Conceptual Domain

Example - UML Tags added with SIW for Value Domain Class

Steps to Add the Permissible Values as Attributes of the LVD Class Each attribute must have a name and a definition. When registered into the caDSR, the attribute becomes the ‘permissible value’. If the permissible value is mapped to a concept - the name of the concept will be the value meaning name and the definition of the concept will be the value meaning definition. If the permissible value is not mapped to a concept – the name of the permissible value will be the value meaning name and the definition entered in the model will be the value meaning definition If there is a conflict as to choice of a value meaning name or definition during the UML Loader registration process, the permissible value will not be automatically registered and will have to be added by manual curation. Concatenated concepts can be used (i.e., a primary concept with qualifiers) and added in the SIW.

Using the SIW to Add Permissible Value Definition and Concepts

Example - Tags for Permissible Value Attributes

Pointing a UML Attribute to a LVD Using the SIW, UML Attribute to indicate that it should use a LVD defined in the model The tag name is CADSR Local Value Domain The value to use is the name of the LVD class to be related to the attribute

UML Attribute Associated with a LVD

Example - Required Tags Local Value Domain Related to an Attribute

Use Case Case 2: There is specific guidance needed for population of the attribute. For example, provide a 500 character or less summary of the additional treatments provided in the emergency room. (this is a non-enumerated value domain and the definition will be the definition of the LVD)

Using SIW to Add Value Domain Class Tags

Example - Required UML Tags for Value Domain Class N

Use Case Case 3: Use all the values under a parent concept (this is a non-enumerated value domain) Create a non-enumerated LVD and associate it with an attribute. 1) Add the ValueDomainConcept tags to the VD in the UML Model or 2) manually curate post-load to add parent concept.

UML Tags for a “Top-Level” Concept for a Value Domain List of Permissible Values ValueDomainConceptCode ValueDomainConceptDefinition[_n] ValueDomainConceptDefinitionSource ValueDomainConceptPreferredName This will need to be done manually in the UML model.

Find the VD and Select a Parent Concept Using Curation Tool

Example of Adding a Parent Concept in the Curation Tool

Example of a Parent Concept for All Permissible Values

Use Case Case 4 : *Use some of the values under a parent concept (this is an enumerated value domain) Create a non-enumerated LVD and associate it with an attribute. Post-load change the VD type to enumerated. Manually curate to add a parent concept and select some values under a parent concept as permissible values. * Requires manual curation after model registration

Use Curation Tool to Add Values from a Parent List Post Registration

Use Case Case 5: *There a list that can be found at a linked web site or in a linked document. (this is a non- enumerated valued domain with a reference document that includes the link) Create a non-enumerated LVD and associate it with an attribute. Post-load manually curate to add a reference document that provides information about the location of permissible values. This can not current be done with either a UML modeling tool or the SIW. * Requires manual curation after model registration

Use Curation to Add Reference Document Post-load

Example of a Reference Document

Use Case Example Case 6: There is not a list of values for the attribute. (Local value domain not required; use generic value domain) For example, if the datatype of the attribute is CD the generic CD value domain will be used.

Example of Using Generic Value Domain

Post Load Curation Add any missing permissible values, permissible values that need additional qualifiers, and permissible values that are not associated with concepts to Value Domains Add link to a parent concept and change VD type to enumerated if tags were not added to model Add a selection of values that are sub-concepts to a parent concept Add a Reference Document with a link to a list of permissible values

Enumerated Value Domains for UML Models – Some Answers Need better guidance for model developers on how reuse existing VDs or how to create LVDs Finding VDs for reuse is not simple Lack of clear documentation as to how the various tools should be used and what limitations there are in the tools Need to clarify Silver Compatibility Guidelines with respect to enumerated Value Domains Current process can require manual curation after model registration Some functions such as adding Reference Documents for enumerations by reference are not supported by current tools

Questions from VCDE How does a modeler do add a enumerated Value Domains in a UML model? How does the SIW support enumerated Value Domains? How do you find permissible value lists to re-use? Are there other manual steps that need to be performed by caDSR content curators? Using a real life example (e.g., AE CDEs from BRIDG/caAERS) provide a real-life example of how enumerated Values from Modeling world are translated into the metadata world?

Next Steps? Have questions been answered? Is additional information/materials/training needed? What format? ?