Directory Package

Overview

The directory package is illustrated below. It provides a simple abstraction of a versioned folder structure. The VERSIONED_FOLDER class is the binding of VERSIONED_OBJECT<T> to the class FOLDER, i.e. it is a VERSIONED_OBJECT<FOLDER>. This means that each of its versions is a Folder structure rather than a single Folder. It provides a means of versioning FOLDER structures over time, which is useful in the EHR, Demographics service or anywhere else where Folders are used to group things. A FOLDER instance contains more FOLDERs and/or items, which are references to other (usually versioned) objects. A FOLDER structure is therefore like a directory containing references to objects. Since they are references, multiple references to the same object are possible, allowing the structure to be used to mutiply classify other objects. If it is used with VERSIONED_COMPOSITIONs for example, the folders might be used to represent episodes and at the same time problem groups. Any individual Folder may contain meta-data in its details attribute (type ITEM_STRUCTURE), which may be archetyped in the same manner as similar attributes throughout the openEHR RM.

RM common.directory
Figure 1. common.directory Package

FOLDER structures inside the VERSIONED_FOLDER are archetypable structures, and FOLDER archetypes can be created in the same fashion as say SECTION archetypes for the EHR.

Paths

Directory paths are built using the name attribute values inherited from LOCATABLE into each FOLDER object. In real data, these will usually be derived from the value of the archetype_node_id attribute, plus a uniqueness modifier if required. Example paths (e.g. within the EHR):

    /folders[hospital episodes]/items[1]
    /folders[patient entered data]/folders[diabetes monitoring]
    /folders[homeopathy contacts]

Uniqueness modifiers are appended in brackets, and are only needed to differentiate folders at the same node that would otherwise have the same names, e.g.

    [hospital episodes]
    [hospital episodes(car accident Aug 1998)]

Class Descriptions

VERSIONED_FOLDER Class

  • Definition

  • Effective

  • BMM

  • UML

Class

VERSIONED_FOLDER

Description

A version-controlled hierarchy of FOLDERs giving the effect of a directory.

Inherit

VERSIONED_OBJECT
VERSIONED_FOLDER

A version-controlled hierarchy of FOLDERs giving the effect of a directory.

Inherits: VERSIONED_OBJECT

Attributes

VERSIONED_OBJECT.uid: HIER_OBJECT_ID [1..1]

Unique identifier of this version container in the form of a UID with no extension. This id will be the same in all instances of the same container in a distributed environment, meaning that it can be understood as the uid of the virtual version tree.

VERSIONED_OBJECT.owner_id: OBJECT_REF [1..1]

Reference to object to which this version container belongs, e.g. the id of the containing EHR or other relevant owning entity.

VERSIONED_OBJECT.time_created: DV_DATE_TIME [1..1]

Time of initial creation of this versioned object.

Functions

VERSIONED_OBJECT.version_count (): Integer [1..1]

Return the total number of versions in this object.

VERSIONED_OBJECT.all_version_ids (): List<OBJECT_VERSION_ID> [1..1]

Return a list of ids of all versions in this object.

VERSIONED_OBJECT.all_versions (): List<VERSION<T>> [1..1]

Return a list of all versions in this object.

VERSIONED_OBJECT.has_version_at_time (
a_time: DV_DATE_TIME[1]
): Boolean [1..1]

True if a version for time a_time exists.

VERSIONED_OBJECT.has_version_id (
a_version_uid: OBJECT_VERSION_ID[1]
): Boolean [1..1]

True if a version with a_version_uid exists.

VERSIONED_OBJECT.version_with_id (
a_version_uid: OBJECT_VERSION_ID[1]
): VERSION

Pre: has_version_id (a_ver_id) [1..1]

Return the version with uid = a_version_uid.

VERSIONED_OBJECT.is_original_version (
a_version_uid: OBJECT_VERSION_ID[1]
): Boolean

Pre: has_version_id(a_ver_id) [1..1]

True if version with a_version_uid is an ORIGINAL_VERSION.

VERSIONED_OBJECT.version_at_time (
a_time: DV_DATE_TIME[1]
): VERSION

Pre: has_version_at_time (a_time) [1..1]

Return the version for time a_time.

VERSIONED_OBJECT.revision_history (): REVISION_HISTORY [1..1]

History of all audits and attestations in this versioned repository.

VERSIONED_OBJECT.latest_version (): VERSION [1..1]

Return the most recently added version (i.e. on trunk or any branch).

VERSIONED_OBJECT.latest_trunk_version (): VERSION [1..1]

Return the most recently added trunk version.

VERSIONED_OBJECT.trunk_lifecycle_state (): DV_CODED_TEXT

Post: Result = latest_trunk_version.lifecycle_state [1..1]

