HL7 Common Terminology Services

The classes of actors that are anticipated to be users of the HL7 CTS API include:

• Message Creation Software – Software that is involved in the creation of HL7 messages. From a vocabulary perspective, this process involves the translation of internal messages and data into the syntax and semantics of the HL7 Version 3 standard.
• Message Processing Software – Software that receives, decodes and acts on the content of standard HL7 Version 3 messages. This process may include validation, translation and inferencing steps.
• RIM Modelers – The combination of people and tools that create and define HL7 Message content.
• Software Developers – The people who build the software that creates, validates and processes HL7 Version 3 messages.
• Vocabulary Translators – A combination of tools and people that translate the abstract HL7 Version 3 specification into the structure and terms of actual data processing applications.

The first two actor classes – message creation and message processing – have a different requirements profile than do the succeeding three:

• Performance – High throughput and scalability are paramount for message creation and processing. Modeling and mapping is considerably more tolerant of variable and potentially sub-optimal response times.
• Reliability – Message creation and processing software requires highly reliable software, while the modeling and authoring environment can tolerate some degree of unreliability and occasional failures.
• Functionality – Once solidified, the functional requirements of message creation and processing software will remain fixed. Any additional capabilities beyond those requirements will not be used. Authoring and modeling, however, will continue to create new and different browsing and viewing demands, and any (useful) functional capabilities may be drawn upon at random times.

Throughout the rest of this document, the message creation and processing profile will be referred to as the Runtime profile and the authoring and browsing as the Browser profile.

In the diagrams that follow, the classes whose instances are solely the responsibility of the HL7 Modeling Groups are colored green and classes that represent content that is managed by either HL7 or a third party terminology provider are colored blue. Existing meta-model classes will be colored a pale yellow. The authors of this document have little or no control over the content and structure of these existing classes – they are in the model solely as reference points.

The descriptions that follow the model use a semi-formal notation based on the model content :

• Class names will be represented in boldface (e.g. VocabularyDomain, ValueSet)
• Attribute names will appear in italics (e.g. vocabularyDomain_name, valueSet_id)
• Relationships will be underlined (e.g. a VocabularyDomain is represented by zero or more VocabularyDomainValueSets)

Where appropriate, relationship cardinality will be expressed by the forms below or something similar:

• 1..1 "Class 1 must relationship with exactly one Class 2 "
• 0..1 "Class 1 may be relationship by at most one Class 2 "
• 1..* "Class 1 must be relationship by one or more Class 2 "
• 0..* "Class 1 may be relationship by zero or more Class 2 "

• An Attribute must be constrained by exactly one Attribute_domain_constraint if and only if the attribute type is "coded".
• Any VocabularyDomain that describes the possible values of a DIM_attribute_domain_constraint must be based on the VocabularyDomain of the corresponding Attribute.
• Any VocabularyDomain that describes the possible values of a RIM_attribute_domain_constraint must be based on the VocabularyDomain of the corresponding DIM_attribute_row if one exists and on the VocabularyDomain of the corresponding Attribute if one doesn’t.

A VocabularyDomainValueSet represents an association between exactly one VocabularyDomain and exactly one ValueSet. Each association between a VocabularyDomain and a ValueSet may apply in zero or one ApplicationContexts. An ApplicationContext names a specific geopolitical entity (e.g. EU, Canada) and/or practice setting (e.g. veterinary medicine, public health), etc. and may be a setting_for zero or more VocabularyDomainValueSet associations.

A ValueSet may include a list of zero or more CodedConcepts drawn from a single CodeSystem. A ValueSet can represent:

• All of the CodedConcepts defined in exactly one CodeSystem
• A specified list of CodedConcepts that are defined in exactly one CodeSystem
• The set of CodedConcepts represented by another ValueSet.

The details about each of these forms will be described in the next section. First we describe the characteristics that all value sets have in common.

It is anticipated that there will be far too many value sets to be able to assign a unique mnemonic or meaningful name to all of them. The primary identifier for a ValueSet is a meaningless numeric identifier, the valueSet_id [4]. The valueSet_name can also contain a unique ‘meaningful’ identifier where appropriate. The valueSet_name is designed for communication between carbon-based life forms.

A ValueSet has a description that describes the intent and purpose of the set. It also has a definingExpression, which is intended to carry a formal machine readable expression that can be used to construct the ValueSet. The meaning and interpretation of definingExpression is not part of this specification. Both description and definingExpression are optional. The ValueSet attribute, allCodes, is described below.

A ValueSet must either be constructed_using at least one other ValueSet or it must be based on exactly one CodeSystem or both [5]. A CodeSystem defines a set of zero or more CodedConcepts which, in turn, signify relevant classes or entities within a particular domain of interest. CodeSystems can range from a simple table of genders to classification systems such as ICD-9 to rich, description-logic based systems such as OpenGalen or SNOMED-CT. As many CodeSystems undergo periodic revision, it is useful to record the ReleaseVersion that was used to define a given ValueSet at a particular point in time. A ValueSet may be defined_using at most one ReleaseVersion. A ReleaseVersion may be used_to_define zero or more ValueSets. The defined using relationship is strictly informative, and services may use a later revision of the code system to represent the ValueSet content. [6]Code systems will be discussed in considerably more detail in a later section describing the CTS Vocabulary API.

A ValueSet may also be constructed using zero or more additional ValueSets. Including a ValueSet means that the CodedConcepts represented by the included set are to be included as part of the containing set. ValueSetConstructors serve two purposes:

1. They allow ValueSets to be included by reference, meaning that changes in the contained set are automatically included in the container.
2. They make it possible to include CodedConcepts from more than one CodeSystem in a single ValueSet.

A ValueSetConstructor connects two ValueSets – the included set and the set being constructed. includeHeadCode determines whether the head code of the included set (if any) is to be included as part of the containing value set.

The table below shows examples of value set constructors. The value set "HL7ConformanceInclusion" includes the contents of the value set, "InclusionNotMandatory" which, in turn includes the set "InclusionNotRequired".

A ValueSet references a set of CodedConcepts. Frequently, the association between a ValueSet and a collection of CodedConcepts implies a subsumption, partitive or other hierarchical relationship where the value set itself represents the ‘whole’(parent) and the concept codes the individual ‘parts’ (children). When this is the case, there may also be a corresponding concept code in the code system itself that represents the same ‘whole’ or ‘parent’ concept. We refer to this corresponding code as the ‘head code’ of the associated value set. Many coded attributes in the HL7 RIM can have varying degrees of granularity. Using the example above, the InclusionNotRequired value set has a head code, "NR", and two subsidiary codes "Excluded (X) " and "Required may be empty (RE)". The second assignment line above indicates that the valid values for this value set may be "X" for excluded, "RE" for required, but may be empty and "NR" when the inclusion is not required for a non-specific reason.

When a value set is used to construct another value set, the head code may or may not be part of the included set. This provides the ability to represent what the HL7 community refers to as ‘abstract’ and ‘specializable’ value sets. A ValueSet may be identified_by at most one CodedConcept, which is known as the "head code". A CodedConcept may be the head_code_for zero or more ValueSets.

The following section describes the basic types that are used in the CTS Message API. Types with the prefix "types::" are all based on the HL7 Version 3 Data Types and are not described further here.

• CTSVersionId - a structure that contains the major and minor version of the CTS Specification. The current version of the specification would be major:1, minor:0 (1.0)
• CodeSystemId - A unique code system identifier. In the HL7 context, this should be the ISO Object Identifier (OID) assigned by HL7 if one exists. Other identifiers such as the DCE UUID, etc. may be used as code system identifiers in non-HL7 settings. In these situations is the responsibility of the implementor to reconcile any namespace conflicts that may arise between OID's and the other identifiers..
• CodeSystemName - the name of a code system. Both code system id and code system names are unique within the HL7 Version 3 namespace, but this is not guaranteed to be universally true.
• ConceptCode - a code that uniquely represents a class or concept within a given code system.
• VocabularyDomainName - the unique name of an HL7 vocabulary domain
• ReleaseVersionId - an identifier that uniquely names a release / version within the context of a code system.
• ValueSetId - an ISO Object Identifier (OID) that uniquely identifies a HL7 value set.
• ValueSetName - the unique name or mnemonic for a value set. Not all value sets will have both ids and names, but when they do, both must be unique.
• ConceptId - the combination of a code system identifier and a concept code which together provide a globally unique name for a concept
• ReleaseVersionId - the unique identifier of a version or release of one or more code systems
• ExpansionContext – an opaque blob used to pass contextual information between the server and client

