Architecture/VCDE Face-to-Face Semantic Integration Workbench (SIW) and the UML Loader

1. Architecture/VCDE Face-to-Face Semantic Integration Workbench (SIW) and the UML Loader Trainer: Tommie Curtis curtist@mail.nih.gov NCICB Liaison / Expert Curator: Dianne Reeves reevesd@mail.nih.gov

2. Session Details:Session Objectives • Objectives for the overall training session • Describe the purpose of the Semantic Integration Workbench (SIW) • How to launch the SIW • Discuss the function of the four User Modes • Identify the input and output of each User Mode • Set SIW Preferences and Describe Defaults values • Submission of an Annotated UML model xmi file to UML Loader • Decompose a UML class and its attributes into Data Elements • Describe how UML model data elements are organized in the caDSR

3. Building your UML Model for Semantic Integration (Model Developer) Guidance for UML model development is found in the SDK documentation(http://ncicb.nci.nih.gov/NCICB/infrastructure/cacoresdk#Documentation) • Naming Conventions follow formatting conventions for Sun Microsystems Java Bean Specification • Names contain no underscores • Do not abbreviate and avoid use of jargon terms • Do NOT repeat class names in attributes • Class Name starts with an uppercase letter - If there are two words, both are capitalized with no spaces between • Attribute Name starts with a lowercase letter - If name contains two words, the second word is capitalized with no space between words • UML Model must include Tagged Values for definitions • Class tagged value = “documentation” • Attribute tagged value = “description” • Multiplicity of each association must be specified - only association and inheritance relationships are mapped to caDSR metadata. • Role names are important because they are used to create method names

4. Creation of an EA Documentation Report

5. Creation of an EA Documentation Report (cont.)

6. Documentation Example

7. Documentation Example – Annotated Attribute

8. Documentation Example – Annotated Class

9. Use Java Primitive Data Types

10. Preparing your UML Model for Semantic Integration and UML Loading (Model Developer) • CLASS and ATTRIBUTE NAMES MUST BE FROZEN AT THIS POINT • Review UML model for completeness by generating project documentation. • caBIG participants should work with their VCDE metadata mentors throughout this process. • Export the UML model to an xmi file using the guidelines described in the SDK.

11. Introduction:Semantic Integration • Semantic Integration is the series of steps taken to map UML classes and attributes to EVS concept codes. These concepts are then used to build data element concepts and data elements for the caDSR. • This association between caDSR metadata to controlled vocabularies permits unambiguous interpretation of UML model objects and mapping between those objects in different domains. • Resulting metadata is more sharable and interoperable. • The Semantic Integration Workbench (SIW) isthe tool used to facilitate and simplify the semantic integration process.

12. Design System and draw model Run Semantic Connector (First Run) Curate Semantic Connector Report Run Semantic Connector (Second Run) Review Annotated Model Register Metadata (UML Loader) Generate and deploy system (Code Generator) Introduction:SIW and the Semantic Integration Process

13. Semantic Integration Workbench (SIW) Features • Integrated into the semantic integration process. • Uses the same XMI parser as the Semantic Connector and the UML Loader. • Streamlines semantic annotation by offering direct queries to the NCI Thesaurus. • Facilitates requested for new EVS concepts to associate with classes and attributes. • Simplifies review of the the final XMI before registration. • Sets UML Loader defaults.

14. SIW System Requirements • Java Web Start (can be downloaded as part of Java Run Time edition from Sun’s website: http://java.sun.com ). • SIW has been tested on Windows 2000, Linux, Mac OSX, and Solaris 8.

15. Using the Semantic Integration WorkbenchLaunch the SIW • To launch the SIW, enter this URL: http://cadsrsiw.nci.nih.gov • If Java Web Start is already installed, follow the prompts to launch the SIW • Java Webstart dialog box displays. You will see the SIW start-up executing. This will take a few minutes. • Click YES at the Security Warning prompt. • Click INSTALL at the next prompt. • Troubleshooting • If you get a File Download dialog box, you don’t have Java Web Start installed. Click CANCEL and go to the Sun website to download it: http://java.sun.com. • SIW v.1 cannot be run without going to the caDSR SIW web site.

16. Using the Semantic Integration WorkbenchLaunch the SIW(http://ncicb.nci.nih.gov/NCICB/infrastructure/cacore_overview/cadsr)

17. Using the Semantic Integration WorkbenchSIW User Modes • The SIW Welcome panel includes four options for SIW use, listed in the order of their use in the SIW Workflow. 1. 2. 3. 4.

18. Using the Semantic Integration Workbench SIW User Modes • The SIW Welcome panel includes four options for SIW use, listed in the order of their use in the SIW Workflow.

19. Using the Semantic Integration Workbench 1. Run the Semantic Connector (First Run)

20. Using the Semantic Integration Workbench 1. Run the Semantic Connector (First Run) • Performed by: Model Owner • Input: Original UML Model in XMI format [ ${filename}.xmi ] • The first run of the Semantic Connector performs an EVS search for each element in the UML Model and attaches one or more EVS concepts per element. • Output: • Fixed_${filename}.xmi: A cleaned-up version of the original UML Model in XMI format, with EA specific tags removed. This XMI file, still non-annotated is referred to as the “Fixed XMI”. • EVSReport_fixed_${filename}.csv: A file in Comma Separated Values (CSV) format, referred to as the “Semantic Connector Report”. This file should be sent to EVS curation team for review and insertion of new concepts to match the UML class and attribute entities.

21. Using the Semantic Integration Workbench Tips and Tricks • Can’t find the fixed .XMI file or Semantic Connector Report (.CSV file) • Files are created in the same root directory as the input file • Note the location of your .XMI input file • Error message displays or first run does not complete • Confirm your .XMI file is in the expected format • Check .XMI export settings in EA

22. Using the Semantic Integration Workbench 1. Run the Semantic Connector (First Run) • Next Step • Send the Fixed_${filename}.xmi, the EVSReport_fixed_${filename}.csv, the documentation file from EA, and the submission form (via email) to NCICB Application Support (ncicb@pop.nci.nih.gov), include the semantic integration submission form. • NCICB Application Support conducts a cursory review of the files to verify completeness. • EVS concept curation team performs Step 2. Curate Semantic Connector Report.

23. UML Model Diagram - Example

24. Example: Gene Class: Gene Attribute: Id Datatype: String EVS touch points

25. Semantic Integration:Semantic Connector Report – First Try

26. Requesting New Terms from EVS • Look in EVS for possible matches or synonyms. • Submit email request to NCICB Applications Support (ncicb@pop.nci.nih.gov) to request new terms. • Include the following information: • Subject Line: New EVS Terms • Term Name • Term Definition with Source • Submitter Name and Contact Information • Multiple terms may be included in a single email.

27. Using the Semantic Integration Workbench 2. Curate the Semantic Connector Report

28. Using the Semantic Integration Workbench 2. Curate the Semantic Connector Report • Performed by: EVS Concept Curation Team • Note: EVS Concept Curation Team will be in contact with the model owner if they have questions. This process can be iterative. • Input: Semantic Connector Report (First Run) [EVSReport_fixed_${filename}.csv] • During this step, the EVS curation team adds and removes concepts and indicates recommended semantic mappings. In this mode, new or existing EVS concepts can be utilized for annotating the model (by EVS staff only). • Output: • EVSReport_fixed_${filename}.csv: The updated CSV referred to as the “Curated Semantic Connector Report”.

29. Using the Semantic Integration Workbench 3. Run the Semantic Connect (Second Run)

30. Using the Semantic Integration Workbench3. Run the Semantic Connector (Second Run) • Performed by: NCICB Application Support Reviewer • Input: Fixed XMI file [ Fixed_${filename}.xmi ] and Updated Semantic Connector Report [ EVSReport_fixed_${filename}.csv ] • This step updates the Fixed XMI file using the Curated Semantic Connector Report as the basis to insert new concept tags. • Output • Annotated_fixed_${filename}.xmi: A fully annotated XMI document.

31. Using the Semantic Integration Workbench 4. Review the Annotated Model

32. Using the Semantic Integration Workbench 4. Review the Annotated Model • Performed by: Model Owner or Reviewer • Input: Annotated_fixed_${filename}.xmi • During this step, the SIW performs a number of validation checks to ensure the XMI file will be correctly transformed into caDSR metadata. In this mode, users reviewing concept mapping and association details between a specific class or attribute and EVS concept. • Output: • Annotated_fixed_${filename}.xmi: The Annotated Model.

33. Using the Semantic Integration Workbench 4. Review the Annotated Model • Details of the Validation Check • Validate datatypes • Check cardinality • Verify that documentation and descriptions are present for all classes and attributes • Review the concept mappings and approve • No two classes should have identical concept mappings • No two attributes may have the same concept annotations within a class • Naming: • All class names should start with uppercase • All attribute names should start with lowercase • Attribute names should not end in ‘s’ • Attribute name should not start with the class name

34. Using the Semantic Integration Workbench 4. Review the Annotated Model • Details of the Validation Check (cont’d) • Inheritance: • Should not have a child class with an attribute that is also defined in its parent. • Associations: • Should all have a role name • Should all be present, not ‘unspecified’ • If multiplicity >1, the role name should end with ‘Collection’ • Human Verified • Do NOT select if the EVS concept has no definition

35. Using the Semantic Integration Workbench SIW Viewer Window Mapped Concept UML Entities

36. Using the Semantic Integration WorkbenchEditing Annotation Details • Editing with the Same Concept Code • Two concepts with the same concept code must have the same concept name, definition and definition source. • When you change concept properties, the SIW will apply the changes to ALL OTHER UML Elements in the model with that concept code. • Changing the Concept Code • If the concept code is changed, only the edited element is modified.

37. UML Model Metadata • Describe how UML model data elements are organized in the caDSR • Decompose a UML class and its attributes into Data Elements

38. Design System and draw model Run Semantic Connector (First Run) Curate Semantic Connector Report Run Semantic Connector (Second Run) Review Annotated Model Register Metadata (UML Loader) Generate and deploy system (Code Generator) Introduction:SIW and the Semantic Integration Process

39. Decomposing UML Models into caDSR metadata

40. Example: Protein Sequence Molecular Weight Class: Protein Sequence Attribute: Molecular Weight in Daltons Datatype: Primitive Type – Double

41. Example: Protein Sequence Molecular Weight Protein Sequence Molecular_Weight java.lang.Double Protein Sequence Molecular_Weight Class: Protein Sequence Attribute: Molecular Weight in Daltons Datatype: Primitive Type – Double Protein Sequence Molecular_Weight java.lang.Double

42. caDSR Administered Component to UML Entity Mapping

43. caDSR Administered Component to UML Element Mapping

44. Review the Submission Package (caDSR Team) • Prepare UML model load submission package that includes: • final Annotated_fixed_${filename}.xmi file • the EA model and documentation updated after import of the Annotated_fixed_${filename}.xmi • UML Loader submission form. • Open model in Enterprise Architect documentation and verify names, definitions, EVS terms, relationships. • Verify all values have been specified on UML Loader submission form. • Create new generic Value Domains (non-enumerated) based on new data types, if needed.

45. Importing an annotated xmi File into EA • Open original EA model and locate the Logical Model • Move the original model to the Custom folder and rename Old Logical Model

46. Importing an annotated xmi File into EA (cont.) • Highlight Logical View and import the new annotated xmi

47. Importing an annotated xmi File into EA (cont.) • Find the new annotated model under Logical View • Move the diagrams from the Old Logical Model to the new Logical Model folder.

48. caDSR Review and Curation (caDSR Team and Model Developer/Curator) Step 1: • Load Annotated_fixed_${filename}.xmi into the caDSR STAGING environment. • Contact Model owner or Curator to Review for Completeness (names, definitions, alternative names, EVS terms, relationships) • Do NOT curate on Staging. Step 2: • Load Annotated_fixed_${filename}.xmi into the caDSR PRODUCTION environment • Review and curate metadata as needed (i.e. add Value Domains/Permissible Values/Value Meanings and additional Attributes.) • Obtain developer review and approval. • Release Data Elements, Data Element Concepts, and Value Domains.

49. UML Loader Summary • UML Loader registers an alternate name and definition for each data element corresponding to the class and attribute name upon which it is based. E.g • An attribute named “symbol” in “Gene” class of caBIO UML Model will have an alternative name of Gene.symbol • The UML definition can be seen as a alternative definition using the Admin tool • UML loaded Data Elements are Self-harmonizing • At loading time, the UML Loader searches for other Data Elements that are described by the same set of concept codes and datatype • If a matching Data Element is found, the UML Loader designates the existing Data Element and classifies it into the additional Classification Scheme corresponding to the new project • Data Elements from a software project are put into a Classification Scheme corresponding to the project name and version for ease of retrieval • Subsequent versions use the same Data Element (where they exist in both projects) but have additional Classification Scheme/Classification Scheme Items added to the Data Elements

50. Finding UML Model Metadata in the CDE Browser Navigate down the tree structure, into the desired Classification scheme / item. Select the link to search for all data elements in that classification scheme item. Select a Data Element from the list of Search Results. View details about that Data Element by selecting the Long Name.