Return the lifecycle state from the latest trunk version. Useful for determining if the version container is logically deleted.

VERSIONED_OBJECT.commit_original_version (
a_contribution: OBJECT_REF[1],
a_new_version_uid: OBJECT_VERSION_ID[1],
a_preceding_version_id: OBJECT_VERSION_ID[1],
an_audit: AUDIT_DETAILS[1],
a_lifecycle_state: DV_CODED_TEXT[1],
a_data: T[1],
signing_key: String[1]
): void

Pre: all_version_ids.has (a_preceding_version_uid) or else version_count = 0 [1..1]

Add a new original version.

VERSIONED_OBJECT.commit_original_merged_version (
a_contribution: OBJECT_REF[1],
a_new_version_uid: OBJECT_VERSION_ID[1],
a_preceding_version_id: OBJECT_VERSION_ID[1],
an_audit: AUDIT_DETAILS[1],
a_lifecycle_state: DV_CODED_TEXT[1],
a_data: T[1],
an_other_input_uids: List<OBJECT_VERSION_ID>[1],
signing_key: String[1]
): void

Pre: all_version_ids.has (a_preceding_version_uid) or else version_count = 0 [1..1]

Add a new original merged version. This commit function adds a parameter containing the ids of other versions merged into the current one.

VERSIONED_OBJECT.commit_imported_version (
a_contribution: OBJECT_REF[1],
an_audit: AUDIT_DETAILS[1],
a_version: ORIGINAL_VERSION[1]
): void [1..1]

Add a new imported version. Details of version id etc come from the ORIGINAL_VERSION being committed.

VERSIONED_OBJECT.commit_attestation (
an_attestation: ATTESTATION[1],
a_ver_id: OBJECT_VERSION_ID[1],
signing_key: String[1]
): void

Pre: has_version_id(a_ver_id) and is_original_version(a_ver_id) [1..1]

Add a new attestation to a specified original version. Attestations can only be added to Original versions.

Invariants

VERSIONED_OBJECT.Version_count_valid: version_count >= 0

VERSIONED_OBJECT.All_version_ids_valid: all_version_ids.count = version_count

VERSIONED_OBJECT.All_versions_valid: all_versions.count = version_count

VERSIONED_OBJECT.Latest_version_valid: version_count > 0 implies latest_version /= Void

VERSIONED_OBJECT.Uid_validity: extension.is_empty

 
{
    "name": "VERSIONED_FOLDER",
    "documentation": "A version-controlled hierarchy of `FOLDERs` giving the effect of a directory. ",
    "ancestors": [
        "VERSIONED_OBJECT"
    ]
}
VERSIONED_FOLDER

FOLDER Class

  • Definition

  • Effective

  • BMM

  • UML

Class

FOLDER

Description

The concept of a named folder.

It is strongly recommended that the inherited attribute uid be populated in top-level (i.e. tree-root) FOLDER objects, using the UID copied from the object_id() of the uid field of the enclosing VERSION object.
For example, the ORIGINAL_VERSION.uid 87284370-2D4B-4e3d-A3F3-F303D2F4F34B::uk.nhs.ehr1::2 would be copied to the uid field of the top FOLDER object.

Inherit

LOCATABLE

Attributes

Signature

Meaning

0..1

items: List<OBJECT_REF>

The list of references to other (usually) versioned objects logically in this folder.

0..1

folders: List<FOLDER>

Sub-folders of this FOLDER.

0..1

details: ITEM_STRUCTURE

Archetypable meta-data for FOLDER.

Invariants

Folders_valid: not folders.is_empty
FOLDER

The concept of a named folder.

It is strongly recommended that the inherited attribute uid be populated in top-level (i.e. tree-root) FOLDER objects, using the UID copied from the object_id() of the uid field of the enclosing VERSION object.
For example, the ORIGINAL_VERSION.uid 87284370-2D4B-4e3d-A3F3-F303D2F4F34B::uk.nhs.ehr1::2 would be copied to the uid field of the top FOLDER object.

Inherits: Any, PATHABLE, LOCATABLE

Attributes

LOCATABLE.name: DV_TEXT [1..1]

Runtime name of this fragment, used to build runtime paths. This is the term provided via a clinical application or batch process to name this EHR construct: its retention in the EHR faithfully preserves the original label by which this entry was known to end users.

LOCATABLE.archetype_node_id: String [1..1]

Design-time archetype identifier of this node taken from its generating archetype; used to build archetype paths. Always in the form of an at-code, e.g. at0005. This value enables a 'standardised' name for this node to be generated, by referring to the generating archetype local terminology.

At an archetype root point, the value of this attribute is always the stringified form of the archetype_id found in the archetype_details object.