The Message API uses a number of coded attributes which are described below.

• LanguageCode – a code for a spoken or written language that follows the rules described in IETF RFC 3066 – Tag for Identification of Languages. This language code consists of multiple subtags separated by hyphens (‘-‘). The first subtag identifies the major language code. It must be drawn from ISO 639.2 -Codes for the representation of names of languages--Part 1: Alpha-2 Code whenever possible. If no two character code is available, it may be drawn from ISO 639.2 - Codes for the representation of names of languages--Part 2: Alpha-3 Code. There are also additional escape mechanisms that aren’t described further here.
  The second subtag is optional. If present, it must be 2-8 characters in length. If two characters in length, it should contain a country code drawn from ISO 3166-1 Two character country codes. If the subtag is 3-8 characters long, it must come from the IANA language tag registry. Additional subtags serve to further refine the language.
• RelationshipCode - a concept code that uniquely identifies a particular relation as it occurs in a code system. Relationship codes must be drawn from the HL7 ConceptRelationship code system whenever possible.
• ApplicationContextCode - a code that identifies a context or realm such as a geopolitical domain, profession or other setting.
• DataTypeCode - a code that identifies the data type of a RIM attribute (e.g. CD, CE, CS, BIN, ST, etc).
• CodingStrengthCode - a code that identifies how non-codeable elements should be treated within an HL7 attribute (CWE - coded with allowed exceptions, CNE - coded, no exceptions)
• ValueSetNodeTypeCode - a code that defines the type of a value set that is returned as a nested list. Types are "A" – abstract, meaning that the value set is not selectable, "S" – specializable, meaning that the values set may be selected but also has further refinements and "L" – leaf, meaning that the node represents a selectable concept code that has no further subdivisions.
• CodeSystemTypeCode - a code that identifies a code system as internally maintained by HL7 (I), externally maintained (E) or externally maintained but HL7 carries an internal copy (EI).
• MatchAlgorithmCode - a code that identifies a string matching algorithm. Match algorithm codes are used in internal search functions

The following table lists the code systems and OIDS that are used in the CTS MAPI messages.

The message runtime and browsing API both inherit a common identification interface.

• getServiceName - returns the name assigned to the service by the service provider
• getServiceVersion - returns an implementation-specific service version identifier
• getServiceDescription - returns a description of the service, author, purpose, etc.
• getHL7ReleaseVersion - returns the latest HL7 vocabulary (not RIM) release represented by the service.
• getCTSVersion - returns the specific CTS version that the service implements (e.g. 1.0)

The following table contains the exceptions that can be raised by one or more of the methods described in this chapter. An exception is an abnormal condition that prevents a method invocation from completing.

The exceptions described below assume that the baseline exception includes a text field where the specific details of the exception can be spelled out. The additional attributes below provide further information beyond the basic text.

- An error that could not be anticipated by the specification has occurred. This includes things like memory faults, I/O errors, database access errors and any other sort of unexpected event that prevents successful completion of the API call. possible_cause can carry a more detailed description of what actually occurred. - The vocabularyDomain_name isn’t recognized by the service - The applicationContext_code isn’t recognized by the service
1. A value set id was supplied, but it isn’t recognized by the service or
2. Only a value set name was supplied the name isn't recognized by the service
3. Neither a name or an id was supplied
- Both valueSet_id and valueSet_name were supplied in a method call. valueSet_id identified a valid value set but it either wasn't the same set as that identified by valueSet_name. valueSet_name may identify a different value set or no valid value set at all. - concept_id.concept_code isn’t recognized as a valid concept code in the code system identified by concept_id.codeSystem_id - The service doesn't support subsumption testing for the code system named by codeSystem_id. - The supplied relationship qualifier isn’t recognized by the service. - the service wasn’t able to perform the requested translation
1. A code system_id was supplied and wasn’t recognized by the service
2. A code system name was supplied, but not the id and the name wasn’t recognized by the service
3. Neither the code system name nor the code system id were supplied
- The expansion context that was supplied by the client is invalid. This can occur because the context was somehow corrupted or because a time limit has expired and the context is no longer valid. - The service doesn’t support subsumption testing on post-coordinated expressions - The service was unable to determine which value set should be used for vocabularyDomain_name and applicationContext_code. - codeSystem_name doesn’t identify the same code system as codeSystem_id, or it doesn’t name a code system at all. - The time limit specified for the function call has expired. - The supplied match text was syntactically incorrect for the specified match algorithm. - The supplied match algorithm isn't supported by the service.

The following sections describe the interface methods of the runtime portion of the message API.

The Runtime section inherits the identification information from the Identification section.

getSupportedMatchAlgorithms - return a list of match algorithms that are implemented in the service.

getSupportedVocabularyDomains - return a list of vocabulary domains that are known to the service.

Parameters:

• matchText - If present and non-null, only vocabulary domains having names that match the text. If matchtext absent or null, all vocabulary domains will be returned.
• matchAlgorithm_code - If the matchText is present and non-null, the matchAlgorithm_code determines how the match text is applied. See Text Match Algorithms for details.
• timeout - The time, in milliseconds, that the client is willing to wait for this operation to be completed. A timeout value of 0 means that there is no time limit on the operation.
• sizeLimit - The maximum number of elements that the service may return. If exactly sizeLimit items are returned, the client assume that there were additional itemes that weren't returned. A sizeLimit of 0 indicates that the number of items that may be returned is unlimited.

Exceptions:

• BadlyFormedMatchText
• UnknownMatchAlgorithm
• TimeoutError
• UnexpectedError

A ValidationDetail entry contains a detailed description of an error or warning.

• codeInError - the concept code that the actual error or warning occurred on. If the error was detected in a concept qualifier or a translation, this value contains the qualifier name, qualifier value or translation value that was actually in error.
• isError - TRUE means that the detail entry describes an error. FALSE means that it is a warning.
• error_id - the error identifier (see: ValidateCode and ValidateTranslation return codes - ValidateCode and ValidateTranslation return codes)
• errorText - a textual explanation of the error or warning

ValidateCodeReturn returns the summary of validateCode call along with the details

• nErrors - the number of errors encountered. If greater than zero, the code or translation is not valid.
• nWarnings - the number of warnings returned. If a code or translation only has warnings, it can still be transmitted and processed even though some of the fields may not be correct.
• detail - a list of the individual errors and/or warnings

validateCode determines whether the coded attribute value contains a valid concept representation for the supplied vocabulary domain and application context. If errorCheckOnly is false, it also validates the code system name and displayName attributes if they are present. It then recursively validates the qualifiers using the same criteria. Concept codes that have originalText and no code are always considered invalid. validateCode doesn’t validate translations.

Parameters:

• vocabularyDomain_name - vocabulary domain for the supplied coded attribute
• codeToValidate - the HL7 concept code to be validated. At bare minimum code must contain the code and code system attributes.
• applicationContext_code - the context or "realm" in which the code is to be used
• activeConceptsOnly - if true (default), only concept codes that are currently active are considered valid. If false, the code will be considered valid as long as it is present in the code system.
• errorCheckOnly - if true, the concept code will only be checked for errors. No warnings will be returned

Exceptions:

• UnknownVocabularyDomain
• UnknownApplicationContextCode
• UnexpectedError

validateTranslation validates the primary code and any translations of an HL7 coded attribute. Any errors or warnings are returned in the ValidateCodeReturn structure.

