UML Model Development and Registration – Some Things You May not Know

1. UML Model Development and Registration – Some Things You May not Know Session Date: May 4, 2005 Session Length: 30 Minutes Target Audience: TBPT Modelers Trainer: Tommie Curtis curtist@mail.nih.gov NCICB Liaison / Expert Curator: Dianne Reeves reevesd@mail.nih.gov

3. Skills Every Modeler Should Have • Identify best practices for model/metadata creation • Recognize well-formed names and definitions • Understand the Semantic Connector process • Prepare information for UML Loader registration • Identify where UML model metadata is being registered in the caDSR • Create Value Domains and Permissible Values • Create Comments, Reference Documents, and Related URLs • Review registered UML metadata • Approve UML registration to production environment • Update the model as it changes

4. Object Agent Valid Values (where relevant) Data Element Concept Agent NSCNumber Value Domain java.lang.Integer Property NSCNumber Representation Code Data Element N Semantic Integration • UML Class = ISO Object Class • Example: Agent • ISO Object Classes are mapped to 1 or more concepts from EVS • UML Class Attribute = ISO Property • Example: nSCNumber • ISO Properties are mapped to 1 or more concepts from EVS • UML Class + UML Class Attribute = ISO Data Element Concept • Agent:nSCNumber • ISO DEC’s are mapped to 2 or more concepts (from OC + Property) • UML (Java) Datatype = ISO Value Domain (at least initially) • Example: java.lang.Integer • Enumerated value domains curated after initial UML loading • UML Class + UML Class Attribute + Datatype/Valid Values = ISO Common Data Element • Example: Agent:nSCNumber: java.lang.Integer

5. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

6. Resources – UML Model Creation • Time Estimate • Varies with understanding of UML modeling and modeling tools • Varies with complexity of the data being modeled • People • Model Owner • VCDE Workspace Mentor • NCICB UML Loading Staff • EVS Staff

7. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

8. Generating XMI for Semantic Interoperability • Requirements for XMI file: • XMI 1.1 • UML 1.3 • Unisys/Rose extensions • Export tagged values • Include “Logical Model” package • Exclude diagrams

9. Running the Semantic Connector • If you know terms/concepts that you will need at not currently in the EVS vocabulary, submit a request to EVS for the addition of the terms prior to running the Semantic Connector. • Send an email to NCICB@pop.nic.nih.gov with the terms and definitions. • Include “Terms for EVS” in the subject line. • Submit the annotated XMI file to NCICB: • To NCICB@pop.nci.nih.gov • Include “For semantic connection” in the subject line • Your model will be run through the Semantic Connector • A semantic connector report will be generated • Comma-separated file (CSV) • Relates terms from diagram to EVS concepts • Report will be curated, verified and sent to you for approval and submission for loading

10. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

11. Semantic Connector Tasks Automated Steps • Match UMLEntity to NCI Thesaurus concept preferred name or synonym • Divide UMLEntity into space-separated terms at the CamelCase separators – repeat match to NCI Thesaurus preferred name or synonym • Return match(es) in comma-delimited file • Update of XMI with annotation terms Non-automated Steps • Addition of new EVS terms/concepts • Review and selection of terms for model annotation

12. Semantic Connector: Report Semantic Connector Report BEFORE Human Verification

13. Semantic Connector: Report UMLEntities lacking UMLDescription

14. Semantic Connector: Report Are the UMLEntity and UMLDescription are consistent with each other? Do they match “common meaning”?

15. Semantic Connector: Report Multiple matches for one UMLEntity

16. Semantic Connector: Report Semantic Connector Report AFTER Human Verification – Step 1

17. Semantic Connector: Report Semantic Connector Report AFTER Human Verification – Step 2

18. Problems and Pitfalls • The needed terms are not registered in NCI Thesaurus • Multiple matches are found for a single term • UML Model is changing during the review process • Model requires multiple passes through the Semantic Connector

19. Resources – Semantic Annotation of UML Models • Time Estimate • Effected by the availability of terms/concepts in EVS – may need multiple cycles if the terms are initially available • Increased by model changes • Requires training in understanding the Semantic Connector reports • People • Model Owner • EVS Reviewer • VCDE Workspace Mentor

20. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

21. Content of the UML Loader Package • UML Loader Submission Form • Classification Scheme (Project Name) with brief description • Version Number • UML Package(s) Alias and Relationships • Context for Loading • Workflow Status • Datatypes Used in Model • Annotated XMI (terms from the Semantic Connector have been added to the XMI) • Final Semantic Connector Report • Point of Contact Name, Email, and Telephone Number * Required information

22. Submit the Model for UML Loading • Submit the annotated XMI file to NCICB: • To NCICB@pop.nci.nih.gov • Include “For UML Loading” in the subject line

23. Running the UML Loader • Your model will be loaded by NCICB staff using the UML Loader • The load process will be verified by NCICB staff • You will receive an email requesting you to review the load in the Stage environment

