1. 1 ECCF Training 2.0 Guidance for the Logical Perspective Specification ECCF Training Working Group January 2011

2. 2 Outline Introduction What is the Logical Perspective Specification (LPS) ? Fundamental Artifacts These are basic artifacts that are required at each specification level Examine each specification artifact by RM-ODP (Reference Model of Open Distributed Processing) viewpoint Define the artifacts Link them to the template Provide examples Engage in constructive exercises

3. 3 Remember our Case Study: Molecular Annotation Service: We have defined the CIM. “Conceptually what purpose does this service serve?” Now we want to define the PIM. “What does the data model look like, and how do the capabilities map to interfaces and operations at a high level?”

4. What is the Logical Perspective Specification? Platform Independent Addresses the business functionality and behavior of a service, independent of the technology that implements it. Moves from the analysis model in the CPS (Computational Perspective Specification) to a logical model in the LPS Refines and constrains the functional and behavioral information presented in the CPS Defines in a more structured way the inputs, outputs, pre-conditions, post- conditions, and error messages for each operation Contains a technology-independent specification of the service contract Typically one LPS for one CPS 4

5. Fundamental Artifacts Business service name Service description and purpose Describe the service in general terms and discuss its intended use. Scope Describe the overall scope of the service. Define all functionality that this particular service provides. Referenced standards Provide details and references to the standards that are used in this service. An example would be a service where the domain model is derived from the BRIDG (Bioinformatics Research Integrated Domain Group) model. 5

6. 6 Enterprise Viewpoint Artifacts The primary artifacts generated from the Enterprise Viewpoint in the Logical Perspective Specification include: Refined CPS Enterprise Viewpoint Artifacts: There may or may not be refinements that are made from the CPS to the LPS level. Refined Conformance Statements: Includes a list of all the Conformance profiles from the CPS that this LPS is conformant to. Includes the specific version of the CPS used. Note: Refinements are used to clarify or correct artifacts and conformance statements from the CPS for use in the LPS.

7. Enterprise Viewpoint Artifacts: Relationship to the CPS Provides details on how this specification relates to the Conceptual Perspective Specification Includes the version number and a link to the CPS Example from Molecular Annotation Service: 7 Conceptual Functional Service Specification Name Conceptual Functional Service Specification Version Description & Link to the Conceptual Functional Service Specification Molecular Annotation Conceptual Functional Service Specification 0.1.1http://ncisvn.nci.nih.gov/svn/cabiodb/ECCF/artifacts/con ceptual/CIMSS_Molecular_Annotation_Service.doc

8. Enterprise Viewpoint Artifacts: Conformance Profile Statements which group functional and semantic profiles around a usage context. One or more Functional Profiles – Collection of functionality which this compliance profile will exhibit Exactly one Semantic Profile – The semantics of the input and output parameters which should be used for the functionality mentioned above. The LPS lists all of the Conformance Profiles from the CPS that it is conformant to. The LPS must be conformant to all of the mandatory conformance profiles from the CPS The LPS can add onto the functionality, but cannot remove or modify any functionality from the CPS conformance profile. 8

9. Molecular Annotation Service: Conformance Profile Name LSDAM-based Gene Annotation Conformance Profile Description Defines the functionality for the Gene Annotation Service using LSDAM semantics Usage This profile would be used by a researcher wishing to access gene annotations 9

10. Molecular Annotation Service: Conformance Profile 10

11. 11 Information Viewpoint Artifacts The primary artifacts generated from the Information Viewpoint in the LPS include: Serializable Information Model: Add constraints and localizations to domain analysis work begun in the CPS Primary Information Objects Control Data Types Value Set Definitions

12. Information Viewpoint Artifacts: Primary Information Object Types Criteria: Primary objects represent the main functionality of the service Primary objects are the central objects in the information model to which all other objects are associated. Primary objects generally form the input and output objects for the majority of the service functionality Primary objects generally experience state changes as service functionality is executed. There can be one or several Primary Information Objects for a service Specification: Object Model (UML, RMIM) Relationship to referenced models 12

13. Molecular Annotation Service: Primary Information Object The Gene class meets the criteria outlined: The service is designed to allow retrieval Genes and various annotations related to a Gene. The Gene object is the central object. It has associations such as MolecularFunction, CellularComponent, BiologicalProcess, and GeneSearchCriteria Genes (or Gene Identifiers) serve as either the input or the output of nearly every service operation. 13

14. Molecular Annotation Service: Gene Model This is a UML model from the Molecular Annotation Service Logical Perspective Specification. It shows the Gene class, its closest associations and their attributes. 14

