Package oracle.hsgbu.hdr.hl7

Contains RIM-specific classes, types, and services for persisting and querying of RIM data.

See: Description

Interface Summary

Interface	Description
RimService	Provides methods to persist and query RIM objects in HDR.

Package oracle.hsgbu.hdr.hl7 Description

Contains RIM-specific classes, types, and services for persisting and querying of RIM data.

Overview

Persistence and querying of RIM objects in HDR is performed by the submit method on RimService. Both actions require a ControlAct to be created and for the ControlAct to contain a subject ActRelationship to an Act subclass. The HL7 package provides the QueryAct interface for querying objects in HDR.

Factory Classes

Classes in the Factories package provide factory methods for creating instances of all RIM classes and data types. The new keyword should never be used to construct instances of HDR classes.

Persisting RIM Objects

The following example shows how to persist a Person object in HDR.

    // Get the RIM service
    RimService rimService = serviceLocator.getRimService();
    DataTypeFactory dataTypeFactory = DataTypeFactory.getInstance();
    ActFactory actFactory = ActFactory.getInstance();
    
    // Create the control act, providing a trigger event.
    // The control act's class code must be CACT to be accepted by the
    // submit method
    CD triggerActCode = dataTypeFactory.newCD("PRPA_TE000001", "2.16.840.1.113894.1004.100.100.2.5");
    
    ControlAct controlAct = actFactory.newControlActEvent(triggerActCode, null);
    
    // Create the registry act. Registry acts are used to denote a
    // registration of a Role or Entity, in this case a person Entity.
    // The registry act's class code is REG, the mood code for a
    // registry act is typically EVN.
    // The registry act will later be associated with the control act
    // using an act relationship
    
    Act act  = actFactory.newRegistryAct(ActMood.EVN, dataTypeFactory.nullCE(NullFlavor.NP), null);
    act.setTitle(dataTypeFactory.newST("Registration Act"));
    
    // Create an II for the person.
    // If a person with the given II is found it will be updated
    // otherwise a new person will be created.
    SET_II m_setId = dataTypeFactory.newSET_II("2.16.840.1.113883.3.1.123121246", "AB12349876", true);
    // Create the person entity, setting some nominal values for name
    // and address
    EntityFactory entityFactory = EntityFactory.getInstance();
    Person person =  entityFactory.newPerson(
        dataTypeFactory.nullCE(NullFlavor.NP), 
        EntityDeterminer.INSTANCE, m_setId);
    
    // Create the EN datatype for the person's name
    ENXP[] namePartArray = new ENXP[] {
        dataTypeFactory.newENXP("Adam", null, null),
      dataTypeFactory.newENXP("Everyman", null, null)
    };
    
    EN name = dataTypeFactory.newEN(namePartArray,
                                    dataTypeFactory.newSET_CS(dataTypeFactory.newCS("L")),
                                    null);
    
    EN[] nameArray = new EN[] { name };
    BAG_EN nameBag = dataTypeFactory.newBAG_EN(nameArray);
    person.setName(nameBag);
    
    // Add the status code. Status codes are validated against state
    // transitions defined by HL7 and against master catalog for the
    // focal class of the submission.
    person.setStatusCode(EntityStatus.ACTIVE);
    
    // Add the administrative gender
    // using 2.16.840.1.113883.5.1 as OID for AdministrativeGender coding scheme
    person.setAdministrativeGenderCode(dataTypeFactory.newCE("M", "2.16.840.1.113883.5.1"));
    
    // Create an address using the AD type
    ADXP addrPart1 = dataTypeFactory.newADXP("CA", dataTypeFactory.newCS("CNT")); //country
    ADXP addrPart2 = dataTypeFactory.newADXP("B.C", dataTypeFactory.newCS("STA")); //state
    ADXP addrPart3 = dataTypeFactory.newADXP("Missisauga", dataTypeFactory.newCS("CTY")); //city
    ADXP addrPart4 = dataTypeFactory.newADXP("8M3C5V", dataTypeFactory.newCS("ZIP")); //postal code
    ADXP addrPart5 = dataTypeFactory.newADXP("123 Fake St.", dataTypeFactory.newCS("SAL")); //street
    
    ADXP[] addrPartArray = new ADXP[] {
      addrPart1,
      addrPart2,
      addrPart3,
      addrPart4,
      addrPart5
    };
    
    AD addr = dataTypeFactory.newAD(addrPartArray,
                                    dataTypeFactory.newSET_CS(dataTypeFactory.newCS("H")),
                                    dataTypeFactory.nullGTS(NullFlavor.NP));
    BAG_AD addrBag = dataTypeFactory.newBAG_AD(new AD[] { addr });
    
    // Add the address to the person
    person.setAddr(addrBag);
    
    // Create an identified entity Role as a container for the Entity.
    // The identified entity Role's class code is IDENT.
    // In this example the person is given as the player of the Role
    // and the scoper is omitted
    RoleFactory roleFactory = RoleFactory.getInstance();
    Role role = roleFactory.newIdentifiedEntity(null, person, null, null);
    
    // Create a Participation between the registry act and the
    // identified role
    act.addParticipation(ParticipationType.SBJ, role);
    
    // Create an outbound Act Relationship between the control act
    // and registry act
    ActRelationship ar = controlAct.addOBActRelationship(ActRelationshipType.SUBJ, act);
    
    // Submit the control act. The returned control act will be
    // null unless a query act was specified in the act relationship
    // on the control act
    ControlAct returnedControlAct = rimService.submit(controlAct);

