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