24. Resources – UML Loading • Time Estimate • Effected by completeness of UML Load Package and availability of the Point of Contact • People • Model Owner • NCICB UML Loading Staff

25. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Prepare Submission Package • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

26. Steps for UML Model Review and Curation • Access into Stage for initial review • Address questions to NCICB staff/VCDE Workspace Mentor • Approve model load in Stage • Load into Production for curation of additional metadata • Review final metadata in Production • Release for public use

27. Staging Review – Is everything in the model registered? Visible with current tools • Object Classes (SDK, p. 84) • Are all Classes represented by Object terms? • Data Element Concepts (SDK, p 29, 112) • Are all Class/Attribute pairs represented by DECs? • Do all DECs have Object Classes and related EVS term CUIs? • Data Elements (SDK, p. 55, 113) • Are all Attributes in the model registered? • Are there Attributes that are not in the model registered? • Naming and Definitions (SDK, p. 112 – 113) • Are Alternate, Preferred, and Long Name formatted correctly? • Do all Objects, Data Element Concepts and Data Elements have Alternate Definitions? • Datatypes (SDK, p. 55) • Does the Representation term in the Data Element match the datatype in the model?

28. Staging Review – Is everything in the model registered? Not visible with current tools. • Relationships (SDK, p. 58) • Are all Associations and Generalization (or Inheritance) relationships represented correctly? • Specification of Multiplicities (SDK, p. 30, 117) • Are all instances recorded correctly? • Direction (SDK, p. 30) • Are all directional associations specified as entered in the model? • Role Names for Associations between Classes (SDK, p. 59) • Are Roles named correctly?

29. Problems and Pitfalls • Model Classes/Attributes not registered in caDSR • Missing from submitted model • Not entered in model correctly • Semantic information not recorded in XMI file • caDSR has Classes/Attributes not seen in model • Inconsistent naming • Should not have been exported in XMI file • Missing Definitions • Missing Objects, Properties, and/or Representations • Improper Datatypes • Used Datatype not registered in caDSR • Wrong Datatype selected during registration

30. Finding the Metadata

31. Admin Tool Search for Object Class

32. Object Class Search

33. Resources – UML Model Review • Time Estimate • Varies with complexity of model • Requires training in usage of tools • People • Model Owner • Curator • NCICB UML Loading Staff • VCDE Workspace Mentor

34. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

35. Content of the Submission Package • UML Model File (EA Preferred), include diagram • Final Semantic Connector Report • Enumerated Permissible Value Lists with Value Meanings • Point of Contact Name, Email, and Telephone Number • Data Dictionary • User Documentation * Minimum required information

36. Steps for Curation • Replace initial Value Domains with enumerated Value Domains as needed • Add Explanatory Comments • Associate Reference Documents, Files, or URLs

37. Problems and Pitfalls • Generic value domains are assigned during registration • Supplemental materials for permissible values not available • Datatypes are not available, mapping or addition of new types may be needed before curation • List of values may be entered or referenced

38. Adding Supplemental Information • Requires Manual Curation using the Admin Tool • Comments • Reference Documents • Related URL’s

39. Resources – Manual Curation of Additional Metadata • Time Estimate • Varies with the number of items to be entered • Includes time for changes and corrections • Depends of availability of supporting information • Requires training in usage of curation tools • People • Model Owner • Curator • QA Reviewer • VCDE Mentor

40. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

41. Final Production Review – Is everything in the model registered? • Review 2-4 Classes and Attributes to ensure correct registration • Check all editorial changes to verify correct completion • Review all new Value Domains and Permissible Values • Ensure that the model displays in the Browser tree • Notify caDSR team of acceptance of the model registration

42. Problems and Pitfalls • The model may not have transferred correctly from Stage to Production • Editorial changes may not have been made or were made incorrectly • New Value Domains may not have been correctly created • Permissible Values may be missing or incorrectly assigned

43. Resources – Model Owner Approval • Time Estimate • Varies with complexity of model • Requires training in the usage of tools • People • Model Owner • NCICB UML Loading Staff • Curator • QA Reviewer • VCDE Mentor

44. UML Model Creation, Registration, and Curation • Create Model • Run Semantic Connector • Semantic Annotation of UML Models • Run UML Loader • Review Stage/Production Registration • Curate Additional Metadata • Model Owner Approval • Model Maintenance and Versioning

45. Resources – UML Maintenance • Time Estimate • Varies with frequency and complexity of model change • People • Model Owner • EVS staff • NCICB UML Loading staff • VCDE Workspace Mentor • Curator

46. Thank you to various team members who contributed to this presentation Overview - George Komatsoulis UML Model Creation - Nafis Zebarjadi Semantic Connector Review – Nicole Thomas UML Loader - Ram Chilukuri Data Review and Curation – Brenda Maeske

47. Questions?