Date post: | 05-Jan-2016 |
Category: |
Documents |
Upload: | bonnie-alexander |
View: | 217 times |
Download: | 0 times |
1
ECCF Training 2.0
Guidance for the
Logical Perspective Specification
ECCF Training Working Group
January 2011
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
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 (Conceptual 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
3
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.
4
5
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.
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:
6
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.1 http://ncisvn.nci.nih.gov/svn/cabiodb/ECCF/artifacts/conceptual/CIMSS_Molecular_Annotation_Service.doc
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.
7
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
8
Molecular Annotation Service:Conformance Profile
9
10
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
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
11
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.
12
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.
13
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
14
Molecular Annotation Service:Gene Model Relationship to LSDAM
15
Molecular Annotation Service:Gene Model Relationship to LSDAM
Trace Attribute Name Type Description
LSDAM Symbol ST The official symbol for the gene based on an organism-specific database of gene symbols, such as HUGO, MGI or RGD
New fullName ST The title of the gene.
16
Gene
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
17
Molecular Annotation Service:MAException
• UML diagram:
18
Molecular Annotation Service:MAException
Data Type Status / Return Value / Exception
Data Type Description
MAException Exception Exception thrown when there is an error in the operation of MA Service methods.
• Date type description:
19
Molecular Annotation Service:Search Criteria
• UML Diagram:
20
Molecular Annotation Service:Search Criteria
• Data Type Descriptions:
21
Data Type Query Search Criteria / Search Result Limiter / Result Set
Data Type Description
GeneSearchCriteria Query Search Criteria Search criteria object for finding genes of interest given a single symbol or alias.
GeneListSearchCriteria Query Search Criteria Search criteria object for finding genes of interest given a list of symbols or aliases.
ReporterSearchCriteria Query Search Criteria Search criteria object for finding genes of interest given a reporter name.
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.
22
Molecular Annotation Service:Error Codes
Error Code Error Condition Description
MAE00000 Fatal Remote system error
MAE10001 Error Gene does not exist
MAE10002 Error Specified microarray is not supported
MAE10003 Error Reporter not found
23
Information Viewpoint Exercise:Primary Information Objects
• Given the following capabilities from the Subject Registration service, identify at least one primary information object.
24
Capability Description
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.
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.
25
Information Viewpoint Exercise:Model Constraints (cont.)
26
Information Viewpoint Exercise:Model Constraints (cont.)
27
CD
CD
TS.DATE
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
Capability Description
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 Registrations This capability is used to import legacy registrations.
Generate Summary3 Report
This capability is used to generate Summary 3 report.
Information Viewpoint Exercise:Control Data Types (cont.)
29
Capability Possible Control Data Types
Query Subject Registration
• Input - Search criteria type
• Output - Exception type
• Output -Result set type
Import Registrations • Input - Specific import format type
• Output – Exception type
Generate Summary3 Report
• Input – Report parameter type
• Output – Report format type
• Output – Exception type
30
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.
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”.
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
32
Interface No Interface Name Interface Description
MA-INF1 MAGeneAnnotationQuery Includes all of the operations for retrieving gene annotations
MA-INF2 MAFreestyleSearch Includes all of the operations for Freestyle Search
Molecular Annotation Service:Interface Model UML
33
Behavioral Viewpoint Artifacts:List of Operations
• List the operations for each interface
• Molecular Annotation Service: List of Operations (Truncated)
34
Operation No.
Operation Name Interface Name Operation Description
MA-INF1-OP1 getGenesBySymbol MAGeneAnnotationQuery Returns the genes named by the specified gene symbols and/or gene aliases
MA-INF1-OP2 getCellularLocations MAGeneAnnotationQuery Returns annotations describing a gene’s location within a cell
MA-INF2-OP1 freestyleSummarySearch MAFreestyleSearchProfile Returns a summary result for a given keyword or keywords
MA-INF2-OP2 freestyleSearch MAFreestyleSearchProfile Returns a list of results matching the given keyword or keywords
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.
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.
36
Molecular Annotation Service:Operation Behavior Description
Behavior Description • Client 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-Conditions None
Security Pre-Conditions
None
Inputs ReporterSearchCriteria
Outputs Fully-populated instance(s) of Gene
• getGenesByMicroArrayReporter
37
Molecular Annotation Service:Operation Behavior Description
Post-Conditions None
Alternate Conditions No matching genes found
Exception Conditions • Specified microarray is not supported• Reporter not found
Additional Details None
Notes None
• getGenesByMicroArrayReporter (cont.):
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
39
Service / System / Actor’s Name
Relationship Data Description
Integrative Translational Research System
Depends Molecular 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
Depends Molecular Annotations
Gene Expression Analysis Tools such as GEWorkbench depend on a Molecular Annotations for putting expression data in context of a genome.
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
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 <StudySubjectConsentVersion> [M]
• ScheduledEpoch [O]
• Outputs:• StudySubject
41
Behavioral Viewpoint Exercise:Operation Behavior Description
42
Behavioral Viewpoint Exercise:Operation Behavior Description
43
44
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.
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.
45
Molecular Annotation Service:Conformance Statements (subset)
# Name Type Viewpoint Description Test Method
1 Query Performance
Obligation Eng. The MA service should provide a response within 0.5 seconds to support a synchronous UI based client
Test cases to include performance testing
2 Semantic Model
Obligation Inf. The MA service must provide traceability to classes in the LS PIM as identified in section 2.3
Design review
3 Data Types Obligation Inf. The MA service must conform to NCI’s constrained list of ISO 21090 data types.
Design review
4 Functional Profiles
Obligation Comp. 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
46
Molecular Annotation Service:Interface to Profile Mapping
Interface No. Interface Profile No. Profile
MA-INF1 MAGeneAnnotationQuery MA-FP1 Gene Annotation Query Profile
MA-INF2 MAFreestyleSearch MA-FP2 Freestyle Search Profile
47
Molecular Annotation Service:Operation to Capability Mapping
Operation No.
Operation Name Capability No.
Profile Capability
MA-INF1-OP1 getGenesBySymbol MA-CPB1 Get Genes By Symbol or Alias
MA-INF1-OP2 getGenesByMicroarrayReporter MA-CPB2 Get Genes By Microarray Reporter
MA-INF2-OP1 freestyleSummarySearch MA-CPB10 Freestyle Summary Search
MA-INF2-OP1 freestyleSearch MA-CPB11 Freestyle Search
48
Logical Perspective SpecificationSummary
• 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
49
References
• Molecular Annotation Service PIM: • https://ncisvn.nci.nih.gov/svn/cabiodb/ECCF/artifacts/logical/
PIMSS_Molecular_Annotation_Service.doc
• Service Registration Service PIM:• https://ncisvn.nci.nih.gov/svn/c3pr/trunk/c3prv2/documentation/design/essn/
SubjectRegistration/PIMSS_Subject_Registration_Service.doc
• caBIG PIM Service Specification Template:• http://gforge.nci.nih.gov/svnroot/candc/trunk/documents/artifact_templates/logical/
caBIG_Platform_Independent_Model_Template.doc
• CBIIT SAIF Implentation Guide (16-Dec-2010 version):• https://wiki.nci.nih.gov/download/attachments/33401213/16Dec2010SAIFIG.pdf?
version=1&modificationDate=1292539920000
50