15. Molecular Annotation Service: Gene Model Relationship to LSDAM The Molecular Annotation Service LPS includes a diagram and a table relating the Gene model back to classes in the LSDAM Mapping is one-to-one except for additional attributes on Gene and NucleicAcidSequenceFeature 15

16. Molecular Annotation Service: Gene Model Relationship to LSDAM 16

17. Molecular Annotation Service: Gene Model Relationship to LSDAM TraceAttribute NameTypeDescription LSDAMSymbolSTThe official symbol for the gene based on an organism-specific database of gene symbols, such as HUGO, MGI or RGD NewfullNameSTThe title of the gene. 17 Gene

18. Information Viewpoint Artifacts: Control Data Type Definitions Control data types are classes used by the service for input and output that are created specifically to perform certain service actions. Examples of common control data types: Exception Types Search Criteria Input Criteria Result Sets Specification of control data types should include: UML diagrams of the types and hierarchies Data type descriptions 18

19. Molecular Annotation Service: MAException UML diagram: 19

20. Molecular Annotation Service: MAException Data TypeStatus / Return Value / Exception Data Type Description MAExceptionExceptionException thrown when there is an error in the operation of MA Service methods. Date type description: 20

21. Molecular Annotation Service: Search Criteria UML Diagram: 21

22. Molecular Annotation Service: Search Criteria Data Type Descriptions: 22 Data TypeQuery Search Criteria / Search Result Limiter / Result Set Data Type Description GeneSearchCriteriaQuery Search CriteriaSearch criteria object for finding genes of interest given a single symbol or alias. GeneListSearchCriteriaQuery Search CriteriaSearch criteria object for finding genes of interest given a list of symbols or aliases. ReporterSearchCriteriaQuery Search CriteriaSearch criteria object for finding genes of interest given a reporter name.

23. Information Viewpoint Artifacts: Value Set Definitions Attributes whose values are controlled by a list of valid values Error Codes Status Codes These can be values for attributes on project specific data types, or additional constraints placed on referenced data types. 23

24. Molecular Annotation Service: Error Codes Error CodeError ConditionDescription MAE00000FatalRemote system error MAE10001ErrorGene does not exist MAE10002ErrorSpecified microarray is not supported MAE10003ErrorReporter not found 24

25. Information Viewpoint Exercise: Primary Information Objects Given the following capabilities from the Subject Registration service, identify at least one primary information object. 25 CapabilityDescription Initiate Subject Enrollment This capability is used to initiate subject registration on a study. Reserve Slot This capability is used to reserve a slot for the subject on a trial. Pre-Register Subject This capability is used to pre-register subject on a trial. Some trials mandate a screening of a subject before they can be accrued to the study. Enroll Subject This capability is used to enroll subject on trial. At this point the subject can be deemed enrolled on the trial and they would be counted towards the accrual.

26. Information Viewpoint Exercise: Model Constraints Scenario: As an architect of the Service Registration service you are designing the serializable information model. The following information needs to be captured for subjects of a study: Biographical information: name, date of birth, gender, primary race, primary ethnicity, telephone number, and address Study Registration information: subject status and status change date & time Your Conceptual Perspective Specification used the following StudySubject object from the BRIDG domain analysis model. Constrain the object to meet the requirements outlined above. 26

27. Information Viewpoint Exercise: Model Constraints (cont.) 27

28. Information Viewpoint Exercise: Control Data Types Given the following capabilities from the Subject Registration service, identify any control data types that may be necessary: 28 CapabilityDescription Query Subject Registration This capability is used to query and retrieve subject registration data including demography data. This also provides the capability to query epoch specific data, for e.g. it can be used to provide data on how many people were screened and how many failed screening for each possible reason. Import RegistrationsThis capability is used to import legacy registrations. Generate Summary3 Report This capability is used to generate Summary 3 report.

29. 29 Behavioral Viewpoint PIM Artifacts The primary artifacts generated from the Behavioral Viewpoint at the PIM specification include: State Model: State should be expressed for important objects relevant to the service specification. Service Contract: Platform Independent service interfaces. Provides a logical grouping of service capabilities. Interface model List of operations for each interface Detailed operation behavior descriptions Dynamic Model: Model of complex internal and external relationships and interactions.

30. Behavioral Viewpoint Artifacts: State Model Include the UML model describing the state transitions of the primary information object(s) of the service. Provide details on the state transitions and discuss any significant implementation considerations based on entity states. Molecular Annotation Service Example: Current service is essentially an open, read-only service. Queries are executed against the service to retrieve results. As such, the only state that a Gene can be in is “Active”. 30

