Common Design Patterns

From HL7Wiki
Jump to navigation Jump to search

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