Note: the details of what constitutes a valid translation are not covered in this document. It is presumed that an outside entity has defined the rules of translation and that this function provides a standardized way to access those rules. Refer to Code Mapping Model for the underlying translation model.

• vocabularyDomain_name - vocabulary domain for the supplied coded attribute
• codeToValidate - the HL7 concept code to be validated. At bare minimum code must contain the code and code system attributes.
• applicationContext_code - the context or "realm" in which the code is to be used
• activeConceptsOnly - if true (default), only concept codes that are currently active are considered valid. If false, the code will be considered valid as long as it is present in the code system.
• errorCheckOnly - if true, the concept code will only be checked for errors. No warnings will be returned

Exceptions:

• UnknownVocabularyDomain
• UnknownApplicationContextCode
• UnexpectedError

translateCode translates fromCode into the concept code, if any, that is valid for the vocabulary domain in the target code system or application context. It returns a complete copy of fromCode with the new translation (if any) appended to the end of the CD.translation sequence. If fromCode already contains a valid translation for the target code system or application context, the return copy of fromCode will match the original.

• vocabularyDomain_name - the vocabulary domain of the coded attribute to be translated
• fromCode– the code to be translated
• toCodeSystem_id - (optional) If supplied, translate the code into a concept code (or codes) drawn from this code system rather than determining the code system from the target context.
• toApplicationContext_code - (optional) The application context of the translated code. Used to determine the target value set which, in turn, determines the target code system. Only one of toCodeSystem_id or targetContext may be specified. If neither or both are specified an UnableToTranslate exception will be thrown.

translateCode returns an HL7 coded attribute that has been translated into the terms of the target coding system. The target code system can either be supplied in the call or can be determined from the targetContext.

Exceptions:

• UnknownVocabularyDomain
• UnknownCodeSystem
• UnknownApplicationContextCode
• UnableToTranslate
• UnexpectedError

fillInDetails returns a complete copy of codeToFillIn with codeSystemName, codeSystemVersion and displayName filled out in the base code and its qualifiers, if any. Qualifiers are filled out recursively - if qualifiers are nested or have other qualifiers, the details are filled in here as well. fillInDetails does not change the code translations.

Parameters:

• codeToFillIn - coded attribute to be completed
• displayLanguage_code- language to use for the display name(s)

Exceptions:

• UnknownCodeSystem
• UnknownConceptCode
• UnknownLanguage
• UnexpectedError

subsumes tests whether the parent coded attribute subsumes (is implied by) the child. If neither parentCode nor childCode have any qualifiers and both are drawn from the same code system, subsumes returns true if and only if childCode can be determined to belong to the transitive closure of the hasSubtype relationship graph headed by parentCode. This document makes no further assertions of the semantics of subsumption beyond this one case.

If the service supports subsumption involving qualifiers and/or subsumption tests across multiple code systems, it must define the appropriate translation semantics. If the service doesn’t support qualifier subsumption, it should raise the QualifiersNotSupported exception if presented with a parentCode or childCode containing qualifiers. Similarily, if the service doesn’t support cross-code system subsumption testing, it should raise SubsumptionNotSupported when supplied with codes with different code systems.

Parameters:

• parentCode - the parent coded attribute to test
• childCode- the child coded attribute to test

subsumes will return ‘true’ if the child code can be determined to be a subtype of the parent. Subsumes will also return ‘true’ if the child and parent codes are equivalent. Translations are ignored in this method.

Exceptions:

• UnknownCodeSystem
• UnknownCode
• SubsumptionNotSupported
• UnrecognizedQualifier
• QualifiersNotSupported
• UnexpectedError

areEquivalent determines whether the two supplied codes represent an equivalent concept from the perspective of the service. It is possible for one or both of the supplied codes to include qualifiers or be drawn from different code systems. code1 and code2 are considered equivalent if and only if code1 subsumes code2 and code2 subsumes code1. The semantics of subsumption are defined in the previous section.

Parameters:

• code1 - first code to test for equivalence
• code2 - second code to test

Exceptions:

• UnknownCodeSystem
• UnknownCode
• SubsumptionNotSupported
• UnrecognizedQualifier
• QualifiersNotSupported
• UnexpectedError

Every value set has a unique identifier. In addition, some value sets may also have an optional mnemonic or name, which, if present, must also be unique.

• ValueSet_id - the unique value set identifier.
• ValueSet_name - the unique value set name (optional)

• pathLength - an integer that defines the distance from the root value set. The root value set will always have a path length of 0
• nodeType_code - a concept code drawn from the HL7 ConceptGenerality (2.16.840.1.113883.5.24) code system. One of:
  • "S" - a specializable node. The concept_id in this node can be selected, but the node can also be further expanded.
  • "A" - an abstract node. The concept_id (if any) in this node cannot be selected. The node must be further expanded. To make a selection
  • "L" - a leaf node. The concept_id in this node may be selected, but no further expansion is possible.
• valueSet - id and name (if any) of the value set associated with this node
• concept_id - the code system and concept code associated with this node, if any
• displayName - the display name used to represent this node.
• isExpandable - TRUE means that this node can be further expanded using the expandValueSetExpansionContext function. canExpand will only be TRUE for specializable and abstract nodes, and then only when the original lookupValueSetExpansion call was made with expandAll set to FALSE.
• expansionContext - if isExpandable is TRUE, expansionContext contains whatever is required by the specific service implementation to further expand the node in a subsequent call. It is opaque to the client software.

The various cases below describe how different sorts of value set definitions would be expanded.

Case 1: Value set A references all of the codes in a non-hierarchical code system, which contains concept codes 1,2, ..N

Case 2: Value set B references all of the codes in a hierarchical code system. The concept code hierarchy is reflected in concept id (1 is root, 1.1 is first child of root, 1.2 second child, 1.2.1 first child of first child, etc.)

Case 3: Value set C specifically references concept codes 1,2,3 in a code system. No references include a relationship code and there is no head code.

Case 4: Value set D references concept codes 1,2,3,4 in a code system. No references include a relationship code, but concept code 4 is defined as the head code.

Case 5: Value set E references value set D above, with includeHeadCode set to TRUE

Case 6: Value set F references value set D above, with includeHeadCode set to FALSE

Case 7: Value set G references concept codes 1.1, 2.1 and 3.1 in a hierarchical code system. All three references use the hasSubtype relationship code. The 1.1 reference includes the referenced code. The 2.1 reference excludes the referenced code. The 3.1 reference has leafOnly set to true. G has no head code.

lookupValueSetExpansion returns an expansion of the value set associated with the supplied vocabulary domain and optional context. The entire vocabulary domain can be expanded all at once (expandAll = TRUE) or can be expanded one level at a time (expandAll = FALSE). If expanding one level at a time, every node that can be further expanded will have isExpandable set to TRUE, meaning that the expansionContext can be passed to expandValueSetExpansionContext for further expansion.

Parameters:

• vocabularyDomain_name - vocabulary domain to expand
• applicationContext_code– context in which the vocabulary domain is to be expanded (optional)
• language_code - language to be used for the returned display names
• expandAll - TRUE means expand all nodes to their entire depth, FALSE means expand one level (default: TRUE)
• timeout - The time, in milliseconds, that the client is willing to wait for this operation to be completed. A timeout value of 0 means that there is no time limit on the operation.
• sizeLimit - The maximum number of elements that the service may return. If exactly sizeLimit items are returned, the client assume that there were additional itemes that weren't returned. A sizeLimit of 0 indicates that the number of items that may be returned is unlimited.

Exceptions:

• UnknownVocabularyDomain
• UnknownApplicationContextCode
• UnknownLanguage
• TimeoutError
• UnexpectedError

expandValueSetExpansionContext takes an opaque expansionContext that was previously returned in a ValueSetExpansion entry and further expands the corresponding node. An additional level. The return is identical to that of lookupValueSetExpansion, and all of the initial constraints, including the timeout value still apply.

Parameters:

• expansionContext- context returned by a previous lookupValueSetExpansion or expandValueSetExpansionContext call

