This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "Common Design Patterns"

From HL7Wiki
Jump to navigation Jump to search
 
(7 intermediate revisions by 4 users not shown)
Line 28: Line 28:
  
 
=== UML for the general pattern  ===
 
=== UML for the general pattern  ===
 
+
* --[[User:Ioana13|Ioana13]] 16:09, 1 October 2009 (UTC) Does '''OtherIds''' contain '''Thing''' or the other way around?
 
[[Image:IIPattern.png]]
 
[[Image:IIPattern.png]]
  
Line 34: Line 34:
  
 
[[Image:II-pattern-entity.gif]]
 
[[Image:II-pattern-entity.gif]]
 +
 +
==== Descriptions ====
 +
The following is a set of 'boiler plate' language for inclusion in models that follow the identifier pattern
 +
 +
<b>anEntity.id</b> (Primary identifier): This identifies the primary object identifier for the object as used by the author of the instance.  Multiple repetitions are allowed to support conveying "version" and "snapshot" ids where these are necessary.  However, alternate identifiers must not be sent in this structure.
 +
 +
<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
 +
 +
<b>IdentifiedEntity.code</b> (Identifier type): This identifies the "kind" of identifier present.
 +
 +
<b>IdentifiedEntity.statusCode</b> (Identifier status): Identifies whether the specified identifier is considered to be active (still usable) for the entity.
 +
 +
<b>IdentifiedEntity.effectiveTime</b> (Identifier timerange): Indicates the period of time over which the identifier is considered to be valid.
  
 
=== Act-ActRelationship Equivalent ===
 
=== Act-ActRelationship Equivalent ===
Line 39: Line 52:
 
[[Image:II-pattern-act.gif]]
 
[[Image:II-pattern-act.gif]]
  
 +
--[[User:Lmckenzi|Lmckenzi]] 16:20, 24 September 2009 (UTC) This diagram does not convey the correct semantics.  EffectiveTime identifies the time the act is effective and has no relationship to the validity of the identifier.  Same thing with status.  As well, the author participation indicates what type of entity authored the act, not what type of identifier the act has.
 +
 +
--[[User:Gschadow|Gschadow]] 23:18, 24 September 2009 (UTC) This pattern is very confusing and the little I understand of it I completely disagree. I'm not going to put a "RegistrationAct" when I model, e.g., an "Approval" and put the "Approval Number" (id that business people recognize) into the Act.id. I also disagree with the renumbering. And I am burned and opposed against multiple ids. They cause very nasty aliasing effects in the database.
  
 
=== Notes ===
 
=== Notes ===
Line 53: Line 69:
  
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Disagree with this. "Reorganization of ids" doesn't make sense. Once an identifier is assigned, it's assigned.
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Disagree with this. "Reorganization of ids" doesn't make sense. Once an identifier is assigned, it's assigned.
 +
 +
--[[User:Grahamegrieve|Grahamegrieve]] 07:36, 18 February 2009 (UTC) Of course. But if you have to re-org your identifiers (say, doing a system upgrade), you may need to assign new identifiers as well.
  
 
2. The technical identifiers do not include any unverified ids
 
2. The technical identifiers do not include any unverified ids
Line 61: Line 79:
 
   
 
   
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Not sure exactly what this means. If you're using an identifier as a reference, and are supplementing it with other cross-reference information, I don't see why it needs to be verified. There should be no issue sending a patient id, name, date of birth and gender over the wire even if you haven't looked at the patient's documents.
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Not sure exactly what this means. If you're using an identifier as a reference, and are supplementing it with other cross-reference information, I don't see why it needs to be verified. There should be no issue sending a patient id, name, date of birth and gender over the wire even if you haven't looked at the patient's documents.
 +
 +
--[[User:Grahamegrieve|Grahamegrieve]] 07:36, 18 February 2009 (UTC) Well, how can you treat an identifier that a user entered with no further checking as a technical id? What is your use case for doing so? But having said that, this is probably a SHOULD NOT not a SHALL NOT
  
 
3. The technical identifiers should not include business ids
 
3. The technical identifiers should not include business ids
Line 74: Line 94:
  
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Business ids are perfectly acceptable for acts and roles. The only time to avoid business ids on acts is if you expect multiple systems to be asserting ids for the same act. However, if you've got one authoritative id, there's no reason not to put that on the act or role.
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Business ids are perfectly acceptable for acts and roles. The only time to avoid business ids on acts is if you expect multiple systems to be asserting ids for the same act. However, if you've got one authoritative id, there's no reason not to put that on the act or role.
 +
 +