Master Catalog Validation

All RIM objects are validated against the master catalog, which defines the allowable class code, mood code, code, player, and/or scoper for Act, Role, and Entity objects. See Mastercatalog for more details.

RIM Object Versioning

All RIM objects stored in HDR are versioned. This means that a history of each object's state is maintained and can be retrieved through HDR. A new version of a record can be created by first querying the record and then calling the createNewVersion method on the object.

Once the version of an object has been persisted, the attributes of that version of the object are immutable. Any subsequent update to the object must follow a call to the createNewVersion method, which creates a new version. While it is possible to create and/or update attributes using an appropriate ReferenceModier the immutability of a specific version's attributes is maintained.

See the Versioned interface for more details.

Automatic Carry-over of Participation and ActRelationship objects

When creating new versions of objects, particularly Act objects, HDR will attempt to carry any ActRelationship and Participation objects over to the newly created version. This facility is provided because updates to Act objects often need to maintain associations to Act or Role objects from the previous version.

The following example shows this behavior in a clinical scenario:

An order is entered for a SBADM.RQO medication, digoxin, where the dose is 0.125 mg and the route is oral. The consumable (CON) participation to the manufactured product role (MANU) is played by a manufactured material (MMAT). There may be an SBJ participation to the patient role, and an AUT participation to an assigned Role.

A subsequent update represents the action of placing an active order on "hold". The submission needs to create a new version of the order with the status changed from "active" to "suspended". The ActRelationship and Participation objects associated with the order are associated with the new version.

A third version of the order "releases" the suspended order. This submission has a status change from "suspended" to "active" for the order. The ActRelationship and Participation objects are automatically associated with the new version of the order.

ActRelationship and Participation objects that should not be carried over from version to version must be explicitly removed from the Act being submitted. To remove, call the remove method on the Iterator returned by the Act methods that allow traversal to ActRelationship and Participation objects. Some points to note about this process are:

• The ActRelationship or Participation objects being removed must have been returned by the query on the Act. This ensures that the ActRelationship or Participation object is present in the Iterator.
• ActRelationship objects must be removed from the owning Act. The owning Act is deemed to be the Act upon which the ActRelationship was originally added, regardless of whether the ActRelationship is inbound or outbound.

If several ActRelationship and Participation objects are removed from version to version, consider using overlay references, which can be created using the makeReference method available on the factory classes.

II Processing

While persisting objects, HDR always adds an additional II. IIs are added to objects after the call to submit, not on the call to the Act, Role or Entity Factory. This additional II has a root as returned by getInternalOID and an extension dictated by an internal sequence. The extension is not guaranteed to be consecutive.

In HDR, IIs encompass all versions of an object such that the addition of an II to a version of an object is available on all previous and all future versions of that object. This behavior is different from the usual behavior of attributes of a versioned object. HDR does, however, allow queries to determine on which version of the object the II was originally set.

Concept List Validation

HDR validates certain rim attributes against lists of concepts registered with the Terminology Server. For details of attribute validation please refer to the appropriate object's javadoc. Such validation occurs in the call to submit().

Additionally, HDR validates datatype properties against concept lists. This validation also occurs during the call to submit().

The following table details concept list validation for datatype properties.

Datatype	Property	List
AD	use	CL_AD_USE
ADXP	partType	CL_ADXP_PART_TYPE
ED	compression	CL_ED_COMPRESSION
ED	integrityCheckAlgorithm	CL_ED_INTEGRITY_CHECK_ALGORITHM
ED	representation	CL_ED_REPRESENTATION
EIVL	event	CL_EIVL_EVENT
EN	use	CL_EN_USE
ENXP	partType	CL_ENXP_PART_TYPE
ENXP	qualifier	CL_ENXP_QUALIFIER
MO	currency	CL_MO_CURRENCY
PIVL	alignment	CL_PIVL_ALIGNMENT
TEL	use	CL_TEL_USE
TS	calendar	CL_TS_CALENDAR

To see more concept lists, please see the Concept List Index.

Querying RIM Objects

HDR provides a robust set of querying options for the retrieval of persisted data. The Query package provides an overview for the usage of the retrievals APIs.

Document References

Health Level Seven, Inc. asserts and retains copyright and intellectual property rights in all works contributed by its members and non-members, relating to all versions of the Health Level Seven (HL7) standards and related materials - including all of the publications referenced in the hl7 package and its sub-packages.