Exceptions:

• InvalidExpansionContext
• TimeoutError
• UnexpectedError

The message browser inherits the identification information from the interface described in Service Identification Section.

This section describes several "building block" structures that are used by the service description and then describes how the information is accessed via the service.

The VocabularyDomainValueSet structure contains the description of a value set (see: Expand a Vocabulary Domain for details) and the context code, if any, in which the value set applies

• definedByValueSet - the value set that defines a vocabulary domain in the specific application context
• applicationContext_code - the context in which the value set applies

VocabularyDomainDescription is the structure returned by the lookupVocabularyDomain function.

• vocabularyDomain_name - the unique name of the vocabulary domain
• description - a description of the domain
• restrictsDomain_name - the vocabulary domain that this domain restricts, if any
• basisOfDomains - a list of the domains that are restrictions of this domain, if any
• constrainsAttributes - a list of the RIM attributes that use this vocabulary domain, if any
• representedByValueSets - a list of the value sets and context that can represent this vocabulary domain, if any

lookupVocabularyDomain returns detailed information about a vocabulary domain.

• vocabularyDomain_name - the name of the vocabulary domain to look up

Exceptions:

• UnknownVocabularyDomain
• UnexpectedError

FullValueSetDescription includes a complete description of the value set including the list of included concept codes and other value sets.

ValueSetConstructor

• includedValueSet - the identifier and name, if any of a value set that is considered to be part of the containing set
• includeHeadCode - TRUE means that the head code, if any, of the included value set is considered to be part of the including set. FALSE means that it isn’t.

ValueSetCodeReference

• referenced_code - a concept code that is referenced by the value set
• relationship_code- A relationship code. If present, all of the descendants of the referenced code are consider part of the value set as well, subject to the leafOnly constraint below. If the relationship is transitive, all descendants are included in the value set. If the relationship is not transitive, only the direct targets of the referenced code are considered.
• includeReferencedCode- TRUE means that the referenced code itself is part of the value set. FALSE means that only the children or descendants are included. includeReferencedCode will always be TRUE when a relationship code is not supplied.
• leafOnly - TRUE means only include the leaf nodes of the relationship. FALSE means include all descendant nodes except, perhaps, the referenced code itself. leafOnly must always be FALSE if no relationship_code is present.

ValueSetDescription

• idAndName-the value set identifier and name, if any
• description - a textual description of the value set and its use
• definingExpression- an expression that defines the set contents (if any)
• basedOnCodeSystem - the code system id, name and version used to construct the value set
• allCodes - TRUE means that all of the codes in the code system are included in the value set. If TRUE, the value set mustn't reference any additional code
• head_code- the concept code that represents the entire value set (if any)

FullValueSetDescription

• description - The id, name, description, etc. of the value set
• constructedUsingValueSets- a list of additional value sets and head code inclusions, if any, that are used to construct this set
• usedToDefine - a list of any other value sets that have been constructed using this set
• referencesCodes - a list of concept codes that this value set explicitly references. This will be empty if allCodes is true and will not include any codes that are implicitly included from other value sets and/or concept code relationships.

lookupValueSet retrieves a complete description of a value set given either a value set identifier or a value set name.

Parameters:

• valueSet_id - the identifier of the value set to look up
• valueSet_name - the name of the value set to look up

Either the value set id, the value set name or both may be supplied. If both are supplied, the name must correctly match the id or an error will be raised.

Exceptions:

• UnknownValueSet
• ValueSetNameIdMismatch
• UnexpectedError

CodeSystemRegistration:

• sponsor - the HL7 member or organization that sponsers the registration
• publisher - the name of the official publisher of the code system
• versionReportingMethod - how new versions are created and distributed
• licensingInformation - licensing requirements for the code system
• inUMLS - TRUE means that the code system is contained in the Unified Medical Language System (UMLS)
• systemSpecificLocatorInfo- the meaning of this field depends upon the specific publisher. It serves to further identify the code system information and is intended to contain things like the HL7 Version 2 table name, etc.
• codeSystemType_code - A concept code that specifies whether the code system is internally created and maintained by HL7 (I), externally created and maintained (E) or externally created but HL7 maintains an internal image for convenience (EI)

Note: The registration elements above are intended to be descriptive only. While many of the fields (sponsor, publisher, versionReportingMethod, etc.) could have additional structure, it wasn't considered necessary within the scope of the present document

CodeSystemInfo

• description - basic description of the code system - see: CTSCodeSystemDescriptor structure
• registrationInfo - registration information for the code system (if any)

lookupCodeSystem returns detailed information for a code system given either a code system identifier (OID) or name.

• codeSystem_Id - the unique code system identifier, which is usually the ISO OID
• codeSystem_name - the name of the code system

Either the code system id, the code system name or both may be supplied. If both the id and name are supplied, the name must match the id or an error will be raised.

Exceptions:

• UnknownCodeSystem
• CodeSystemNameIdMismatch
• UnexpectedError

lookupValueSetForDomain returns the descriptor (id and name if any) of the value set that would be used for the supplied domain in the application context (if any).

Parameters:

• vocabularyDomain_name - name of the vocabulary domain to look up
• applicationContext_code - application context (optional)

Exceptions:

• UnknownVocabularyDomain
• UnknownApplicationContextCode
• NoApplicableValueSet
• UnexpectedError

isCodeInValueSet returns true if the supplied concept identifier is included in and can be selected from the value set, false otherwise.

Parameters:

• valueSet_id - the identifier of the value set to look up
• valueSet_name - the name of the value set to look up
• includeHeadCode - TRUE means that the head code (if there is any) is considered to be part of the set. FALSE means that the head code, if any, is excluded.
• codeToValidate - the code system id and concept code to test

Either the value set id, the value set name or both may be supplied. If both are supplied, the name must correctly match the id or an error will be raised.

Exceptions:

• UnknownValueSet
• ValueSetNameIdMismatch
• UnknownConceptCode
• UnknownCodeSystem
• UnexpectedError

This section describes the coded data elements used in the vocabulary API

• LanguageCode – a code for a spoken or written language that follows the rules described in IETF RFC 3066 – Tag for Identification of Languages. This language code consists of multiple subtags separated by hyphens (‘-‘). The first subtag identifies the major language code. It must be drawn from ISO 639.2 -Codes for the representation of names of languages--Part 1: Alpha-2 Code whenever possible. If no two character code is available, it may be drawn from ISO 639.2 - Codes for the representation of names of languages--Part 2: Alpha-3 Code. There are also additional escape mechanisms that aren’t described further here.
  The second subtag is optional. If present, it must be 2-8 characters in length. If two characters in length, it should contain a country code drawn from ISO 3166-1 Two character country codes. If the subtag is 3-8 characters long, it must come from the IANA language tag registry. Additional subtags serve to further refine the language.
• MimeTypeCode - A mime type drawn from IETF RFC2045 - Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. HL7 also maintains a subset of the Mime type codes in the Media Type code system, OID 2.16.840.1.113883.5.79 - MediaType.
• ConceptStatusCode- the status of a concept within a code system (active, retired, etc.)
• PropertyCode - a property that may be associated with concepts in a code system.
• RelationshipCode - identifies a particular relation as it occurs in a code system. Relationship codes must be drawn from the HL7 ConceptRelationship code system whenever possible.
• MapQualityCode - the general "quality" of a concept mapping (exact, broader, narrower, etc.)
• RelationQualifierCode - qualifier for a concept relationship.
• MatchAlgorithmCode -a code for an algorithm used for string matching and comparison.

The following table lists the code systems and OIDS that are used in the CTS VAPI messages.

The vocabulary runtime and browsing API both inherit a common identification interface.

The service identification describes the service implementation - its name, version, description and which CTS version it is implementing. It is possible for any identification access call to raise an UnexpectedError exception.

• getServiceName - returns the name given to the service by the service provider.
• getServiceVersion- returns a version identifier specific to the service implementation
• getServiceDescription - a description of the service, author, purpose, etc.
• getCTSVersion - the specific CTS version that the service implements (e.g. 1.0)