--[[User:Grahamegrieve|Grahamegrieve]] 07:36, 18 February 2009 (UTC) No no, you are thinking of OBJ identifiers, not BUSN identifiers. BUSN business ids don't make good technical identifiers. Again, this is SHOULD NOT not SHALL NOT
  
 
4. If the object carries human readable identifiers, the otherIds class should be used
 
4. If the object carries human readable identifiers, the otherIds class should be used
Line 87: Line 109:
  
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Type is only necessary if the usecase for conveying the identifier is for human display.  The fact that the identifier is human readible itself is irrelevant.  If the target is a computer system (e.g. tying an order to a particular patient), the id type is irrelevant.  All that matters is that the id resolves down to a single object and has sufficient agreeing verification information that the computer system can be confident it's got the right one.
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) Type is only necessary if the usecase for conveying the identifier is for human display.  The fact that the identifier is human readible itself is irrelevant.  If the target is a computer system (e.g. tying an order to a particular patient), the id type is irrelevant.  All that matters is that the id resolves down to a single object and has sufficient agreeing verification information that the computer system can be confident it's got the right one.
 +
 +
--[[User:Grahamegrieve|Grahamegrieve]] 07:36, 18 February 2009 (UTC) well, if it's for display, or if anyone says the magic words "what type of identifier is this?"
  
 
5. The otherIds class must have a single identifier
 
5. The otherIds class must have a single identifier
Line 101: Line 125:
  
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) I agree that entity ids tend to need type if you're displaying them for humans. However, this isn't generally true of act ids. Act ids don't have "types". They simply identify the act.
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) I agree that entity ids tend to need type if you're displaying them for humans. However, this isn't generally true of act ids. Act ids don't have "types". They simply identify the act.
 +
 +
--[[User:Grahamegrieve|Grahamegrieve]] 07:36, 18 February 2009 (UTC) Perhaps we do need to differentiate between the typical act patterns and the typical role/entity patterns.
  
 
7. The otherIds class should have a status and a validTime
 
7. The otherIds class should have a status and a validTime
Line 111: Line 137:
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) I'd treat this as a MAY, not a SHOULD. It depends entirely on the usecase. Saying "Their library card # is 123456" may be completely sufficient. The fact that it expired two years ago is rarely relevant. Remember that the effective time of the role or act is completely distinct from the uniqueness period of the id. The id *should* be globally unique across all time if it's compliant. If not, you use the validTime within the II type. The time conveyed on the act or role merely reflects when the act was ongoing or when the person held the role, which is a far shorter timeperiod than when the role was active. You only need to convey this information if the usecase suggests the person might have a need for it.
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) I'd treat this as a MAY, not a SHOULD. It depends entirely on the usecase. Saying "Their library card # is 123456" may be completely sufficient. The fact that it expired two years ago is rarely relevant. Remember that the effective time of the role or act is completely distinct from the uniqueness period of the id. The id *should* be globally unique across all time if it's compliant. If not, you use the validTime within the II type. The time conveyed on the act or role merely reflects when the act was ongoing or when the person held the role, which is a far shorter timeperiod than when the role was active. You only need to convey this information if the usecase suggests the person might have a need for it.
  
 
+
--[[User:Grahamegrieve|Grahamegrieve]] 07:36, 18 February 2009 (UTC) II only has a valid time from HXIT<II>. I think that invalidates your argument.
  
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) This pattern is missing assigning authority name - Who is asserting the id, be it for an act (author of the registration) or entity (scoper for the role).  Also, I don't think the role necessarily has to have type IDENT.
 
--[[User:Lmckenzi|Lmckenzi]] 15:33, 14 May 2008 (CDT) This pattern is missing assigning authority name - Who is asserting the id, be it for an act (author of the registration) or entity (scoper for the role).  Also, I don't think the role necessarily has to have type IDENT.
  
 
== Measurement Pattern ==
 
== Measurement Pattern ==
 
''do I really have to use stinkin’ UCUM?''
 
  
 
Requirements:
 
Requirements:
 
* PQ only handles value and unit (See PQ Triad in Abstract Data Types)
 
* PQ only handles value and unit (See PQ Triad in Abstract Data Types)
* Unit is strictly a UCUM code not an estimated measure
+
* Unit is strictly a UCUM code  
 
* The context of use must specify what is measured
 
* The context of use must specify what is measured
* The context of use must allow a notional qualifier (“kind of measurement” - scoop, cup, etc)
+
* If estimated portions are specified (e.g., 2 scoops, 2 good measures, etc.) then make the "scoopful" or "good measure" and Entity and count it -- no need for a unit of measure.
  
 
UML for the pattern (TODO: replace with an observation example)
 
UML for the pattern (TODO: replace with an observation example)
Line 130: Line 154:
  
 
Notes:
 