LOCATABLE.uid: UID_BASED_ID [0..1]

Optional globally unique object identifier for root points of archetyped structures.

LOCATABLE.links: List<LINK> [0..1]

Links to other archetyped structures (data whose root object inherits from ARCHETYPED, such as ENTRY, SECTION and so on). Links may be to structures in other compositions.

LOCATABLE.archetype_details: ARCHETYPED [0..1]

Details of archetyping used on this node.

LOCATABLE.feeder_audit: FEEDER_AUDIT [0..1]

Audit trail from non-openEHR system of original commit of information forming the content of this node, or from a conversion gateway which has synthesised this node.

items: List<OBJECT_REF> [0..1]

The list of references to other (usually) versioned objects logically in this folder.

folders: List<FOLDER> [0..1]

Sub-folders of this FOLDER.

details: ITEM_STRUCTURE [0..1]

Archetypable meta-data for FOLDER.

Functions

(abstract) Any.is_equal (
other: Any[1]
): Boolean [1..1]

Value equality: return True if this and other are attached to objects considered to be equal in value.

Parameters
other

Other object for comparison.

Any.equal alias "=", "==" (
other: Any[1]
): Boolean [1..1]

Reference equality for reference types, value equality for value types.

Parameters
other

Other object for comparison.

Any.instance_of (
a_type: String[1]
): Any [1..1]

Create new instance of a type.

Any.type_of (
an_object: Any[1]
): String [1..1]

Type name of an object as a string. May include generic parameters, as in "Interval<Time>".

Any.not_equal alias "!=", "≠" (
other: Ordered[1]
): Boolean [1..1]

True if current object not equal to other. Returns not equal().

PATHABLE.parent (): PATHABLE [1..1]

Parent of this node in a compositional hierarchy.

PATHABLE.item_at_path (
a_path: String[1]
): Any

Pre: path_unique (a_path) [1..1]

The item at a path (relative to this item); only valid for unique paths, i.e. paths that resolve to a single item.

PATHABLE.items_at_path (
a_path: String[1]
): List<Any> [0..1]

List of items corresponding to a non-unique path.

PATHABLE.path_exists (
a_path: String[1]
): Boolean

Pre: not a_path.is_empty [1..1]

True if the path exists in the data with respect to the current item.

PATHABLE.path_unique (
a_path: String[1]
): Boolean

Pre: path_exists (a_path) [1..1]

True if the path corresponds to a single item in the data.

PATHABLE.path_of_item (
a_loc: PATHABLE[1]
): String [1..1]

The path to an item relative to the root of this archetyped structure.

LOCATABLE.concept (): DV_TEXT [1..1]

Clinical concept of the archetype as a whole (= derived from the archetype_node_id' of the root node)

LOCATABLE.is_archetype_root (): Boolean [1..1]

True if this node is the root of an archetyped structure.

Invariants

LOCATABLE.Links_valid: links /= Void implies not links.is_empty

LOCATABLE.Archetyped_valid: is_archetype_root xor archetype_details = Void

LOCATABLE.Archetype_node_id_valid: not archetype_node_id.is_empty

Folders_valid: not folders.is_empty

 
{
    "name": "FOLDER",
    "documentation": "The concept of a named folder.\n\nNOTE: It is strongly recommended that the inherited attribute `_uid_` be populated in _top-level_ (i.e. tree-root) `FOLDER` objects, using the UID copied from the `_object_id()_` of the `_uid_` field of the enclosing `VERSION` object. +\nFor example, the `ORIGINAL_VERSION.uid` `87284370-2D4B-4e3d-A3F3-F303D2F4F34B::uk.nhs.ehr1::2`  would be copied to the `_uid_` field of the top `FOLDER` object.",
    "ancestors": [
        "LOCATABLE"
    ],
    "properties": {
        "items": {
            "_type": "P_BMM_CONTAINER_PROPERTY",
            "name": "items",
            "documentation": "The list of references to other (usually) versioned objects logically in this folder. ",
            "type_def": {
                "container_type": "List",
                "type": "OBJECT_REF"
            },
            "cardinality": {
                "lower": 0,
                "upper_unbounded": true
            }
        },
        "folders": {
            "_type": "P_BMM_CONTAINER_PROPERTY",
            "name": "folders",
            "documentation": "Sub-folders of this `FOLDER`. ",
            "type_def": {
                "container_type": "List",
                "type": "FOLDER"
            },
            "cardinality": {
                "lower": 0,
                "upper_unbounded": true
            }
        },
        "details": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "details",
            "documentation": "Archetypable meta-data for `FOLDER`.",
            "type": "ITEM_STRUCTURE"
        }
    },
    "invariants": {
        "Folders_valid": "not folders.is_empty"
    }
}
FOLDER