The following table contains the exceptions that can be raised by one or more of the methods described in this section. An exception is an abnormal condition that prevents a method invocation from completing. Exceptions involving communications, operating system, database, etc. errors are not included in the list below, and it is assumed that the mechanisms for handling this type of error will already be addressed by the language and/or communications subsystem used in the implementation.

The exceptions described below assume that the baseline exception includes a text field where the specific details of the exception can be spelled out. The additional attributes below provide further information beyond this basic text.

- the code system identifier isn't recognized by the service. - the code system identifier was recognized, but the concept_code wasn’t defined in the code system. - property_code isn’t supported by the code system - language_code isn’t supported by the code system - relationship_code isn’t supported by the code system - relationQualifier_code isn’t supported by the code system - mimeType_code isn’t supported by the code system - no designation could be found for concept_id in language language_code - codeSystem_name doesn’t identify the same code system as codeSystem_id, or it doesn’t name a code system at all. - matchText can’t be parsed by the service

• codeSystem_id - the unique code system identifier, which is usually the ISO OID.
• codeSystem_name - the official name of the code system.
• copyright - copyright notice associated with code system, if any.
• codeSystem_versions- the version or versions of the code system that are supported by this service. This list may be empty if the code system doesn’t support individual version identifiers.

getSupportedCodeSystems provides a list of all code systems and versions supported by the service.

Parameters:

• timeout - The time, in milliseconds, that the client is willing to wait for this operation to be completed. A timeout value of 0 means that there is no time limit on the operation.
• sizeLimit - The maximum number of elements that the service may return. If exactly sizeLimit items are returned, the client nust assume that there were additional items that weren't returned. A sizeLimit of 0 indicates that the number of items that may be returned is unlimited.

Exceptions:

• TimeoutError
• UnexpectedError

• codeSystem - the code system id, name and supported version(s)
• fullName- the complete name of the code system
• codeSystemDescription- the description of the code system contents
• supportedLanguages- a list of all of the languages supported by the service for the code system. A "supported" language is recognized by the code system and at least some of the concept designations or properties are available in that language. All code systems must support at least one language. While the service must list all of the primary language subtags that it supports, it is optional whether it lists secondary languages. (i.e., if it supports "en-UK", it must list "en" but may or may not list "en-UK").
• supportedRelations- a list of all of the relationship codes supported by the service for the code system. A "supported" relationship is recognized by the code system and the code system is able to determine whether any two concept codes in the code system are or are not related to each other under this relationship. A non-hierarchical code system doesn’t need to support any relationships. Subsumption is represented by the hasSubtype relationship code.
• supportedProperties- a list of all of the properties supported by the service for the code system. A "supported" property means that the code system recognizes the property and at least one coded concept is associated with this property and an optional value.
• supportedMimeTypes- a list of the mime types supported by the code system. All code systems must support the "text/plain" mime type, even if there are no properties associated with it.
• supportedRelationQualifiers- a list of the relationship qualifiers supported by the code system (if any).

lookupCodeSystemInfo takes a code system identifier (OID) and/or name and returns a detailed description of the code system and elements that are supported by the service.

Parameters:

• codeSystem_id - the iso OID of the code system
• codeSystem_name - the unique code system name

Exceptions:

• UnknownCodeSystem
• CodeSystemNameIdMismatch
• UnexpectedError

isConceptIdValid determines whether the supplied concept identifier is valid.

Parameters:

• concept_id - the code system and concept code to validate
• activeConceptsOnly- TRUE means that only active concepts are considered valid. FALSE means that any concept code known to the code system is ok.

Exceptions:

• UnknownCodeSystem
• UnexpectedError

The StringAndLanguage structure contains both the text and associated language code. The two part structure exists because it is possible for the language returned by lookupDesignation and other operations to be different than the requested language. As an example, the client may request the designation for a concept in the en-scouse (English Liverpudlian dialect) and the service may return a designation in unqualified English (en). The client software may need to know that the returned value doesn’t exactly match the requested value.

Some programming language bindings may already include the language code as part of the return value (e.g. XML/SOAP). For the sake of consistency, the language_code field should be carried in those bindings even if it is redundant.

lookupDesignation returns the most appropriate designation for the supplied concept identifier in the specified language and context. lookupDesignation will first attempt to find a designation that exactly matches the supplied language. If no matches are found, it will remove the rightmost subtag, if any and try again. This process will be repeated until a matching designation is found or only the primary subtag remains. As an example, "en-UK-south" would match "en-UK-south", "en-UK" and "en" in that order. It would not match "en-US" or "fr".

Parameters:

• concept_id - the code system id and concept code
• language_code - the desired language of the returned designation

Exceptions:

• UnknownLanguageCode
• UnknownCodeSystem
• UnknownConceptCode
• NoApplicableDesignationFound
• UnexpectedError

Determine whether the supplied concept codes are related

Parameters:

• codeSystem_id - the code system of the parent and child codes
• source_code - the concept code that occurs as the source of the relationship
• target_code - the concept code that occurs as the target of the relationship
• relationship_code - the concept code that identifies the relationship
• relationQualifiers - an optional list of relationship qualifier codes. If the relationQualifiers list contains one or more qualifier codes, only relationship entries that that have qualifiers that match all of the qualifiers in the list will be considered.
• directRelationsOnly- TRUE means test direct relationships only, FALSE means that the transitive closure of the relationship is to be tested if the relationship is transitive. If the relationship is not transitive, the result is the same no matter the setting of this flag.

areCodesRelated returns TRUE if one of the following conditions holds:

1. There is a direct relationship of type relationship_code between source_code and target_code according to the specified code system.
2. There is a direct relationship of type relationship_code between target_code and source_code according to the specified code system and the relationship is defined as symmetric.
3. Source_code equals target code and the relationship is reflexive.
4. directRelationsOnly is FALSE, relationship_code is transitive and there is a relationship of type relationship_code between source_code and target_code in the forward transitive closure of relationship_code starting at source_code.
5. directRelationsOnly is FALSE, relationship_code is transitive and symmetric and there is a relationship of type relationship_code between target_code and source_code in the backwards transitive closure of relationship_code starting at source_code

Exceptions:

• UnknownConceptCode
• UnknownCodeSystem
• UnknownRelationshipCode
• UnknownRelationQualifier
• UnexpectedError

getSupportedCodeSystems provides a list of all code systems and versions supported by the service. The CodeSsytemIdAndVersionsList structure is defined in Code Systems Supported by the API

• timeout - The time, in milliseconds, that the client is willing to wait for this operation to be completed. A timeout value of 0 means that there is no time limit on the operation.
• sizeLimit - The maximum number of elements that the service may return. If exactly sizeLimit items are returned, the client assume that there were additional itemes that weren't returned. A sizeLimit of 0 indicates that the number of items that may be returned is unlimited.

Exceptions:

• TimeoutError
• UnexpectedError

Return a list of concept identifiers having matching designation(s)and criteria

• codeSystem_id - code system to be searched.
• matchText - If present and non-null, only vocabulary domains having names that match the text. If matchtext absent or null, all vocabulary domains will be returned.
• matchAlgorithm_code - If the matchText is present and non-null, the matchAlgorithm_code determines how the match text is applied. See Text Match Algorithms for details.
• language_code - if supplied, restrict the search to designations with this language only. (Default: Search all languages). Language code matches will not be more general than the supplied language_code. If, for example, "en" is passed as the language code, it will match designations with a language of "en", "en-UK", "en-UK-south", etc. If, however, "en-UK-south" is passed as the language code, only concepts having designations in that specific language will be returned.
• activeConceptsOnly- TRUE means match active concept codes only, FALSE means match any concept code in the code system (Default: TRUE)
• timeout - The time, in milliseconds, that the client is willing to wait for this operation to be completed. A timeout value of 0 means that there is no time limit on the operation.
• sizeLimit - The maximum number of elements that the service may return. If exactly sizeLimit items are returned, the client assume that there were additional itemes that weren't returned. A sizeLimit of 0 indicates that the number of items that may be returned is unlimited.