31. Behavioral Viewpoint Artifacts: Interface Model Related service operations may be grouped into interfaces to a provide a logical grouping for service implementers. This grouping may be different than the functional profiles. Specification: Interface Model UML Interface description table Molecular Annotation Service: Interface Description Table 31 Interface NoInterface NameInterface Description MA-INF1MAGeneAnnotationQueryIncludes all of the operations for retrieving gene annotations MA-INF2MAFreestyleSearchIncludes all of the operations for Freestyle Search

32. Molecular Annotation Service: Interface Model UML 32

33. Behavioral Viewpoint Artifacts: List of Operations List the operations for each interface Molecular Annotation Service: List of Operations (Truncated) 33 Operation No. Operation NameInterface NameOperation Description MA-INF1-OP1getGenesBySymbolMAGeneAnnotationQueryReturns the genes named by the specified gene symbols and/or gene aliases MA-INF1-OP2getCellularLocationsMAGeneAnnotationQueryReturns annotations describing a gene’s location within a cell MA-INF2-OP1freestyleSummarySearchMAFreestyleSearchProfileReturns a summary result for a given keyword or keywords MA-INF2-OP2freestyleSearchMAFreestyleSearchProfileReturns a list of results matching the given keyword or keywords

34. Behavioral Viewpoint Artifacts: Operation Behavior Descriptions Detailed description of the behavior of each interface operation Includes the following information: Behavior Description Textual description of the operation behavior and business logic Pre-Conditions Any pre-conditions necessary for invoking this operation Security Conditions Describe in detail the security constraints which the user needs to fulfill in order to execute this operation Inputs Provide details of the inputs required to invoke this operation. Indicate if the input is mandatory or optional. Outputs Details of the operation outputs. 34

35. Behavioral Viewpoint Artifacts: Operation Behavior Descriptions Included information (cont.): Post-Conditions Describe the details of the system state after the operation has been successfully executed. Exception Conditions List and describe any exception conditions for this operation with common error codes where applicable. Additional Implementation Details Notes Any additional notes dealing restrictions to the operation and its relation to other operations in the service. 35

36. Molecular Annotation Service: Operation Behavior Description Behavior DescriptionClient supplies a ReporterSearchCriteria instance with a reporter name and a microarray design as search criteria The case of the reporter name is ignored If the Microarray is null then all Microarrays are searched The system returns the matching Gene object(s), if any Pre-ConditionsNone Security Pre- Conditions None InputsReporterSearchCriteria OutputsFully-populated instance(s) of Gene getGenesByMicroArrayReporter 36

37. Molecular Annotation Service: Operation Behavior Description Post-ConditionsNone Alternate ConditionsNo matching genes found Exception ConditionsSpecified microarray is not supported Reporter not found Additional DetailsNone NotesNone getGenesByMicroArrayReporter (cont.): 37

38. Behavioral Viewpoint Artifacts: Dynamic Model Includes the descriptions of the interactions of the service. Sequence diagrams describing significant interactions with the service. Relationships to external services. Molecular Annotation Service: External Service Relationships 38 Service / System / Actor’s Name RelationshipDataDescription Integrative Translational Research System DependsMolecular Annotations Integrative Translational Research Systems such as caIntegrator depend on Molecular Annotations for looking up annotations for microarray reporters used in experiments being analyzed. Gene Expression Analysis Tool DependsMolecular Annotations Gene Expression Analysis Tools such as GEWorkbench depend on a Molecular Annotations for putting expression data in context of a genome.

39. Behavioral Viewpoint Exercise: State Model Given the following operations and states, diagram a basic state model for the Subject Registration service: 39 Operations: initiateSubjectEnrollment preRegisterSubject reserveSlot failSubjectScreening enrollSubject takeSubjectOffStudy States: Candidate Pending Reserved Pending On-Study On Study Off Study

40. Behavioral Viewpoint Exercise: Interface Model Given the following Service Registration Interfaces, match the operations with the most appropriate interface. Interfaces: SRManagementBase - Provides the functionality common to both the registering site as well as coordinating center. SRQuery - Provides the functionality to query subject registration SRManagementSite - Provides the functionality available to the Site Registrar at the registering site SRReporting - Provides the functionality available to the Study Registrar (as well as other approved personnel) at the Study Coordinating center. Operations: querySubjectRegistration retrieveAccrualData initiateSubjectRegistration updateSubjectRegistration 40

