TRIM Update Semantics

From DOC

Updates involving a TRIM can work either of two ways:

1. trim to trim (document-style)
2. trim to placeholder to trim (transaction-style)

The latter is more flexible but is a little harder to configure. Both methods provide the same level of security and audit trail.

Document-style

When you update a trim in the document-style, the trim to be updated is copied and a new "event" menu data item is created. Since the original trim was used as the source for the new trim, you can be pretty certain that the new trim at least starts with the contents of the original trim. When instantiated, you'll notice that the new trim has two (or more) Tolven event entries, the first one being the most recent. This provides a history of the Trim - one can navigate to each trim leading to the current Trim. (Note: This history is of a single observation as a single point in time - that is, it shows revisions of that one observation. Recording the patient's weight at two different times would be two completely different trims, not a revision of a single trim).

<trim ...>
    ...
    <tolvenEventId timestamp="20090106093331+0000" status="completed" principal="bob" application="echr" path="echr:patient-15977665:observation-16401068" id="16401068" accountId="1972006"/>
    <tolvenEventId timestamp="20090106051554+0000" status="completed" principal="bob" application="echr" path="echr:patient-15977665:observation-16401057" id="16401057" accountId="1972006"/>
    <transitions path="trim.act.statusCodeValue">
        <transition to="completed" name="create">
            <label language="en">Completed</label>
        </transition>
        <transition to="active" from="active" name="reviseActive">
            <label language="en">Revise</label>
        </transition>
        ...
    </transitions>
    <transition>reviseCompleted</transition>
    <act moodCode="EVN" classCode="OBS">
        <bind phase="create" application="echr">

Trims are the source to create and update menu data items. One placeholder and one or more Events. Rules create appropriate list entries.

Transaction-style

In order to understand transaction-style, imagine that a placeholder gets created without a TRIM being involved. (The placeholder could have been created by a TRIM but a TRIM is not required). So, when it comes time to update the placeholder, no TRIM instance yet exists. Since there is no TRIM to begin with, it would be impossible to initialize the TRIM from the "original" TRIM. Patient demographics is a good example of this type of TRIM. To update the demographics, we create (instantiate) a brand new TRIM. The TRIM itself should "pull" appropriate information from the existing placeholder. If it doesn't, then the newly instantiated patient TRIM will, for example, not have the current patient's name.

So this type of TRIM must explicitly pull in placeholder data. Here's an example of how that is done:

  <player classCode="PSN" determinerCode="INSTANCE">
    <name>
      <label>Patient Name</label>
        <EN>
          <label>Legal Name</label>
          <use>L</use>
          <part>
            <label>First Name</label>
            <type>GIV</type>
            <ST>#{patient.firstName}</ST>
         </part>
         <part>
            <label>Middle Name</label>
            <type>GIV</type>
            <ST>#{patient.middleName}</ST>
         </part>
         <part>
           <label>Last Name</label>
           <type>FAM</type>
           <ST>#{patient.lastName}</ST>
         </part>
  ...

You'll see that the TRIM has to explicitly "pull" the placeholder elements it is interested in using EL. This is done as the new TRIM is created so that by the time it gets displayed, all of the current patient settings are in place.

 <EN>
   <label>Legal Name</label>
   <use>L</use>
   <part>
     <label>First Name</label>
     <type>GIV</type>
     <ST>Mary</ST>
   </part>
  <part>
    <label>Middle Name</label>
    <type>GIV</type>
    <ST>Candice</ST>
  </part>
  <part>
    <label>Last Name</label>
    <type>FAM</type>
    <ST>Abril</ST>
  </part>

Then, the UI can change these values in the instantiated TRIM. The update itself is the same as with Document mode: During update processing, the TRIM is used to populate the Placeholder with the potentially new values.

Since this type of TRIM gets created anew, it needs some way to know which placeholder it is to initialize from. We typically do this from the UI using an Ajax function that calls the intstantiate servlet supplying the placeholder id:

<a href="#" onclick="instantiate('reg/evn/patient','echr:patient-15977665:personal:identity','echr:patient-15977665')"...>

It is critical that this type of TRIM actually pull the placeholder id as well - so that the submit processing knows which placeholder to update. In this example, the patient role must have the patient placeholder path because that's where the application.xml will be looking for it:

   <id>
     <II>
       <root>#{computeIDRoot(account)}</root>
       <extension>#{patient.path}</extension>
     </II>

In summary, in the transaction style, different TRIMs (or no TRIM) can create or update a placeholder.