This project has moved and is read-only. For the latest updates, please go here.

Logical Data Model

This section seeks to describe and discuss the methodology behind the OpenIZ data design and to describe the logical data design and schema. Note that the logical data design is often different from the physical schema as the physical schemata are adapted for the restrictions of the RDBMS in which they operate. The logical data design is also separate from the business data model design though the concepts are translatable.


The OpenIZ data model can be described as a series of component or packages. These packages are used to logically describe the how the entirety of the IZTW data model functions. The logical groups within the OpenIZ data model can be described as:

  • Security Tables: Security tables are primarily used for the purpose of securing the OpenIZ data and enforcing of policies. OpenIZ’s policy system is described in the solution architecture section of this document. Security tables also deal with users in roles.
  • Clinical Tables: These tables represent the primary way in which clinical data is stored. The OpenIZ clinical data model is a derivation of the HL7® Reference Information Model (RIM). The HL7 RIM can be described as a series of base classes describing all events as “entities playing roles participating in acts”. Where:
    • Entities: An entity represents a person, place, organization, or thing (syringe, antigen, vaccine, etc.). Entities can be related to one another via an entity relationship such as place belonging to an organization or series of materials belonging to a vaccination kit.
    • Roles: Roles represent a type of part an entity plays. For example, a Person entity may play the role of a provider or a patient.
    • Participations: Participations are the link between an act and an entity via a role. A participation is used to describe how an entity participates in the carrying out of an act.
    • Acts: An act represents an action performed. An example of an Act may be an encounter the patient has with a provider to receive a weight or immunization. Acts may be related to one another, for example an encounter may fulfill an appointment, or an observation may be a part of an encounter.
  • Stock Management Tables: These tables represent a series of ledgers for each of the “places” represented in OpenIZ. Stock management tables primarily deal with tracking transfer orders to/from places and organizations.
  • Protocol / Workflow Tables: These tables represent metadata that is used by forecasting and DSS tools to enforce vaccination protocols. Patients are enrolled into a series of protocols or workflows that can be used to track adherence to best practices.
  • Concept Tables: These tables are used to control the vocabulary used within the OpenIZ data model. OpenIZ uses a series of core concepts in the clinical tables and the concept tables permit the mapping of these internal OpenIZ concepts to wire-level codes in HL7® FHIR™, or HL7® CDA™.


All data tables in OpenIZ are versioned. This includes everything from display names of concepts, entities, acts, etc. This versioning allows an administrator to view a record as it was when it was created by a clinician.

This is important not only for a medical/legal reason, but for understanding why an action was taken and/or submitted. The versioning of major elements is performed using a few core concepts:

  • Object Table: The core table contains the object’s identifier and any immutable attributes of the object. For example, the Entity table contains the immutable “class code” attribute in the object table.
  • Object Version Table: The object version table contains the object’s versioned attributes. That is, attributes which may change over the lifetime of the object. Each version is assigned a unique identifier. The version table also keeps track of version history via a replaces column so that versions are linked to one another.
  • Associative Tables: All associative tables to a versioned object carry an EffectiveVersionId and ObsoleteVersionId which allow the OpenIZ queries to establish whether a relationship was active at a particular time an action was taken, and also allows OpenIZ to establish the user which was responsible for adding/removing the association.

Some tables are versioned in a different manner; these tables are typically tables where versioning is not as important for tracing purposes. These tables typically have a CreationTime/CreatedBy and ObsoletionTime/ObsoletedBy column and may have a pointer to a previous record that represents an edit.

The key message is that no UPDATE statements are (and should never) be performed on the OpenIZ database.

Tags and Extensions

Often times there are country specific requirements that cannot be stored in the default OpenIZ data model. The data model has two methods of storing and reproducing such data.

Tags represent version independent, non-structural data associated with an Act or Entity. Tags are often used for tagging workflow values associated with an Act (such as editing approval process), security tags, and/or attachments. Tags are primarily used for storing metadata.

Extensions are structural attributes that modify the meaning of an Act or Entity. Extensions differ from tags in that they add meaning to an entity or act, and thus, are versioned. Extensions can be thought of as representing data specifically associated with the entity. Examples of extensions include 10-cell address of a patient, a stock consumption policy of a place. Extensions should be used in the last resort, when no other mechanism exists to store the data in the natural data model.

Overall Data Model

Because the OpenIZ data-model is designed to be flexible, it can be overwhelming at first. In order to increase the readability of the entities, the logical concepts found in the data model can be color coded as:

  • Entities – Yellow
  • Roles – Green
  • Participations – Orange
  • Acts – Red
  • Security – Purple
  • Concepts – Blue
  • Stock – Gold
  • Others – White







The entity table provides a master list of all entity data within the data model. This table is used to store attributes related to the abstract superclass “Entity”.



The entity version table provides data related to the versioning of entity data within the OpenIZ system. All key entity attributes (minus classification) are stored in the entity version table.



The entity telecommunications address table provides a 1..n relationship through which telecommunications addresses (email addresses, phone numbers, fax numbers, etc.) can be stored and related to a particular entity version.



The telecommunications address type table is used to store data related to the type of telecommunications addresses used. This can be configured so that handlers may “contact” these addresses.



The entity address table is used to store addresses that are related to a particular entity. These addresses may include physical addresses, mailing addresses such a PO Boxes, etc.



The entity address component table is used to store the component pieces of an entity address. These components may include the street address, city, village, zip code, geo-locator, etc. All address components are phonetically searchable.



