January 19, 2009
Version 0.0.3
Proposed Service Description Construct Template
HITSP/SDxxx
Submitted to:
Healthcare Information Technology Standards Panel
Submitted by:
HITSP Staff
DOCUMENT CHANGE HISTORY
Version Number / Description of Change / Name of Author / Date Published /0.0.1 / Initial Draft / Framework Review WG / December 27, 2008
0.0.2 / Revised Draft / Framework Review WG / January 6, 2009
0.0.3 / Revised Draft / Framework Review WG / January 19, 2009
COPYRIGHT NOTICE
© 2008 ANSI. This material may be copied without permission from ANSI only if and to the extent that the text is not altered in any fashion and ANSI’s copyright is clearly noted.
Include copyright statements only for those citations that rise to the level of requiring one, i.e., the document replicates a lot of content from the source specifications. Typically, the minimal citations within HITSP constructs do not require individual copyrights and a general copyright attribution can be made. Example: All other cited materials are copyrighted by their respective organizations, and used here by kind permission of their owners. (ANSI’s lawyers should weigh in on this)
Table of Contents
1.0 Introduction 5
1.1 Abstract 7
1.2 Source 7
1.3 Classification and Categorization 7
2.0 Functional DescriptioN 8
2.1 Commissioning/consumer Actor and Service Provider Interaction 8
2.2 Core Operation 8
2.3 Scenario(s) 8
2.4 Context for Use (e.g., framework) 8
2.4.1 Assumptions. 8
2.4.2 Dependencies 9
2.4.3 Pre-conditions 9
2.4.4 Triggers 9
2.4.5 Post-conditions 9
3.0 Dynamic Behaviors (Interactions/exchanges) 10
3.1 Semantic Content Requirements (Data elements and structure) 10
4.0 Implementation Model(s) 11
4.1 Mapping of Actors (see Table 3.2.3-1 from IS01) 11
4.2 Interaction Patterns Implementation 11
4.2.1 Input 11
4.2.2 Output 11
5.0 Technical Implementation(s) 12
5.1 Overview 12
5.2 Rules for Implementing 12
6.0 Conformance 13
7.0 Standards 14
8.0 Reference Documents 15
9.0 Document Update 16
9.1 January 19, 2009 16
Figures and Tables
Figure 1.2-1 Lorem ipsum… 3
Table 1.4-1 Reference Documents 3
Table 2.1.2-1 Lorem ipsum… 3
Text highlighted in this manner is proposed explanatory text for authors.
Text that has a green background are my notes, observations and recommendations (some of which I gleaned from the participants on the call. In any event, it is text to be removed from any final template.
1.0 Introduction
HITSP Philosophy Applied to Service Constructs
The goal of HITSP is to adopt a service definition wherever possible, but it also recognizes that in the context of a Use Case, there may be a need and opportunity to describe a proto-service that is an aggregation of previously defined Transactions and/or Transaction Packages[1].
The Service Definition Construct must support both types of descriptions.
Recommend: Within the context of the HITSP documentation and integration of service concepts with non-service-oriented transactions and transaction packages, the following working definitions/philosophies be followed:
· A Service definition for HITS is a “black box” – an encapsulated set of actions that upon the receipt and processing of appropriately supplied information (data elements and constraints on same) can deliver a consistent and repeatable outcome or set of outcomes, also explicitly defined.
· A service is a re-usable conceptual activity such as subject discovery, scheduling, etc. (actual categorizations TBD)
· The internal logic of the service may or may not be expressed or be defined at all provided the result(s) of the service are conformant to all applicable specifications, e.g., an ordering service need not describe how it accesses and resolves disparate source calendar formats, only that the result is conformant to .ics standard.
· Defines a contract in the sense that the initiator of a service accepts the responsibility and accountability for the proper use of any service; likewise, the consumer of the result of a service accepts the results for the specific purposes of the service and does not impute new semantics on the content. In this regard, the service requester, service provider, and service consumer all acknowledge and accept strict adherence to the intended service results as provided by this specification.
· An interface describes the data requirements to be satisfied by the initiator(s)/requestor(s) of the service, as well as the results.
· Core interface data requirements are to be articulated in the HITSP Service Construct, additional constraints may be applied by one or more contexts.
· A service may be a consumer of other services external to themselves.
Recommend a Service Definition is a minimal Construct that:
· Does not have to be as completely self-describing as the underlying standard itself, only those constraints defined by HITSP need be specified.
o EXAMPLE: a service definition that would encompass the act the providing registry data to a repository would have the specific metadata values, not a reference to another HITSP construct.
· Describes the Service Interface Data Requirements, that is, the data elements and constraints required for the service to be executed.
o This is NOT the definition of any content requirements that may be packaged and presented to the service for processing (the payload)
o It is the envelope data and mailing requirements (business rules of use) of the postal service, not the letter in the envelope.
· Describes the nature of the service to the extent necessary for the unambiguous definition of data element requirements for input and output to enable semantic exchange of content required by the service to fulfill its function (regardless of ultimate transportation and transmission methodology.
· Describes one or more reference implementation designs that illustrate how a service can or should be platform bound or implemented – how normative or prescriptive for HITSP in this area is TBD.
o Where reference implementations are identified, detailed constraints may be required where the underlying implementation is unspecified, i.e., formats for timestamps within a WSDL or message must be stated, especially in instances where such values may be derived from the payload content.
Recommend that each service be independently described in a separate Service Contract/Definition Construct. An aggregation of services may be an interesting catalog, but is not necessarily implementer friendly or useful.
Recommend collapsing any set of functions into a service when it can be demonstrated that two or more functions are never used independently (or where interoperability is not an issue within the “black box” of the service).
Recommend each service be an entry in a registry for version tracking and reuse[2], then it may be more appropriate to have only the bare minimum of information described in this document, and the full details in the registered object definitions in the DB (most likely to be a repository of XML objects, one for each sub-service, containing the necessary sections and details that can be published in multiple formats.)
Recommendation Uniquely ID and register each service with an OID
· Each new version has a new OID, a registry will allow one to look up and understand each specific instance of a service. Any ancestry tracking requirements?
1.1 Abstract
The first entry in the introduction should be a named division called <abstract> This is the short description of the service that will form the basic entry in derived catalogs, web sties, etc. The abstract should describe the function, type of input and potential output(s) of the service without the details, just enough for one to understand whether the service is potentially of value.</abstract>
1.2 Source
Citation of the selected service definition; if new HITSP artifact, then attribution is the selected standards invoked by the Construct to function as a black box.
1.3 Classification and Categorization
The selected service definitions classification is noted here if drawn from an architecture that declares service categories and or classification schemes. It the service definition is a new HITSP artifact, then HITSP can choose to select a temporary categorization.
The actual classification scheme is less important in that such classifications are an aspect of a service, and as such should be known by HITSP. HITSP has yet to decide on any given SOA movement as the single such architecture for the US realm.
2.0 Functional DescriptioN
2.1 Commissioning/consumer Actor and Service Provider Interaction
This is the WHO section
Recommend: For HITSP, the interface be thought of as two dimensional so not sure what the service needs to say about the possible range of consumers of the service; constraints on usage of a service are specified by an IS)
Observation: Interactions are relative to a specific Mode or Reference Implementation and this section should be a subsection of either or both of those sections.
Observation: An interface may have multiple business actors supply information for the proper execution of the service. The provisioning and coordination of the actions and actors involved is outside of HITSPs scope except where explicitly requested by the accepted Use Case or is embedded in the source specification.
2.2 Core Operation
This is the core WHAT section
Recommend using simple, direct text – if one provides X, Y, and Z, then [some result].
2.3 Modes
This is more of the WHAT section
Recommend: If a service has modes of operation, each mode be described as an extension to a core operation (or interface?), i.e., what is the distinguishing aspect of the mode, how is it invoked, how is this expressed in the output, etc. If no modes, drop this section.
2.4 Scenario(s)
This is the WHY section
Observation: Not sure what value this section has, scenarios are described within the Interoperability Specification. A service is most re-usable when it is context free (or minimal context as described in the Context section.
2.5 Context for Use (e.g., framework)
This is the WHEN section - the context defines the behavioral boundaries of the service to support maximum re-use.
2.5.1 Assumptions.
Observation: these sections may or may not be necessary depending on the service being described; if no content then the sections should be removed.
2.5.2 Dependencies
How is this content different from the input requirements or from pre-conditions?
Observation: these sections may or may not be necessary depending on the service being described; if no content then the sections should be removed.
2.5.3 Pre-conditions
Depending on the granularity of the service, a service may only be valid to run provided some prior business rule check or other value to be changed is actually present and available for the service to act upon. This is not an assumption, but a testable pre-condition that if not satisfied the service will fail to execute or achieve the desired result. Example: A service may exist to publish CDA lab documents to a patients PHR with the pre-condition that authentication has occurred. This implies that the state of authentication is testable (via inspection of the CDA content) and if the condition is not met, the service will not push the document out.
2.5.4 Triggers
Observation: these sections may or may not be necessary depending on the service being described; if no content then the sections should be removed.
2.5.5 Post-conditions
If the service has no defined output that can be validated except a notification of success (or failure) to set a value in the target of the service, a testable post condition of the service needs to be stated here. Example: A library service may check-in a document to a repository without notification to the user of success or failure; a testable post-condition is that the document is present in the repository with the correct (logged) values.
3.0 Dynamic Behaviors (Interactions/exchanges)
This is the HOW IT WORKS INSIDE section, and may not be present when an external service standard is referenced (black box approach).
Observation: This section is likely to be documentation of internal behavioral information that would not be replicated if described in the selected standard.
If the service is a new HITSP artifact, if there is any orchestration of the actors defined in the aggregated T and TPs this is the section for the UML interaction diagrams.
3.1 Semantic Content Requirements (Data elements and structure)
This section is only for the data the service interface requires in order to fulfill the “contract”; it does not describe the payload that may be a part of any exchange. This topic doesn’t seem to fit right in this section; might be a better fit under the input requirements or broken down to show content related to the minimal functionality with Mode specific elements and/or constraints defined under each Mode.
4.0 Implementation Model(s)
This is the HOW section
Example bindings vs a real piece of software; a reference implementation design.
This section could be merged with the Technical Implementation section unless the content is significantly different.
4.1 Mapping of Actors (see Table 3.2.3-1 from IS01)
A smaller version of the table will appear here ONLY if the service is a HITSP artifact and some specific coordination of actors from the Ts and TPs that are assembled is required; if an external standard is cited, then the internals of that service should not be described here and the section deleted.
4.2 Interaction Patterns Implementation
Lorem ipsum…
4.2.1 Input
Lorem ipsum…
4.2.2 Output
Lorem ipsum…
5.0 Technical Implementation(s)
One or more technical implementation designs would be included here, e.g., a WSDL for web services; the exact content subsections are dependent on the implementation design.
5.1 Overview
Lorem ipsum…
Figure 1.2-1 Lorem ipsum…
Insert a graphic here
5.2 Rules for Implementing
Lorem ipsum…
6.0 Conformance
This needs to be clarified…
7.0 Standards
This section can be deleted; the Source section in the Introduction serves the purpose of identifying the underlying standards in the document.
8.0 Reference Documents
This section should also include any bibliographic references to other publications It should include a core group of documents such as the Acronyms and Glossary. The resulting table should be alphabetically sorted by document ID; sort order should be non-id’d items first by alpha.