Exceptions:

• UnknownCodeSystem
• BadlyFormedMatchText
• UnknownMatchCode
• UnknownLanguageCode
• TimeoutError
• UnexpectedError

Return a list of concept identifiers having one or more properties with values that match the supplied match text string and other criteria:

• codeSystem_id - code system to be searched.
• matchText - the text to search for. The format and syntax of matchText depends upon the matchAlgorithmCode.
• matchAlgorithm_code - The match algorithm to use when comparing the match text with the target designations. See Text Match Algorithms for details.
• language_code - if supplied, restrict the search to designations with this language only. (Default: Search all languages). Language code matches will not be more general than the supplied language_code. If, for example, "en" is passed as the language code, it will match designations with a language of "en", "en-UK", "en-UK-south", etc. If, however, "en-UK-south" is passed as the language code, only concepts having designations in that specific language will be returned.
• activeConceptsOnly- TRUE means match active concept codes only, FALSE means match any concept code in the code system (Default: TRUE)
• properties- list of properties codes to be searched. (Default: search all properties)
• mimeTypes- list of mime types to search. (Default: search all MIME types)
• timeout - The time, in milliseconds, that the client is willing to wait for this operation to be completed. A timeout value of 0 means that there is no time limit on the operation.
• sizeLimit - The maximum number of elements that the service may return. If exactly sizeLimit items are returned, the client assume that there were additional itemes that weren't returned. A sizeLimit of 0 indicates that the number of items that may be returned is unlimited.

Exceptions:

1. UnknownCodeSystem
2. BadlyFormedMatchText
3. UnknownMatchCode
4. UnknownLanguageCode
5. UnknownPropertyCode
6. UnknownMimeTypeCode
7. TimeoutError
8. UnexpectedError

The following structures are all used to build the complete coded concept description return structure

lookupDesignations returns selected designations for the supplied concept. The matching rules for lookupDesignations are identical to those defined in Search for Concept Codes by Designation Text. The ConceptDesignationList return structure is described in ConceptDesignation Structure.

• concept_id - the code system identifier and concept code to look up
• matchText - the text to search for. The format and syntax of matchText depends upon the matchAlgorithmCode.
• matchAlgorithm_code - The match algorithm to use when comparing the match text with the target designations. See Text Match Algorithms for details.
• language_code - if supplied, restrict the search to this language only. (Default: Search all languages)

Exceptions:

• UnknownCodeSystem
• UnknownConceptCode
• BadlyFormedMatchText
• UnknownMatchAlgorithm
• UnknownLanguageCode
• UnexpectedError

lookupProperties returns selected properties for the supplied concept. Properties, matchText language_code and mimeTypes properties follow the same rules as those in lookupConceptCodesByProperty. The ConceptPropertyList return structure is described in ConceptProperty Structure.

• concept_id- the code system identifier and concept code to get the properties for
• properties- a list of properties to search. If omitted or empty, all properties are searched.
• matchText - the text to search for. The format and syntax of matchText depends upon the matchAlgorithmCode.
• matchAlgorithm_code - The match algorithm to use when comparing the match text with the target designations. See Text Match Algorithms for details.
• language_code - if supplied, restrict the search to this language only. (Default: Search all languages)
• mimeTypes - list of mime types to search. (Default: search all MIME types)

Exceptions:

• UnknownCodeSystem
• UnknownConceptCode
• BadlyFormedMatchText
• UnknownMatchAlgorithm
• UnknownLanguageCode
• UnknownPropertyCode
• UnknownMimeTypeCode
• UnexpectedError

Parameters:

• pathLength - an integer that defines the distance from the codeToExpand in hops. The root node will always have a path length of 0.
• concept_code - related concept code
• designation - the preferred designation for code in the appropriate language and usage context, or the default designation if none is stated explicitly as being preferred
• relationQualifiers - list of relationship qualifiers that apply to this node
• canExpand - TRUE means that there are additional concept codes directly related to concept_code that can be further expanded.
• expansionContext- if canExpand is true, this field contains an opaque context that can be used to further expand the code in this node.

• expandConcept_id - code system identifier and concept code to be expanded. If the relationship_code is "hasSubtype" and souceToTarget is true, the concept code can be omitted, meaning that we want all "root" concepts in the subtype relationship - all concepts that do not appear as the target of one or more hasSubtype relationships.
• relationship_code - relationship to be expanded
• sourceToTarget- TRUE means expand from source to target. FALSE means expand from target to source.
• directRelationsOnly- if TRUE or relationship_code is not transitive, only the direct targets (or sources if sourceToTarget is FALSE) of expandConcept_id are returned. If FALSE and relationship_code is transitive, descendants or ancestors are returned as well.
• designationlanguage_code - language that the returned concept designations should be in
• timeout - The time, in milliseconds, that the client is willing to wait for this operation to be completed. A timeout value of 0 means that there is no time limit on the operation.
• sizeLimit - The maximum number of elements that the service may return. If exactly sizeLimit items are returned, the client assume that there were additional itemes that weren't returned. A sizeLimit of 0 indicates that the number of items that may be returned is unlimited.

A depth-first tree-walk is used to return the descendants or ancestors of the node. if a node occurs in more than one branch, it is replicated for the return structure. If directRelationsOnly is false, the relationship is transitive, and there is a cycle in the relationship structure, expansion will stop at the last non-repeating node. canExpand will be set to true for this node which will allow the client to manually descend the cyclic structure if it chooses, one cycle at a time.

language_code and usageContext_code are used to determine which designation to return in the RelatedCode structure. The rules for determining the correct designation are the same as in the lookupDesignation method, except that this method doesn't throw a NoApplicableDesignationFound exception. If there isn't an applicable designation for a particular node, the designation field will contain an empty string.

Exceptions:

• UnknownCodeSystem
• UnknownConceptCode
• UnknownRelationshipCode
• UnknownLanguageCode
• TimeoutError
• UnexpectedError

expandCodeExpansionContext further expands a RelatedCodeList node that was returned by a previous lookupCodeExpansion or expandCodeExpansionContext call.

• contextToExpand- an opaque identifier that was returned in an expansionContext attribute of a RelatedCodeList node in a previous lookupCodeExpansion or expandCodeExpansionContext call

Exceptions:

• InvalidExpansionContext

  Note: expansion contexts are not necessarily permanent. The temporal validity of an expansion context is a function of the specific service implementation.

• NoApplicableDesignationFound
• TimeoutError
• UnexpectedError

/* CTS Specification Version Identifier */
        struct CTSVersionId {
                short   major;
                short   minor;
        };

package org.hl7.CTSVAPI;


/**
* org/hl7/CTSVAPI/CTSVersionId.java .
* Generated by the IDL-to-Java compiler (portable), version "3.1"
* from idl/CTSVAPI.idl
* Monday, March 8, 2004 11:17:26 PM CST
*/


/**
 *$lt;PRE>CTS Specification Version Identifier </PRE>
 */
public final class CTSVersionId implements org.omg.CORBA.portable.IDLEntity
{
  public short major = (short)0;
  public short minor = (short)0;

  public CTSVersionId ()
  {
  } // ctor

  public CTSVersionId (short _major, short _minor)
  {
    major = _major;
    minor = _minor;
  } // ctor

} // class CTSVersionId

/*
 * A property code was used that wasn't valid for the code system
 */
        exception UnknownPropertyCode {
                PropertyCode            property_code;
        };

package org.hl7.CTSVAPI;


/**
* org/hl7/CTSVAPI/UnknownPropertyCode.java .
* Generated by the IDL-to-Java compiler (portable), version "3.1"
* from idl/CTSVAPI.idl
* Monday, March 8, 2004 11:17:26 PM CST
*/

public final class UnknownPropertyCode extends java.lang.Exception
{
  public String property_code = null;

