Sharing Valuesets, Codes, and Maps (SVCM), published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.5.2-current built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.SVCM/ and changes regularly. See the Directory of published versions

2:3.101 Translate Code [ITI-101]

This section corresponds to transaction [ITI-101] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-101] is used by the Terminology Consumer and Terminology Repository Actors.

2:3.101.1 Scope

This transaction is used by the Terminology Consumer that supports the Translate Option to translate a given code from a ValueSet to a code from another ValueSet based on a ConceptMap Resource. The request is received by the Terminology Repository that supports the Translate Option. The Terminology Repository processes the request and returns a response of Parameters with the translated code.

2:3.101.2 Actor Roles

Table 2:3.101.2-1: Actor Roles

Actor:	Terminology Consumer
Role:	Requests a translation of a code from one ValueSet to another based on a ConceptMap from the Terminology Repository.
Actor:	Terminology Repository
Role:	Returns information for the translated code based on criteria provided by the Terminology Consumer.

2:3.101.3 Referenced Standards

HL7 FHIR	HL7 FHIR standard R4 http://hl7.org/fhir/R4/index.html

2:3.101.4 Messages

Figure 2:3.101.4-1: Interaction Diagram

2:3.101.4.1 Translate Code Request Message

The Translate Code Request message is a FHIR $translate operation on the ConceptMap Resource.

2:3.101.4.1.1 Trigger Events

A Terminology Consumer triggers a Translate Code Request to a Terminology Repository according to the business rules for the translation. These business rules are outside the scope of this transaction.

2:3.101.4.1.2 Message Semantics

A Terminology Consumer initiates an $translate request using HTTP GET as defined at http://hl7.org/fhir/conceptmap-operation-translate.html on the ConceptMap Resource. The required input parameters are identified in Table 2:3.101.4.1.2-1.

The URL for this operation is: [base]/ConceptMap/$translate?[parameter=value]

Where [base] is the URL of Terminology Repository.

See ITI TF-2: Appendix W for informative implementation material for this transaction.

Table 2:3.101.4.1.2-1: Translate Code Message HTTP Input Parameters

Input Parameter Name	IHE Constraint	Search Type	Description
url [0..1]	[1..1]	uri	A canonical URL for a concept map. The server must know the concept map (e.g., it is defined explicitly in the server's concept maps, or it is defined implicitly by some code system known to the server.
source [0..1]	[1..1]	uri	Identifies the value set used when the concept (system/code pair) was chosen. May be a logical id, or an absolute or relative location. The source value set is an optional parameter because in some cases, the client cannot know what the source value set is. However, without a source value set, the server may be unable to safely identify an applicable concept map, and would return an error. For this reason, a source value set SHOULD always be provided. Note that servers may be able to identify an appropriate concept map without a source value set if there is a full mapping for the entire code system in the concept map, or by manual intervention.
code [0..1]	[1..1]	code	The code that is to be translated. If a code is provided, a system must be provided.
system [0..1]	[1..1]	uri	The system for the code that is to be translated.
target [0..1]	[1..1]	uri	Identifies the value set in which a translation is sought. May be a logical id, or an absolute or relative location. If there is no target specified, the server should return all known translations, along with their source.
_format [0..1]		mime-type	The requested format of the response from the mime-type value set. See ITI TF-2: Appendix Z.6.
conceptMap [0..1]	[0..0] This parameter is not allowed when the url parameter is used.	ConceptMap
conceptMapVersion [0..1]		string	The identifier that is used to identify a specific version of the concept map to be used for the translation. This is an arbitrary value managed by the concept map author and is not expected to be globally unique. For example, it might be a timestamp (e.g., yyyymmdd) if a managed version is not available.
version [0..1]		string	The version of the system, if one was provided in the source data.
coding [0..1]	[0..0] This parameter is not allowed when the code+system parameters are used.	Coding
codeableConcept [0..1]	[0..0] This parameter is not allowed when the code+system parameters are used.	CodeableConcept
targetsystem [0..1]	[0..0] This parameter is not allowed when the target parameter is used.	uri
dependency [0..*]			Another element that may help produce the correct mapping.
dependency.element [0..1]		uri	The element for this dependency.
dependency.concept [0..1]		CodeableConcept	The value for this dependency.
reverse [0..1]		boolean	if this is true, then the operation should return all the codes that might be mapped to this code. This parameter reverses the meaning of the source and target parameters.

2:3.101.4.1.3 Expected Actions

The Terminology Repository shall process the input parameters to discover the value sets and code to be translated that matches the parameters given and return a response as per Section 2:3.101.4.2 or an OperationOutcome with an error message.

2:3.101.4.2 Translate Code Response Message

2:3.101.4.2.1 Trigger Events

The Terminology Repository found the translation details matching the input parameters specified by the Terminology Consumer as a result of a Translate Code Request.

2:3.101.4.2.2 Message Semantics

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for handling guidance for Access Denied.

The response message is a FHIR Parameters Resource with properties of the code set based on the out parameters defined at http://hl7.org/fhir/conceptmap-operation-translate.html and reproduced in Table 2:3.101.4.2.2-1.

Table 2:3.101.4.2.2-1: Translate Code Message HTTP Output Parameters

Parameter Name	Type	Description
result [1..1]	boolean	True if the concept could be translated successfully. The value can only be true if at least one returned match has an equivalence which is not unmatched or disjoint.
message [0..1]	string	Error details, for display to a human. If this is provided when result = true, the message carries hints and warnings (e.g., a note that the matches could be improved by providing additional detail).
match [0..*]		A concept in the target value set with an equivalence. Note that there may be multiple matches of equal or differing equivalence, and the matches may include equivalence values that mean that there is no match.
match.equivalence [0..1]	code	A code indicating the equivalence of the translation, using values from http://hl7.org/fhir/valueset-concept-map-equivalence.html
match.concept [0..1]	Coding	The translation outcome. Note that this would never have userSelected = true, since the process of translations implies that the user is not selecting the code (and only the client could know differently)
match.product [0..*]		Another element that is the product of this mapping
match.product.element [0..1]	uri	The element for this product
match.product.concept [0..1]	Coding	The value for this product
match.source [0..1]	uri	The canonical reference to the concept map from which this mapping comes from

2:3.101.4.2.3 Expected Actions

The Terminology Consumer has received the response and continues with its workflow.

2:3.101.5 Security Considerations

See the general Security Consideration in ITI TF-1: 51.5.

2:3.101.5.1 Security Audit Considerations

Note that the same audit message is recorded by both Terminology Consumer and Repository. The difference being the Audit Source element. Both sides record to show consistency between the message sent by the Consumer and the action taken at the Registry.

The actors involved shall record audit events according to the Audit Event for Translate Code by the Terminology Consumer and Repository.