Notes:
* Measurements should always be identified
+
* Kind of quantity (Observation.code) should always be identified, therefore
* Measurements should always have a code : CD
+
* measurements should always have a code : CD
* Unless the units are fixed, the measurement needs some “measurement QualifierCode”
 
* Measurements should always have a methodCode (optional)
 
  
 
== Relative Timing Pattern ==  
 
== Relative Timing Pattern ==  

Latest revision as of 16:09, 1 October 2009

Introduction

This hot topic concerns the notion that there are a number of common design patterns that should be well known to the v3 model designers, and should be used where appropriate.

MnM needs a process to gather these patterns, publish them in one place, and have a process that draws the attention of the target model designers to the patterns.

Patterns

Note: These patterns are highly controversial and are offered as examples to start debate, not to serve as exemplary patterns that should be used.

Identifier Pattern

Where’s identifier type?

Requirements:

  • We need multiple technical identifiers (different scopes, data model re-organizations)
  • We also need multiple human readable identifiers for some things
  • For these, we need to know what real world concept they match to
  • II is just a technical identifier

UML for the general pattern

  • --Ioana13 16:09, 1 October 2009 (UTC) Does OtherIds contain Thing or the other way around?

IIPattern.png

Entity-Role Equivalent

II-pattern-entity.gif

Descriptions

The following is a set of 'boiler plate' language for inclusion in models that follow the identifier pattern

anEntity.id (Primary identifier): This identifies the primary object identifier for the object as used by the author of the instance. Multiple repetitions are allowed to support conveying "version" and "snapshot" ids where these are necessary. However, alternate identifiers must not be sent in this structure.

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

IdentifiedEntity.code (Identifier type): This identifies the "kind" of identifier present.

IdentifiedEntity.statusCode (Identifier status): Identifies whether the specified identifier is considered to be active (still usable) for the entity.

IdentifiedEntity.effectiveTime (Identifier timerange): Indicates the period of time over which the identifier is considered to be valid.

Act-ActRelationship Equivalent

II-pattern-act.gif

--Lmckenzi 16:20, 24 September 2009 (UTC) This diagram does not convey the correct semantics. EffectiveTime identifies the time the act is effective and has no relationship to the validity of the identifier. Same thing with status. As well, the author participation indicates what type of entity authored the act, not what type of identifier the act has.

--Gschadow 23:18, 24 September 2009 (UTC) This pattern is very confusing and the little I understand of it I completely disagree. I'm not going to put a "RegistrationAct" when I model, e.g., an "Approval" and put the "Approval Number" (id that business people recognize) into the Act.id. I also disagree with the renumbering. And I am burned and opposed against multiple ids. They cause very nasty aliasing effects in the database.

Notes

1. The technical id (Thing.id/anEntity.id/anAct.id) should always SET<II> (or DSET<II> in Data types R2)

The reason for making this a set rather than a singleton is similar to the argument for not using CV: fixing it to a single II will prevent organisations from ever re-organising their persistent identification mechanisms. Note - this is not about reassigning OIDs - SET<> is not required for this use case.

If there is some case where this clearly doesn't apply, then SET<> is not needed. HL7 provides no clarification whether all or just one of the ids must be matched, but for real world usage, it should just be one. This should be clarified in narrative.

--Lmckenzi 15:33, 14 May 2008 (CDT) Disagree with this. "Reorganization of ids" doesn't make sense. Once an identifier is assigned, it's assigned.

--Grahamegrieve 07:36, 18 February 2009 (UTC) Of course. But if you have to re-org your identifiers (say, doing a system upgrade), you may need to assign new identifiers as well.

2. The technical identifiers do not include any unverified ids

This is fairly straight forward: unverified IDs are always human identifiers not technical identifiers, as their provenance (usually a user typing in the system directly) can never be ascertained. Note that the notion of unverified ids is introduced in R2.

--Lmckenzi 15:33, 14 May 2008 (CDT) Not sure exactly what this means. If you're using an identifier as a reference, and are supplementing it with other cross-reference information, I don't see why it needs to be verified. There should be no issue sending a patient id, name, date of birth and gender over the wire even if you haven't looked at the patient's documents.

--Grahamegrieve 07:36, 18 February 2009 (UTC) Well, how can you treat an identifier that a user entered with no further checking as a technical id? What is your use case for doing so? But having said that, this is probably a SHOULD NOT not a SHALL NOT

3. The technical identifiers should not include business ids

In general, ids are labelled as business ids because they are re-used to identify multiple objects of different classes that are linked by a common business process. An example is the notion of an order number - it may be associated with several different acts in different moods (there might be another pattern there). Because the scope in which the technical identifiers are used for matching is not defined (and is supposed to be globally unique), it is potentially dangerous to allow business identifiers as technical identifiers. If it is done, the scope of the matching of the technical identifiers should be clearly identified in the narrative, and the nature of the use of the business identifiers should be clearly identified.

