Difference between revisions of "Identifiers IM Design Pattern"
m (→Diagram(s)) |
|||
| (12 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
[[Category:Information Model Design Patterns - Candidate]] | [[Category:Information Model Design Patterns - Candidate]] | ||
| + | [[Category:Design Patterns]] | ||
[[:Category:Information Model Design Patterns - Candidate|Return to Candidate Information Model Design Pattern List]] | [[:Category:Information Model Design Patterns - Candidate|Return to Candidate Information Model Design Pattern List]] | ||
| Line 10: | Line 11: | ||
<!--Date on which the pattern received final (ballot) approval. (Leave blank for an initial submission.) --> | <!--Date on which the pattern received final (ballot) approval. (Leave blank for an initial submission.) --> | ||
| − | Pending | + | *''Approved at Harmonization:'' 2011-11-17 |
| + | *''Approved by Ballot:'' Pending | ||
| + | |||
| + | == Applicable circumstances == | ||
| + | |||
| + | <!--Identifies the model circumstances in which the pattern applies. Use "MAY" for optional and "SHALL" for mandatory --> | ||
| + | |||
| + | This pattern applies in all circumstances where identifiers are used. The work group responsible for the model must decide (using the criteria above) whether system identifiers, human identifiers or both are required. Models will be expected to use the appropriate parts (human and/or system) of the pattern. For clarity, the System Identifier pattern is just the id attribute on the root class. The Human Identifier pattern is everything else. | ||
| + | |||
| + | == Non-applicable circumstances == | ||
| + | |||
| + | <!--Identifies the model circumstances in which the does not pattern applies. Use "SHOULD NOT" for optional and "SHALL NOT" for mandatory --> | ||
| + | |||
| + | None | ||
== Purpose == | == Purpose == | ||
| Line 44: | Line 58: | ||
'''Identifier pattern applied to Roles''' | '''Identifier pattern applied to Roles''' | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Description == | == Description == | ||
| Line 54: | Line 63: | ||
<!--Explanation of the pattern and how it works --> | <!--Explanation of the pattern and how it works --> | ||
| − | The | + | === Overview === |
| + | The purpose of this pattern is to provide a standardized (and safe) way of expressing both "system" identifiers and "human readable" identifiers for the identifiable RIM objects - Acts*, Entities and Roles. (No pattern is defined for the edge case of Participation identifiers as no use has been found for these to have anything other than system identifiers. The pattern for Acts is 'draft' and is documented in the [[Talk:Identifiers_IM_Design_Pattern|Discussion]] portion of this page.) These two types of identifiers are defined as follows: | ||
| − | + | '''System Identifier''': A unique, verified identifier specific to one and only one object. It is intended for use in system transactions on that object (e.g. state change requests, "Get" queries, etc.) While these may, on occasion, be exposed to humans, no identifier context is required. There should only be one system identifier for a given object except in rare cases where system migration or other change forces assignment of a secondary identifier for the object. The system identifier is always assigned by the system that "owns" the object. Identifiers assigned by non-owning systems are not system identifiers. | |
| − | + | '''Human Identifier''': An identifier used by and exposed to humans that is associated with this object. It may or may not be uniquely associated with the object (i.e. it's possible for one ''Human Identifier'' to link to multiple objects. As well, there can be multiple human identifiers of different types associated with a given object. The validity of the identifier in pointing to the object may be time-limited due to re-use of identifiers. | |
| − | + | The identifier pattern supports both types of identifiers. Neither type is required. It is up to the designers of a given model to determine which of the two types they require or whether both are needed. Criteria to reach these decisions are as follows: | |
| − | + | 1. A system identifier should be provided if there's a need to manipulate the object or perform direct retrieval of the object by computer systems (changing status, updating the object, etc.) | |
| − | + | 2. Human identifiers should be provided if there's potentially the need to have multiple identifiers for an object assigned by different parties and/or where additional metadata about an identifier is needed (type, status, validity time, assigning authority) | |
| − | + | Note: It is possible for one identifier to be both a 'system' identifier and a 'human' identifier. In this circumstance the identifier should be sent twice - once in each location. | |
| − | The | + | The constraints represented in the diagram represent minimums. Additional tightening may be performed. For example, making the presence of an identifier mandatory, requiring typeCode, etc. However, care should be taken about constraining too far. At the international level, none of the descriptive attributes for human identifiers should be excluded, and the maximum number of repetitions should not be constrained. In specifications closer to implementation level, it is possible for additional constraints that prohibit repetitions and/or exclude descriptive attributes when it is known that that use-cases supported by the repetitions and descriptive attributes will never apply in the context of the constraining specification. |
| − | it | ||
| − | |||
| − | + | Note: This pattern is specified using HL7 Datatypes R2. However, the pattern is still valid using datatypes R1. In R1, substitute SET<II> in place of DSET<II>. Also, the constraints and guidance on identifier scope and verification cannot be applied formally due to the lack of these properties in R1. However, the guidance still applies. For example, if a given identifier meets the characteristics of a BUSN scope, then it can't be used as a Primary identifier. | |
| − | |||
| − | it | ||
| − | + | === Usage === | |
| + | The following is a set of 'boiler plate' language for inclusion in models that follow the identifier pattern. Content in <span style="color:#0000FF">blue</span> provides additional guidance, rationale and usage information. | ||
| − | + | <b>AnEntity/ARole.id</b> (Primary identifier): This identifies the primary object identifier for the object as used by the authoring system of the instance. Multiple repetitions are allowed to support conveying "version" and "snapshot" ids where these are necessary. In rare circumstances (where a system migration is taking place), multiple "object" identifiers may be sent to support transition. However, alternate identifiers must not be sent in this structure. | |
| − | + | <span style="color:#0000FF">The rationale for supporting multiple repetitions even when only OBJ identifiers are desired is similar to that for allowing code translations. Sometimes systems may migrate between identification schemes just as they migrate between code systems. When this occurs, there is generally a period of time during which both the old identifier and new identifier need to be transmitted to enable interoperability during the transition phase. Supporting multiple repetitions allows this clean transition. Therefore, caution should be used in constraining the upper cardinality down to 1.</span> | |
| − | + | <span style="color:#0000FF">The constraint that these identifiers must be verified is that it is nonsensical for a system id to be non-verified. These identifiers are not subject to human data-entry and therefore verification is unnecessary.</span> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | <span style="color:#0000FF">Because business identifiers can correspond to multiple objects, they must not be used for system identifiers, which require discrete resolution to one and only one object.</span> | |
| − | + | <b>AnEntity/ARole.alternateIdentifier</b>: This association is what allows the alternate (possibly human-readable) identifiers to be specified. | |
| − | In | + | <span style="color:#0000FF">In many cases, multiple identifiers will be useful. If constrained to only one, a model will have to make clear what identifier gets sent if multiple identifiers apply.</span> |
| − | |||
| − | |||
| − | be | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | <b>IdentifiedEntity.id</b> (Alternate identifier): This provides an additional or alternate identifier for the object assigned or used by some other context. Usually this will have an id scope of BUSN or OBJ. In cases where the identifier root is unknown, it may be left unspecified and the identifier expressed with a UNC (unencoded) null flavor. Repetitions are not permitted as each repetition will potentially have different supporting attributes. To send multiple identifiers, use multiple repetitions of the referencing association. | |
| − | + | <span style="color:#0000FF">This attribute is not made mandatory to allow for the possibility of sending a repetition where the identifier is unknown or unencoded but other information such as type or assigning authority is known.</span> | |
| − | + | <b>IdentifiedEntity.code</b> (Identifier type): This identifies the "kind" of identifier present. An appropriate concept domain should be used for the type of object being identified. Depending on the vocabulary this might be a general category (e.g. "Credit Card Number") or could be so specific as to essentially be coded version of the identifier root (e.g. "Royal Bank of Canada Platinum Visa Number"). | |
| − | + | <span style="color:#0000FF">Having a coded type is most important if you want computer systems to be able to display or act upon identifiers of different types in different ways. Otherwise the II.identifierName property is sufficient for providing a human-readable label</span> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | <b>IdentifiedEntity.statusCode</b> (Identifier status): Identifies whether the specified identifier is considered to be active (still usable) for the entity. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | to | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | <span style="color:#0000FF">The notion is not that this id will be reused for another object (which is non-conformant for v3 expectations and is bad practice for any identifier management scheme), but that the id has a limited period of validity (perhaps there was a duplicate record, and it's now retired).</span> | |
| + | <b>IdentifiedEntity.effectiveTime</b> (Identifier timerange): Indicates the period of time over which the identifier is considered to be valid for the entity. | ||
| − | = | + | <span style="color:#0000FF">Same rationale as for statusCode.</span> |
| − | < | + | <b>Organization.name</b> (Assigning authority name): Indicates the name of the body that issued the identifier. |
| − | + | <span style="color:#0000FF">This is primarily useful when the IdentifiedEntity.code attribute is being sent and is not sufficient to fully describe the identifier. For example, if the identifier type was "Driver's license", knowing the assigning authority was "Florida Dept. of Motor Vehicles" would be sufficient to infer that the identifier is a Florida drivers license. As with IdentifiedEntity.code, this attribute is not necessary if the II.identifierName property is specified. | |
| − | |||
| − | = | ||
| − | |||
| − | |||
| − | |||
| − | |||
== Examples == | == Examples == | ||
| Line 166: | Line 121: | ||
<!--Reference to models (and locations within them) where the pattern has been used --> | <!--Reference to models (and locations within them) where the pattern has been used --> | ||
| − | + | ||
== Variations == | == Variations == | ||
| Line 172: | Line 127: | ||
<!-- Identify other variations of this pattern, if any. --> | <!-- Identify other variations of this pattern, if any. --> | ||
| − | + | Additional attributes or associations may be added off the IdentifiedEntity classes if the business case requires additional semantics. | |
| + | |||
| + | The pattern for Acts is 'draft' and is documented in the [[Talk:Identifiers_IM_Design_Pattern|Discussion]] portion of this page. | ||
Latest revision as of 07:03, 25 November 2011
Return to Candidate Information Model Design Pattern List
Contents
Identifier Pattern
Effective Date
- Approved at Harmonization: 2011-11-17
- Approved by Ballot: Pending
Applicable circumstances
This pattern applies in all circumstances where identifiers are used. The work group responsible for the model must decide (using the criteria above) whether system identifiers, human identifiers or both are required. Models will be expected to use the appropriate parts (human and/or system) of the pattern. For clarity, the System Identifier pattern is just the id attribute on the root class. The Human Identifier pattern is everything else.
Non-applicable circumstances
None
Purpose
In HL7, identifiers are conveyed by the II datatype. However, this datatype only provides information needed to resolve unique identity. However, it does not provide any contextual information needed by humans, such as who issued the identifier, what type of identifier it is, etc. While this information is not always needed, it's commonly required. As well, when collections of identifiers are present it's often necessary to be able to distinguish the purpose of each of the identifiers.
Sponsor
MnM
Diagram(s)
General (UML) view of the pattern
Identifier pattern applied to Entities
Identifier pattern applied to Roles
Description
Overview
The purpose of this pattern is to provide a standardized (and safe) way of expressing both "system" identifiers and "human readable" identifiers for the identifiable RIM objects - Acts*, Entities and Roles. (No pattern is defined for the edge case of Participation identifiers as no use has been found for these to have anything other than system identifiers. The pattern for Acts is 'draft' and is documented in the Discussion portion of this page.) These two types of identifiers are defined as follows:
System Identifier: A unique, verified identifier specific to one and only one object. It is intended for use in system transactions on that object (e.g. state change requests, "Get" queries, etc.) While these may, on occasion, be exposed to humans, no identifier context is required. There should only be one system identifier for a given object except in rare cases where system migration or other change forces assignment of a secondary identifier for the object. The system identifier is always assigned by the system that "owns" the object. Identifiers assigned by non-owning systems are not system identifiers.
Human Identifier: An identifier used by and exposed to humans that is associated with this object. It may or may not be uniquely associated with the object (i.e. it's possible for one Human Identifier to link to multiple objects. As well, there can be multiple human identifiers of different types associated with a given object. The validity of the identifier in pointing to the object may be time-limited due to re-use of identifiers.
The identifier pattern supports both types of identifiers. Neither type is required. It is up to the designers of a given model to determine which of the two types they require or whether both are needed. Criteria to reach these decisions are as follows:
1. A system identifier should be provided if there's a need to manipulate the object or perform direct retrieval of the object by computer systems (changing status, updating the object, etc.)
2. Human identifiers should be provided if there's potentially the need to have multiple identifiers for an object assigned by different parties and/or where additional metadata about an identifier is needed (type, status, validity time, assigning authority)
Note: It is possible for one identifier to be both a 'system' identifier and a 'human' identifier. In this circumstance the identifier should be sent twice - once in each location.
The constraints represented in the diagram represent minimums. Additional tightening may be performed. For example, making the presence of an identifier mandatory, requiring typeCode, etc. However, care should be taken about constraining too far. At the international level, none of the descriptive attributes for human identifiers should be excluded, and the maximum number of repetitions should not be constrained. In specifications closer to implementation level, it is possible for additional constraints that prohibit repetitions and/or exclude descriptive attributes when it is known that that use-cases supported by the repetitions and descriptive attributes will never apply in the context of the constraining specification.
Note: This pattern is specified using HL7 Datatypes R2. However, the pattern is still valid using datatypes R1. In R1, substitute SET<II> in place of DSET<II>. Also, the constraints and guidance on identifier scope and verification cannot be applied formally due to the lack of these properties in R1. However, the guidance still applies. For example, if a given identifier meets the characteristics of a BUSN scope, then it can't be used as a Primary identifier.
Usage
The following is a set of 'boiler plate' language for inclusion in models that follow the identifier pattern. Content in blue provides additional guidance, rationale and usage information.
AnEntity/ARole.id (Primary identifier): This identifies the primary object identifier for the object as used by the authoring system of the instance. Multiple repetitions are allowed to support conveying "version" and "snapshot" ids where these are necessary. In rare circumstances (where a system migration is taking place), multiple "object" identifiers may be sent to support transition. However, alternate identifiers must not be sent in this structure.
The rationale for supporting multiple repetitions even when only OBJ identifiers are desired is similar to that for allowing code translations. Sometimes systems may migrate between identification schemes just as they migrate between code systems. When this occurs, there is generally a period of time during which both the old identifier and new identifier need to be transmitted to enable interoperability during the transition phase. Supporting multiple repetitions allows this clean transition. Therefore, caution should be used in constraining the upper cardinality down to 1.
The constraint that these identifiers must be verified is that it is nonsensical for a system id to be non-verified. These identifiers are not subject to human data-entry and therefore verification is unnecessary.
Because business identifiers can correspond to multiple objects, they must not be used for system identifiers, which require discrete resolution to one and only one object.
AnEntity/ARole.alternateIdentifier: This association is what allows the alternate (possibly human-readable) identifiers to be specified.
In many cases, multiple identifiers will be useful. If constrained to only one, a model will have to make clear what identifier gets sent if multiple identifiers apply.
IdentifiedEntity.id (Alternate identifier): This provides an additional or alternate identifier for the object assigned or used by some other context. Usually this will have an id scope of BUSN or OBJ. In cases where the identifier root is unknown, it may be left unspecified and the identifier expressed with a UNC (unencoded) null flavor. Repetitions are not permitted as each repetition will potentially have different supporting attributes. To send multiple identifiers, use multiple repetitions of the referencing association.
This attribute is not made mandatory to allow for the possibility of sending a repetition where the identifier is unknown or unencoded but other information such as type or assigning authority is known.
IdentifiedEntity.code (Identifier type): This identifies the "kind" of identifier present. An appropriate concept domain should be used for the type of object being identified. Depending on the vocabulary this might be a general category (e.g. "Credit Card Number") or could be so specific as to essentially be coded version of the identifier root (e.g. "Royal Bank of Canada Platinum Visa Number").
Having a coded type is most important if you want computer systems to be able to display or act upon identifiers of different types in different ways. Otherwise the II.identifierName property is sufficient for providing a human-readable label
IdentifiedEntity.statusCode (Identifier status): Identifies whether the specified identifier is considered to be active (still usable) for the entity.
The notion is not that this id will be reused for another object (which is non-conformant for v3 expectations and is bad practice for any identifier management scheme), but that the id has a limited period of validity (perhaps there was a duplicate record, and it's now retired).
IdentifiedEntity.effectiveTime (Identifier timerange): Indicates the period of time over which the identifier is considered to be valid for the entity.
Same rationale as for statusCode.
Organization.name (Assigning authority name): Indicates the name of the body that issued the identifier.
This is primarily useful when the IdentifiedEntity.code attribute is being sent and is not sufficient to fully describe the identifier. For example, if the identifier type was "Driver's license", knowing the assigning authority was "Florida Dept. of Motor Vehicles" would be sufficient to infer that the identifier is a Florida drivers license. As with IdentifiedEntity.code, this attribute is not necessary if the II.identifierName property is specified.
Examples
Variations
Additional attributes or associations may be added off the IdentifiedEntity classes if the business case requires additional semantics.
The pattern for Acts is 'draft' and is documented in the Discussion portion of this page.
