HR-XML 3.0 Standards, 2009 September 23.
Menu: [ Home | Guidelines | BODs | Nouns | Global elements | WSDL | Packages | Code Lists | Master Index ]
Trace back: » ch46s16 | ch03s30 | ch03s13 | ch02s03 | ch02s04 »
The previous sections described OAGIS data management constructs. The following sections examine approaches for using these constructs.
After the introduction of key concepts, the discussion is divided into two parts. The first part focuses on Create, Update, and Delete operations. The second part looks at Read data management operations.
To properly represent and process messages, senders and receivers must have a common understanding of the set of elements managed by message instances. Accurately determining the set of managed elements is a key challenge for message senders and receivers. Without agreed upon approaches, message senders and receivers face ambiguity with regard to data management operations. The sections below introduce key concepts and explain potential sources of ambiguity.
Specifications developed by Consortia tend to encompass a broad range of requirements contributed from a diverse group of participants. As consequence, the elements that a Consortium specifies for a "noun" representing a business entity tends to be a superset of what is relevant to a given implementation. Trading partners typically implement only a subset of the complete noun definition. This is a subset of elements representing entities actually managed by the trading partner systems. Those elements are said to be within the implementation scope, whereas the remainder are "out of scope."
A requisite for the data management approaches outlined in this documentation is that the senders and receivers of message instances understand the "set of elements managed" by message instances. This section is intended to introduce this concept, which is relied on in subsequent sections.
A message instance manages a set of elements. This set of elements represents entities actually managed by trading partner systems (that is those that are in-scope as described in the section called “Implementation Scope”). The set of managed elements within a message instance may include all the elements within a noun definition or a subset of the entire definition. Central to the concept of the "set of elements managed" is understanding that this set includes a union of the elements within the message instance with value assignments (i.e., those elements present in the message instance containing data) as well as elements with no values assigned (or, under the methodology that will be introduced, elements with an explicit Null assignment). In other words, the concept recognizes that data management instructions can be conveyed by elements in a message instance with assigned values as well as elements without value assignments. One of several possible examples of the latter is distinguishing an element with no value assignment that represents an instruction to delete an entity that exists on the receiving system.
Without an agreement between sender and receiver on what constitutes the set of managed elements within a message instance, ambiguities will impede interoperability. Consider that senders and receivers may have difficulty distinguishing elements within the managed set that have no value assignment from elements that are merely "out of scope" (as discussed in the prior section). Consider also how choice of update approach -- such as an approach of sending changes only -- can affect interoperability if sender and receiver lack a shared understanding of the set of elements managed. If only changes are sent, how will the receiver of a message distinguish among elements with no value assignments representing delete instructions from elements without a value assignment representing entities that have remained unchanged and, thus are not part of the incremental changes reported? Some broad data management approaches and guidelines are introduced in the sections that follow.
There are two basic data management approaches for Create, Update, and Delete operations:
Snap-Shot. Under this approach, the sender conveys within the noun all the elements representing the current composition of the entity being managed. This can be thought of as sending a "snapshot" of the full entity as it exists at the moment. This also is referred to as the "full-refresh" approach. This approach is outlined in the section called “Snapshot Approach”
Incremental. This involves sending a message containing only the particular elements representing entities that have been created, updated or deleted. This also is referred to as the "Delta" approach. For a detailed description, see the section called “Incremental Approach”.
While the snapshot approach is generally considered simpler to implement than the incremental approach, message instances based on the snapshot approach are larger in size and may require longer processing time than those based on the Incremental approach.
Note
The two approaches (snapshot and incremental) are not mutually exclusive within the context of a trading partner relationship as long as trading partners have a shared understanding of when and how to apply each approach. For example, "create" and "delete" operations involving relatively discrete elements tend not to pose the same degree of difficulty in calculating the "set of managed elements" as unconstrained "update" operations. In such cases, trading partners might decide to handle the simple creates and deletes using the incremental style, yet use the full-refresh for updates of existing entities.
The following rules apply to both the Snapshot and the Incremental data management approaches described in separate sections.
For any ActionVerbType-based BOD instance the following rules apply:
[R14] The set of elements being managed by a message instance must be well-defined and understood by message senders and receivers.
For a description of the underlying concept, refer back to the section called “Set of Managed Elements”. The above rule also is revisited in the separate sections covering Snapshot and Incremental data management approaches.
[R1] An entity to be represented and managed by an element in a noun instance, SHOULD be identified by a standard, primary ID or ID set (in the case of a composite key) for reference in data management operations.
The above rule applies to the design of the Noun as well as data management practices by message senders and receivers.
[R2] To preserve the utility of standard IDs in data management operations between trading partners, it is RECOMMENDED that trading partners avoid managing these same standard IDs within the message instances.
For example, Noun features such as AlternativeDocumentID SHOULD be used to associate a new ID with a noun instance versus migrating a primary ID, like DocumentID, to another ID value. This not only ensures IDs remain stable, but also avoids potential ambiguity in the way data management instructions are specified and interpreted.
[R3] A TaskID MAY be specified in the ApplicationArea (ApplicationArea/Sender/TaskID) as an annotation to tie a message instance back to a business task and related business event.
A business task is a generalization of business action and business event. Business actions correspond to commands and requests triggered by business events and event notifications.
The following rules apply to the use of ActionCriteria and ActionExpression elements within the ActionVerbType. These rules reflect constraints within the definition of ActionVerbType as well as within the OAGIS BOD architecture itself. The rules also clarify the use of ActionVerbType elements in data management.
[R4] The BOD architecture supports a many-to-many relationship between ActionCriteria and the Noun.
A Noun instance may be associated with multiple ActionCriteria instances.
An ActionCriteria instance may be associated with multiple Noun instances.
[R5] The flexibility of the schema supports a many-to-many relationship between the verb’s ActionExpression and the Noun.
A Noun instance may be associated with multiple ActionExpression instances.
An ActionExpression instance may be associated with multiple Noun instances.
The next set of rules focus on the use of elements defined within ActionVerbType. For ease of reference, the diagram that appeared in the earlier section on ActionVerbType is repeated below.
As the diagram illustrates, ActionExpression and ChangeStatus are associated through the ActionCriteria element. The cardinalities of these elements mandate that the set of ActionExpressions within the ActionCriteria may be associated with a single ChangeStatus. ChangeStatus can optionally contain such details as a Code (classifying the ChangeStatus), a Description, an EffectiveDateTime, a ReasonCode, zero or more Reason descriptions, and zero or more StateChange elements, each of which may contain a range of state change details.
[R6] If one-to-many ActionExpressions are associated with a ChangeStatus, then that association MUST be represented with exactly one ActionCriteria.
[R8] Where "Add" is specified as the value of actionCode (ActionExpression@actionCode="Add"), the ActionExpression indicates the creation ("addition") of the entity represented by the element matched by the expression.
[R9] Where "Change" is specified as the value of actionCode (ActionExpression@actionCode="Change"), the ActionExpression indicates the modification of the entity represented by the element matched by the expression.
[R10] Where "Delete" is specified as the value of actionCode (ActionExpression@actionCode="Delete"), the ActionExpression indicates the removal ("deletion") of the entity represented by the element matched by the expression.
[R11] Where "Replace" is specified as the value of actionCode (ActionExpression@actionCode="Replace") the ActionExpression indicates the replacement of the entity represented by the element matched by the expression.
Note that the use of the "Replace" actionCode attribute is associated with the "Snapshot" data management approach. See the section called “Snapshot Approach”.
[R12] The expression of the ActionExpression must be constructed to match the element(s) of the noun instance representing the entities being managed.
Note
An ActionExpression can apply to a single noun instance or multiple nouns within a BOD and should be
constructed appropriately. For example
/ProcessCandidate/DataArea/Candidate matches all Candidate nouns within the
ProcessCandidate BOD (assuming it contains multiple nouns) whereas
/ProcessCandidate/DataArea/Candidate[DocumentIDGroup/DocumentID='C111222'] matches only
the Candidate noun with a DocumentID equal to "C111222".
The key characteristics of the snapshot approach are as follows:
The message sender and receiver must have an understanding of the set of elements being managed. The "snapshot" communicated within a message instance will represent the set of managed elements in its entirety. This would include elements understood to be within the set of managed elements but that have no value assignment.
The snapshot could be set at the level of a noun or it could be a major element within a noun. The snapshot should be an aggregate that can be referenced by a primary ID. This might be the noun itself (for example, a Candidate noun referenced by its DocumentID) or an aggregate therein (for example, CandidateProfile, which is repeatable within Candidate and referenced by CandidateProfile/ID).
The sender of a snapshot may be either a system of record (SOR) publishing a snapshot of data or a non-SOR system that is requesting a receiving system to process a snapshot of data. In both cases, the sender may communicate the business task (ApplicationArea/Sender/TaskID) that caused the message to be created and communicated. ChangeStatus, available within the ActionVerbType, enables the reporting of meta-data such as ReasonCode.
The receiver of a snapshot message must update its system with all the elements within the set of managed elements. This may result in:
The creation of entities that were represented in the message but that did not previously exist on the system;
The updating of existing entities with corresponding refreshed data from the message instance; and
The deletion of entities that have no value assignment within the message instance, but that existed on the receiving system.
Because the message instance includes all data within the scope of the snapshot, the message also may include elements representing entities that remain unchanged on the receiving system.
There are many considerations that go into a data management policy and its successful execution. The following are intended as baseline rules for using the snapshot approach within BOD instances.
Under the snapshot approach, the following rules apply for any BOD instance based on ActionVerbType:
The key characteristics of the incremental or "Delta" approach are as follows:
A subset of a Noun is communicated in a message instance; note that the subset could be the Noun itself, or any element therein.
The set of managed elements within a message instance must be well-defined and understood by the senders and receivers.
Any subset of elements managed together should be aggregated as an element in the message and be identifiable through the use of standard IDs.
Elements included in a message instance (with the exception of ID(s)) are limited to those that contain entities that have been created, updated or deleted.
Detailed data management instructions for create, update, and delete operations are communicated in the message instance using a combination of ActionExpression, actionCode, and noun content.
The sender of an Incremental message may be either a system of record (SOR) publishing a create, update or delete operation or a non-SOR system that is requesting its targeted receivers to process a create, update, or delete operation.
The receiver of an Incremental message instance must update its system per the data management instructions (create, update, or delete operations on some set of elements) conveyed in the message instance through the ActionExpressions. This may result in the "creation", "update", or "deletion" of entities in the system as specified in the data management instructions.
Physical vs. Logical Delete
The receiving system may interpret a "deletion" as either a physical delete or logical delete and is dependent upon the receiving systems data retention policies.
Under the incremental approach, the following rules apply for any BOD instance based on ActionVerbType:
[R14.2] The set of elements being managed MUST be well-defined and understood by message senders and receivers.
For further information, see the section called “Verb Types and Responses”.
For any "Delete" operation, the following rules apply:
[R22] The Expression of the ActionExpression must match the element of the noun instance that represents the created entity.
For any "Delete" operation, where the entity being deleted is identifiable with ID(s) the following rules apply:
Identification of the data entity deserves special note; cases exist where the data entity being managed does not have a designated identifier or key (i.e., surrogate key, etc.) that is common and available across the communicating systems. For example, consider a Person with many Addresses where the Address entity does not have an identifier that is shared across systems; it is the value of properties of the entity, itself, that provide for the unique identification. Because it is not possible to issue an update operation on an entity using a common ID, the sending system must issue two operations: one delete operation for the "old" entity and one create operation for the "new" entity. This approach realizes the "old/new value" of the "optimistic locking" data management transaction model for maintaining data integrity.
For any "Update" operation, the following rules apply:
[R25] The Expression of the ActionExpression must match the element of the noun instance that represents the updated entity.
[R26] The message instance noun must provide a reference to the entity via its ID(s) (if one exists) and only include the updated properties of the entity.
For any "Update" operation, where the entity is not identifiable with ID(s) the following rules apply:
[R27] The message instance must contain two ActionExpressions and two noun instances
The first ActionExpression with an actionCode of "Delete" must identify the element being deleted, as represented in the first noun instance
The second ActionExpression with an actionCode of "Add" must identify the element being created, as represented in the second noun instance
Note that add and update operations of the incremental approach apply R14 to represent element null assignments.