The entity name table is used to store 1..n names related to an entity. An entity name may be a place name such as “Good Health Hospital”, a person name such as “Legal”, “Maiden”, etc.



The entity name component table is used to store the components of an entity name. These may include the given, family, suffix or prefix portions of a name.



The entity name use table is used to store a master list of allowed uses of an entity name. This table is also responsible for ensuring that an appropriate name use is used in conjunction with the associated entity. For example, a “Person” entity name may not use an “Organizational” name use.



The entity identifier table is used to store a list of 1..n identifiers associated with an entity. An entity identifier can be thought of in many ways, for example:

-          An MRN for a Patient

-          A GTIN or UPC for a Material

-          An OU name for an Organization

-          A license number for a Provider



The entity identifier type table is used to identify how an entity identifier is to be used and selected. An example, a GTIN entity identifier type may not be used with a Person entity as a Person does not carry a GTIN.



An assigning authority an a globally unique domain identifier which qualifies which system, organization or authority has the ability to assign new identifiers within a domain. An example of an assigning authority may be a system which generates MRNs, a jurisdictional EMPI, a global trade organization, etc.



An entity extension represents a non-classified, extended field for the entity. Extension fields are used primarily to store data related to an entity that does not belong in the standard OpenIZ datastore. For example, there may be a jurisdictional requirement to store the Race or EthnicGroup of a Person.



An entity extension type qualifies the type of extension represented in the EntityExtension table. The type identifies an extension handler responsible for de-persisting the data.



An entity tag represents a simple Key/Value pair data that is version-independent for a particular entity, that is to say that the updating of the tag does not produce a new version of the entity. Tags can be used for things like workflow tagging, quarantine control, or any other application specific use.



The person table is used to store data related to the Person subclass of the Entity superclass.



Identifies the languages of communication in which the person can be contacted.



The Patient table is used to store data related to the Patient subclass of the Person superclass. The patient table adds fields for date of birth, multiple birth order, deceased time, etc.



The provider role table is used to store data related to the provider subclass of the Person superclass.



An Organization is a table used to store data related to the Organization subclass of the Entity superclass. An organization represents a legal entity, which is not a person, who has a mandate to deliver healthcare.



A Place is a table used to store data related to a physical place where care is delivered.



The PlaceService table is used to store data related to the services available at a particular place. The services in the scope of OpenIZ may represent immunization services, weight services, emergency services, etc.



The Material table is used to store data related to the Material subclass of the Entity superclass. A material represents a physical thing or supply that is used in the delivery of care. This can include syringes, diluents, vaccines, kits, gloves, etc.



A manufactured material represents a material that can be ordered from a manufacturer. This includes syringes, diluents, gloves, etc. This is a specialization for a Material in that a material can technically be a self-assembled group of materials which may not necessarily be orderable by a manufacturer (for example: a vaccine kit which is an administrative material)



Represents an association between two materials with the option to specify the number of source units contained in a target unit.



The entity association table is used to associate entities to one another. This can be used in a variety of ways including

-          Linking places to an organization

-          Linking materials together in a kit

-          Linking persons together, for example a mother/father of a patient

-          Linking places together in an administrative hierarchy.

-          Linking providers with patients.



The ActParticipation associative entity class is used to associate a particular version of an act with a version of an entity participating in the act. Example of participations include : RecordTarget, Author, Performer, Subject, etc.



The Act table is used to store the abstract data related to a particular act.



The ActVersion table is used to store abstract data related to a particular point-in-time version of an Act or subclass of an act.



The ActRelationship table is used to link two acts together in some way. Examples of an ActRelationship include fulfillment (i.e. an encounter fulfills an appointment), componentization (i.e. encounter has an observation), etc.



The SubstanceAdministration table is used to store the administration of substances (like vaccines) to the patient.



The Observation table is used to store additional data related to an observation that occurs during the course of an encounter.



The QuantityObservation table is used to store additional data related to an observation whose value is a quantity. For example, an observation of weight, blood pressure, height, etc.



The CodedObservation table is used to store additional data related to an observation whose value is a code. For example, observing the patient has blue eyes.



The TextObservation table is used to store additional data related to observations which have textual content such as observation



The PatientEncounter table is used to store additional data related to an encounter that the patient has with the health system. For example, an encounter may represent a single fulfillment of 6 week vaccinations.



The ActTag table represents a series of version independent metadata tags applied to the act. These can be workflow, security or categorization tags.



The ActExtension table represents a series of extended data elements that can assigned to an act’s version. This can be to store additional data related to the act itself not representable in the core data framework.



The stock ledger is used to store stock transactions (like a bank account) performed against a Place’s stock level. A stock ledger has a 1..1 mapping to a deduction, deposit or transfer of materials between places.



The stock balance table is used to store a running total or balance of a material at a particular place.



A stock order represents a special type of Act (a non-clinical act) which is a request to order stock to/from a place. Mood codes for this include:

-          Propose – When a planning function proposes an order

-          Intend – When an order should be placed

-          Event – When an order has been placed



A quantified act participation is a specialization of an act participation that has the ability to convey the number of entities participating in the act. In particular, quantified act participations represent entities which are classes instead of instances of entities.



Represents a specialization of an entity association whereby the container entity has a specified number of Source in Target entity.

Last edited Jan 13, 2016 at 7:47 PM by jf03cg, version 3