--Lmckenzi 15:33, 14 May 2008 (CDT) Business ids are perfectly acceptable for acts and roles. The only time to avoid business ids on acts is if you expect multiple systems to be asserting ids for the same act. However, if you've got one authoritative id, there's no reason not to put that on the act or role.

--Grahamegrieve 07:36, 18 February 2009 (UTC) No no, you are thinking of OBJ identifiers, not BUSN identifiers. BUSN business ids don't make good technical identifiers. Again, this is SHOULD NOT not SHALL NOT

4. If the object carries human readable identifiers, the otherIds class should be used

In the context of RIM modeling, this means a Role or an ActRelationship pattern as shown above. Human readable identifiers always carry meaning, and the meaning should generally be conveyed. Inherent in this pattern is that some identifiers may be carried twice - once as a technical id and once as a human readable identifier. Although there is technical duplication, this clearly defines the dual roles that the identifier plays.

If this pattern is not used, implementors will be forced to use a variety of dirty tricks to convey the type of the identifier, which is generally necessary in an implementation environment.

--Lmckenzi 15:33, 14 May 2008 (CDT) Type is only necessary if the usecase for conveying the identifier is for human display. The fact that the identifier is human readible itself is irrelevant. If the target is a computer system (e.g. tying an order to a particular patient), the id type is irrelevant. All that matters is that the id resolves down to a single object and has sufficient agreeing verification information that the computer system can be confident it's got the right one.

--Grahamegrieve 07:36, 18 February 2009 (UTC) well, if it's for display, or if anyone says the magic words "what type of identifier is this?"

5. The otherIds class must have a single identifier

This identifier is that human readable identifier. Generally it would be expected to have an extension in the II. Duplicate identifiers are not required and would be confusing.

6. The otherIds class must have a Id type (somewhere in it's associations)

So the users can mark up the type. There's some doubt about quite what the best form of the type attribute is. In some cases the type is not very useful and the identifier of the provider of the identifier is required. Comment required

--Lmckenzi 15:33, 14 May 2008 (CDT) I agree that entity ids tend to need type if you're displaying them for humans. However, this isn't generally true of act ids. Act ids don't have "types". They simply identify the act.

--Grahamegrieve 07:36, 18 February 2009 (UTC) Perhaps we do need to differentiate between the typical act patterns and the typical role/entity patterns.

7. The otherIds class should have a status and a validTime

The notion is not that this id will be reused for another object (that would be BAD), but that the id has a limited period of validity (perhaps there was a duplicate record, and it's now retired). This is not required but is a relatively harmless addition to an actual model.

--Lmckenzi 15:33, 14 May 2008 (CDT) I'd treat this as a MAY, not a SHOULD. It depends entirely on the usecase. Saying "Their library card # is 123456" may be completely sufficient. The fact that it expired two years ago is rarely relevant. Remember that the effective time of the role or act is completely distinct from the uniqueness period of the id. The id *should* be globally unique across all time if it's compliant. If not, you use the validTime within the II type. The time conveyed on the act or role merely reflects when the act was ongoing or when the person held the role, which is a far shorter timeperiod than when the role was active. You only need to convey this information if the usecase suggests the person might have a need for it.

--Grahamegrieve 07:36, 18 February 2009 (UTC) II only has a valid time from HXIT<II>. I think that invalidates your argument.

--Lmckenzi 15:33, 14 May 2008 (CDT) This pattern is missing assigning authority name - Who is asserting the id, be it for an act (author of the registration) or entity (scoper for the role). Also, I don't think the role necessarily has to have type IDENT.

Measurement Pattern

Requirements:

  • PQ only handles value and unit (See PQ Triad in Abstract Data Types)
  • Unit is strictly a UCUM code
  • The context of use must specify what is measured
  • If estimated portions are specified (e.g., 2 scoops, 2 good measures, etc.) then make the "scoopful" or "good measure" and Entity and count it -- no need for a unit of measure.

UML for the pattern (TODO: replace with an observation example)

PQPattern.png

Notes:

  • Kind of quantity (Observation.code) should always be identified, therefore
  • measurements should always have a code : CD

Relative Timing Pattern

Can I have a new EIVL code

i.e. ... “draw CBC 5 days after TreatmentStartDate”

Requirements:

  • Need to express that some event happens at a time relative to some other event
  • Need to identify the other event specifically (by identifier, or by pattern)
  • Need to specify how long between the two events as time, possibly with some form of uncertainty
  • Must be computable

UML for the pattern (TODO: replace with proper Act/ActRelationship examples)

EIVLPattern.png

Notes:

  • the definition of pauseQuantity needs to be adjusted to allow this pattern