  public UnknownPropertyCode ()
  {
    // super(UnknownPropertyCodeHelper.id());
  } // ctor

  public UnknownPropertyCode (String _property_code)
  {
    // super(UnknownPropertyCodeHelper.id());
    property_code = _property_code;
  } // ctor


  public UnknownPropertyCode (String $reason, String _property_code)
  {
    // super(UnknownPropertyCodeHelper.id() + "  " + $reason);
    property_code = _property_code;
  } // ctor

} // class UnknownPropertyCode

/*************************************************
 *      Code mapping interface                   *
 *                                               *
 * The code mapping interface represents one     *
 * or more mappings between code systems         *
 *************************************************/
        interface CodeMapping : Identification {

/* List of mappings supported by the service */
                CodeMapList getSupportedMaps() raises (UnexpectedError);


/* Map a concept code from one code system into the closest equivalent (if any)
 * in the target code system
 *      fromConcept_id                   - The code system / concept code to map
 *      toCodeSystem_id                  - The target code system
 *	map_name			 - Name of the map to use.  Can be omitted if there is only one possible map
 *					   from the fromConcept_id code system to the toCodeSystem_id.
 *
 *      Returns                         - Mapped concept in target system
 *
 *      Exceptions
 *              UnknownCodeSystem       - Either the from or the to code system isn't supported
 *                                        by this map service
 *              UnknownConceptCode      - The concept code to be mapped isn't part of the code system
 *              MappingNotAvailable     - There is not a map from the supplied concept code to the
 *                                        target code system.
 *
 *		UnableToMap      	- The requested concept code could not be mapped
 *		UnknownMapName		- mapping_name is not understood by the service
 *		MapSourceMismatch	- source code system id in map didn't match fromConcept_id code system
 *		MapTargetMismatch	- target code system id in map didn't match targetCodeSystem_id in call
 *		AmbiguousMapRequest	- There is more than one possible map between the source concept and target
 *		UnexpectedError		- An unspecified error occurred that prevented successful completion
 *					  of the request
 */
                MappedConceptCode mapConceptCode(
                        in ConceptId                    fromConcept_id,
                        in CodeSystemId                 toCodeSystem_id,
                        in string			map_name
                        )
                        raises ( UnknownCodeSystem,
                                 UnknownConceptCode,
                                 MappingNotAvailable,
                                 UnknownMapName,
                                 AmbiguousMapRequest,
                                 MapNameSourceMismatch,
                                 MapNameTargetMismatch,
                                 UnableToMap,
                                 UnexpectedError);
        };

package org.hl7.CTSVAPI;


/**
* org/hl7/CTSVAPI/CodeMappingOperations.java .
* Generated by the IDL-to-Java compiler (portable), version "3.1"
* from idl/CTSVAPI.idl
* Monday, March 8, 2004 11:17:27 PM CST
*/


/*************************************************
 *      Code mapping interface                   *
 *                                               *
 * The code mapping interface represents one     *
 * or more mappings between code systems         *
 *************************************************/
public interface CodeMappingOperations  extends org.hl7.CTSVAPI.IdentificationOperations
{

  /**
 *<PRE>List of mappings supported by the service </PRE>
 */
  org.hl7.CTSVAPI.CodeMap[] getSupportedMaps () throws org.hl7.CTSVAPI.UnexpectedError;