41. Behavioral Viewpoint Exercise: Operation Behavior Description For the following Subject Registration Service Operation, detail possible pre-conditions, security conditions, post-conditions, and exception conditions initiateSubjectEnrollment Description: This functionality is invoked by the client to initiate subject enrollment. Clients can provide consent correspondence data like consent delivery, consent presenter etc to begin the enrollment process. Inputs: BiologicEntityIdentifier [M] DocumentIdentifier (study identifier) [M] OrganizationIdentifier (registering site identifier) [M] StudySubject including the following: DSET [M] ScheduledEpoch [O] Outputs: StudySubject 41

42. 42 Deployment Viewpoint Artifacts The primary artifacts generated from the Deployment Viewpoint at the LPS include: Deployment Model: Platform Independent deployment consideration and plans List deployment scenarios for this service. Provide deployment guidelines for the service implementers.

43. Other Mandatory Artifacts Conformance Statements Testable and verifiable statements made in the context of a single viewpoint. References Table identifying the sources used to create the specification Glossary Citation of terms specific to this specification and not included in the overall CBIIT Glossary Interface to profile mapping The mapping of the Interfaces from the LPS to the corresponding profiles in the CPS. Interface operations to profile capabilities The mapping of the operations of the interfaces to the corresponding profile capabilities from the CPS. 43

44. Molecular Annotation Service: Conformance Statements (subset) #NameTypeViewpointDescriptionTest Method 1Query Performance ObligationEng.The MA service should provide a response within 0.5 seconds to support a synchronous UI based client Test cases to include performance testing 2Semantic Model ObligationInf.The MA service must provide traceability to classes in the LS PIM as identified in section 2.3 Design review 3Data TypesObligationInf.The MA service must conform to NCI’s constrained list of ISO 21090 data types. Design review 4Functional Profiles ObligationComp.Functional Profiles shall be deployed as functional wholes. Ignoring or omitting functional behavior defined within a functional profile is not permitted, nor is diverging from the detailed functional specifications provided in Section 5. Design review & test cases 44

45. Molecular Annotation Service: Interface to Profile Mapping Interface No.InterfaceProfile No.Profile MA-INF1MAGeneAnnotationQueryMA-FP1Gene Annotation Query Profile MA-INF2MAFreestyleSearchMA-FP2Freestyle Search Profile 45

46. Molecular Annotation Service: Operation to Capability Mapping Operation No. Operation NameCapability No. Profile Capability MA-INF1-OP1getGenesBySymbolMA-CPB1Get Genes By Symbol or Alias MA-INF1-OP2getGenesByMicroarrayReporte r MA-CPB2Get Genes By Microarray Reporter MA-INF2-OP1freestyleSummarySearchMA-CPB10Freestyle Summary Search MA-INF2-OP1freestyleSearchMA-CPB11Freestyle Search 46

47. Logical Perspective Specification Summary Enterprise Viewpoint Relationship to CPS Refine conformance statements from CPS Information Viewpoint Further constrains and localizes the CPS information model to meet the needs of the current project. Details primary objects as well as control data types Behavioral Viewpoint Formalized Service Contract Logically group operations into interfaces Detailed descriptions of service operations Deployment Viewpoint Deployment Considerations 47

48. References Molecular Annotation Service PIM: https://ncisvn.nci.nih.gov/svn/cabiodb/ECCF/artifacts/logical/PIMSS_Molecular_Ann otation_Service.dochttps://ncisvn.nci.nih.gov/svn/cabiodb/ECCF/artifacts/logical/PIMSS_Molecular_Ann otation_Service.doc Service Registration Service PIM: https://ncisvn.nci.nih.gov/svn/c3pr/trunk/c3prv2/documentation/design/essn/Subject Registration/PIMSS_Subject_Registration_Service.dochttps://ncisvn.nci.nih.gov/svn/c3pr/trunk/c3prv2/documentation/design/essn/Subject Registration/PIMSS_Subject_Registration_Service.doc caBIG PIM Service Specification Template: http://gforge.nci.nih.gov/svnroot/candc/trunk/documents/artifact_templates/logical/c aBIG_Platform_Independent_Model_Template.dochttp://gforge.nci.nih.gov/svnroot/candc/trunk/documents/artifact_templates/logical/c aBIG_Platform_Independent_Model_Template.doc CBIIT SAIF Implentation Guide (16-Dec-2010 version): https://wiki.nci.nih.gov/download/attachments/33401213/16Dec2010SAIFIG.pdf?ver sion=1&modificationDate=1292539920000https://wiki.nci.nih.gov/download/attachments/33401213/16Dec2010SAIFIG.pdf?ver sion=1&modificationDate=1292539920000 48