  /**
 *<PRE>Map a concept code from one code system into the closest equivalent (if any)
   * in the target code system
   *      fromConcept_id                   - The code system / concept code to map
   *      toCodeSystem_id                  - The target code system
   *	map_name			 - Name of the map to use.  Can be omitted if there is only one possible map
   *					   from the fromConcept_id code system to the toCodeSystem_id.
   *
   *      Returns                         - Mapped concept in target system
   *
   *      Exceptions
   *              UnknownCodeSystem       - Either the from or the to code system isn't supported
   *                                        by this map service
   *              UnknownConceptCode      - The concept code to be mapped isn't part of the code system
   *              MappingNotAvailable     - There is not a map from the supplied concept code to the
   *                                        target code system.
   *
   *		UnableToMap      	- The requested concept code could not be mapped
   *		UnknownMapName		- mapping_name is not understood by the service
   *		MapSourceMismatch	- source code system id in map didn't match fromConcept_id code system
   *		MapTargetMismatch	- target code system id in map didn't match targetCodeSystem_id in call
   *		AmbiguousMapRequest	- There is more than one possible map between the source concept and target
   *		UnexpectedError		- An unspecified error occurred that prevented successful completion
   *					  of the request
   </PRE>
 */
  org.hl7.CTSVAPI.MappedConceptCode mapConceptCode (org.hl7.CTSVAPI.ConceptId fromConcept_id, String toCodeSystem_id, String map_name)
  		throws org.hl7.CTSVAPI.UnknownCodeSystem, org.hl7.CTSVAPI.UnknownConceptCode, org.hl7.CTSVAPI.MappingNotAvailable,
  		       org.hl7.CTSVAPI.UnknownMapName, org.hl7.CTSVAPI.AmbiguousMapRequest, org.hl7.CTSVAPI.MapNameSourceMismatch,
  		       org.hl7.CTSVAPI.MapNameTargetMismatch, org.hl7.CTSVAPI.UnableToMap, org.hl7.CTSVAPI.UnexpectedError;
} // interface CodeMappingOperations

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="urn://hl7.org/CTSVAPI" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:apachesoap="http://xml.apache.org/xml-soap"
                     xmlns:impl="urn://hl7.org/CTSVAPI" xmlns:intf="urn://hl7.org/CTSVAPI" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/
                     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
                     xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<wsdl:types>
		<schema targetNamespace="urn://hl7.org/CTSVAPI" xmlns="http://www.w3.org/2001/XMLSchema">
			<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
			<complexType name="SupportedMap">
				<sequence>
					<element name="map_name" nillable="true" type="xsd:string"/>
					<element name="mapDescription" nillable="true" type="xsd:string"/>
					<element name="fromCodeSystem_id" nillable="true" type="xsd:string"/>
					<element name="fromCodeSystem_name" nillable="true" type="xsd:string"/>
					<element name="fromCodeSystem_version" nillable="true" type="xsd:string"/>
					<element name="toCodeSystem_id" nillable="true" type="xsd:string"/>
					<element name="toCodeSystem_name" nillable="true" type="xsd:string"/>
					<element name="toCodeSystem_version" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="ArrayOfSupportedMap">
				<complexContent>
					<restriction base="soapenc:Array">
						<attribute ref="soapenc:arrayType" wsdl:arrayType="impl:SupportedMap[]"/>
					</restriction>
				</complexContent>
			</complexType>
			<complexType name="UnexpectedError">
				<sequence>
					<element name="possible_cause" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="ConceptId">
				<sequence>
					<element name="codeSystem_id" nillable="true" type="xsd:string"/>
					<element name="concept_code" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="MappedConceptCode">
				<sequence>
					<element name="mappedConcept_id" nillable="true" type="impl:ConceptId"/>
					<element name="mapQuality_code" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="MappingNotAvailable">
				<sequence>
					<element name="fromCodeSystem_id" nillable="true" type="xsd:string"/>
					<element name="toCodeSystem_id" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="UnableToMap">
				<sequence/>
			</complexType>
			<complexType name="UnknownConceptCode">
				<sequence>
					<element name="concept_code" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="UnknownCodeSystem">
				<sequence>
					<element name="codeSystem_id" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="UnknownMapName">
				<sequence>
					<element name="map_name" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="AmbiguousMapRequest">
				<sequence>
					<element maxOccurs="unbounded" name="possible_maps" nillable="true" type="xsd:string"/>
				</sequence>
			</complexType>
			<complexType name="CTSVersionId">
				<sequence>
					<element name="major" type="xsd:short"/>
					<element name="minor" type="xsd:short"/>
				</sequence>
			</complexType>
		</schema>
	</wsdl:types>
	<wsdl:message name="UnknownMapName">
		<wsdl:part name="fault" type="impl:UnknownMapName"/>
	</wsdl:message>
	<wsdl:message name="AmbiguousMapRequest">
		<wsdl:part name="fault" type="impl:AmbiguousMapRequest"/>
	</wsdl:message>
	<wsdl:message name="getServiceDescriptionResponse">
		<wsdl:part name="getServiceDescriptionReturn" type="xsd:string"/>
	</wsdl:message>
	<wsdl:message name="MappingNotAvailable">
		<wsdl:part name="fault" type="impl:MappingNotAvailable"/>
	</wsdl:message>
	<wsdl:message name="getServiceVersionRequest">

   </wsdl:message>
	<wsdl:message name="getSupportedMapsResponse">
		<wsdl:part name="getSupportedMapsReturn" type="impl:ArrayOfSupportedMap"/>
	</wsdl:message>
	<wsdl:message name="UnknownConceptCode">
		<wsdl:part name="fault" type="impl:UnknownConceptCode"/>
	</wsdl:message>
	<wsdl:message name="UnexpectedError">
		<wsdl:part name="fault" type="impl:UnexpectedError"/>
	</wsdl:message>
	<wsdl:message name="UnknownCodeSystem">
		<wsdl:part name="fault" type="impl:UnknownCodeSystem"/>
	</wsdl:message>
	<wsdl:message name="UnableToMap">
		<wsdl:part name="fault" type="impl:UnableToMap"/>
	</wsdl:message>
	<wsdl:message name="getCTSVersionRequest">

   </wsdl:message>
	<wsdl:message name="getServiceNameResponse">
		<wsdl:part name="getServiceNameReturn" type="xsd:string"/>
	</wsdl:message>
	<wsdl:message name="getServiceNameRequest">

   </wsdl:message>
	<wsdl:message name="getServiceDescriptionRequest">

   </wsdl:message>
	<wsdl:message name="mapConceptCodeRequest">
		<wsdl:part name="fromConcept_id" type="impl:ConceptId"/>
		<wsdl:part name="toCodeSystem_id" type="xsd:string"/>
		<wsdl:part name="map_name" type="xsd:string"/>
	</wsdl:message>
	<wsdl:message name="mapConceptCodeResponse">
		<wsdl:part name="mapConceptCodeReturn" type="impl:MappedConceptCode"/>
	</wsdl:message>
	<wsdl:message name="getSupportedMapsRequest">

   </wsdl:message>
	<wsdl:message name="getCTSVersionResponse">
		<wsdl:part name="getCTSVersionReturn" type="impl:CTSVersionId"/>
	</wsdl:message>
	<wsdl:message name="getServiceVersionResponse">
		<wsdl:part name="getServiceVersionReturn" type="xsd:string"/>
	</wsdl:message>
	<wsdl:portType name="CodeMappingOperations">
		<wsdl:operation name="getSupportedMaps">
			<wsdl:input message="impl:getSupportedMapsRequest" name="getSupportedMapsRequest"/>
			<wsdl:output message="impl:getSupportedMapsResponse" name="getSupportedMapsResponse"/>
			<wsdl:fault message="impl:UnexpectedError" name="UnexpectedError"/>
		</wsdl:operation>
		<wsdl:operation name="mapConceptCode" parameterOrder="fromConcept_id toCodeSystem_id map_name">
			<wsdl:input message="impl:mapConceptCodeRequest" name="mapConceptCodeRequest"/>
			<wsdl:output message="impl:mapConceptCodeResponse" name="mapConceptCodeResponse"/>
			<wsdl:fault message="impl:AmbiguousMapRequest" name="AmbiguousMapRequest"/>
			<wsdl:fault message="impl:UnexpectedError" name="UnexpectedError"/>
			<wsdl:fault message="impl:UnableToMap" name="UnableToMap"/>
			<wsdl:fault message="impl:MappingNotAvailable" name="MappingNotAvailable"/>
			<wsdl:fault message="impl:UnknownMapName" name="UnknownMapName"/>
			<wsdl:fault message="impl:UnknownConceptCode" name="UnknownConceptCode"/>
			<wsdl:fault message="impl:UnknownCodeSystem" name="UnknownCodeSystem"/>
		</wsdl:operation>
		<wsdl:operation name="getCTSVersion">
			<wsdl:input message="impl:getCTSVersionRequest" name="getCTSVersionRequest"/>
			<wsdl:output message="impl:getCTSVersionResponse" name="getCTSVersionResponse"/>
			<wsdl:fault message="impl:UnexpectedError" name="UnexpectedError"/>
		</wsdl:operation>
		<wsdl:operation name="getServiceDescription">
			<wsdl:input message="impl:getServiceDescriptionRequest" name="getServiceDescriptionRequest"/>
			<wsdl:output message="impl:getServiceDescriptionResponse" name="getServiceDescriptionResponse"/>
			<wsdl:fault message="impl:UnexpectedError" name="UnexpectedError"/>
		</wsdl:operation>
		<wsdl:operation name="getServiceName">
			<wsdl:input message="impl:getServiceNameRequest" name="getServiceNameRequest"/>
			<wsdl:output message="impl:getServiceNameResponse" name="getServiceNameResponse"/>
			<wsdl:fault message="impl:UnexpectedError" name="UnexpectedError"/>
		</wsdl:operation>
		<wsdl:operation name="getServiceVersion">
			<wsdl:input message="impl:getServiceVersionRequest" name="getServiceVersionRequest"/>
			<wsdl:output message="impl:getServiceVersionResponse" name="getServiceVersionResponse"/>
			<wsdl:fault message="impl:UnexpectedError" name="UnexpectedError"/>
		</wsdl:operation>
	</wsdl:portType>
	<wsdl:binding name="CodeMappingServiceSoapBinding" type="impl:CodeMappingOperations">
		<wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
		<wsdl:operation name="getSupportedMaps">
			<wsdlsoap:operation soapAction=""/>
			<wsdl:input name="getSupportedMapsRequest">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:input>
			<wsdl:output name="getSupportedMapsResponse">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:output>
			<wsdl:fault name="UnexpectedError">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="mapConceptCode">
			<wsdlsoap:operation soapAction=""/>
			<wsdl:input name="mapConceptCodeRequest">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:input>
			<wsdl:output name="mapConceptCodeResponse">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:output>
			<wsdl:fault name="AmbiguousMapRequest">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="UnexpectedError">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="MapNameSourceMismatch">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="MapNameTargetMismatch">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="UnableToMap">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="MappingNotAvailable">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="UnknownMapName">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="UnknownConceptCode">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
			<wsdl:fault name="UnknownCodeSystem">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="getCTSVersion">
			<wsdlsoap:operation soapAction=""/>
			<wsdl:input name="getCTSVersionRequest">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:input>
			<wsdl:output name="getCTSVersionResponse">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:output>
			<wsdl:fault name="UnexpectedError">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="getServiceDescription">
			<wsdlsoap:operation soapAction=""/>
			<wsdl:input name="getServiceDescriptionRequest">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:input>
			<wsdl:output name="getServiceDescriptionResponse">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:output>
			<wsdl:fault name="UnexpectedError">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="getServiceName">
			<wsdlsoap:operation soapAction=""/>
			<wsdl:input name="getServiceNameRequest">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:input>
			<wsdl:output name="getServiceNameResponse">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:output>
			<wsdl:fault name="UnexpectedError">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="getServiceVersion">
			<wsdlsoap:operation soapAction=""/>
			<wsdl:input name="getServiceVersionRequest">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:input>
			<wsdl:output name="getServiceVersionResponse">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:output>
			<wsdl:fault name="UnexpectedError">
				<wsdlsoap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn://hl7.org/CTSVAPI" use="encoded"/>
			</wsdl:fault>
		</wsdl:operation>
	</wsdl:binding>
	<wsdl:service name="CodeMappingOperationsService">
		<wsdl:port binding="impl:CodeMappingServiceSoapBinding" name="CodeMappingService">
			<wsdlsoap:address location="http://localhost:8080/axis/services/CodeMappingService"/>
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>