Transaction Update Files

From wiki.eclass.eu
Jump to: navigation, search

Contents

[edit] Transaction Update Files (TUF)

[edit] Application

  • UseCase: Automated data updates
  • NonUseCase: Viewing differences by human

[edit] Available for eCl@ss Version

BASIC and ADVANCED

[edit] Definition

The Transaction Update Files (TUF) contain all information that is needed for a semi-automated update of valuated data. This can be transactional data or a catalogue file (e.g. a BMEcat file) with eCl@ss data (class/property/value/unit) that must be transferred from a previous eCl@ss MajorRelease to a later eCl@ss MajorRelease.

These files are one among several supporting files (RUF, TUF, CUF, SDF) which enable a user to update an eCl@ss classified and property described material master to a new version. All of these can be found here.

[edit] Files and Format

TUF is available for eCl@ss BASIC and ADVANCED in two different XML files. It includes only information that connot be obtained by the direct comparison of subsequent structure data releases.

Contained in the Transaction Update Files are combinations of predecessor-successor pairs of paths. A path starts from an Application Class and passes different reference properties of blocks to finally reach a certain property in the context of this Application Class and Block structure.

Reasonable, BASIC model paths are therefore all very short (containing only the application class and the property) and ADVANCED model paths can become very long (when a property is addressed that is situated in a deeply nested block structure).

If only the previous release is accessible, Structure Difference File (SDF) may be used before applying Transaction Update Files.

There are two different XML files:

C6.png
Figure 1 - TUF (eCl@ssXML-1.0)

[edit] Structure of the file

The transaction update file wraps in a TUF element an unbounded sequence of TUF_ENTRY elements. Each TUF_ENTRY contains one of the five commands:


These commands are explained in detail in the remainder of this chapter.


[edit] equiv_path

Purpose: To transport how a certain property’s context has changed between source and target release.

The equiv_path contains a sequence of up to five elements:


1.     source_path: mandatory; PROPERTYPATH_Type

         a.     can have up to three optional attributes (CC, AC, aspect having IRDI as values) that describe the class context of the property path

         b.     contains a sequence of property elements which describe the path of the property. This path is only longer than 1 in case of advanced classes, i.e. where a block structure is traversed. Each property element has three elements:

                                          i.    a mandatory ref (IRDI of the property)

                                         ii.    an optional ordinal_number (integer index of a traversed pattern of cardinality)

                                        iii.    a target_class_ref (IRDI of the selected specialization of a traversed pattern of polymorphism)

2.     target_path: mandatory; structurally of the same PROPERTYPATH_Type as source_path

3.     value_mapping: optional; contains a sequence of source_value and target_value which are both references to an ontoML value group.

4.     unit_mapping: optional; contains a sequence of source_unit and target_unit which are both identified by their IRDI.

5.     incompatible_change: optional; boolean that tells whether or not a change can be performed automatically (when omitted it obviously can)

 

Note:

Deletions in eCl@ss 7.0 were implemented such that:

·         a new property was introduced in target class

·         an equiv_path command was issued from the to be deleted property to the newly created one

·         the to be “deleted” property was set to deprecated

Thereby it was not triggered that the code of the old application class be updated as it would have had to be in case a real replace (including a real deletion of property) had been performed.

 

[edit] Examples

Please note: Some example refer to eCl@ssXML-1.0, some refer to eCl@ssXML-2.0, syntactically they are equal, only namespaces are different.


Example 1 (eCl@ssXML-1.0):

In this example, the property AAE670 in the default aspect SGX034 was replaced by the property AAQ326. The context of the property path is the CC BAE982 with the AC ABY226.

<tuf:equiv_path> 
      <tuf:source_path aspect="0173-1#01-SGX034#004" ac="0173-1#01-ABY226#005" cc="0173-1#01-BAE982#005">
        <cmn:property ref="0173-1#02-AAE670#001" /> 
      </tuf:source_path> 
      <tuf:target_path aspect="0173-1#01-SGX034#005" ac="0173-1#01-ABY226#006" cc="0173-1#01-BAE982#006">
        <cmn:property ref="0173-1#02-AAQ326#001" /> 
      </tuf:target_path>
</tuf:equiv_path>


Example 2 (eCl@ssXML-2.0):

In this example, the property AAC963 (Rated Voltage, deleted) that was assigned to the BASIC AC of SourceClass 22410101 was replaced by property BAH005 (Rated Voltage):

TUFPropertyReplaceCDP.jpg

The corresponding TUF entry is:

TUFPropertyReplaceXML.jpg


Example 3 (eCl@ssXML-2.0): JOIN Class

The successor path for property AAO735 (Rated Voltage, deleted) that was assigned to the BASIC AC (ABZ689) of SourceClass 40210203 (BAC917) is now the BASIC AC (AEL649) of TargetClass 34140202, after the JOIN of the SourceClass into the TargetClass. The TUF entry is:

TUFJoinClassXML.jpg


[edit] delete_path

Purpose: To delete a path which is no longer valid, i.e. a property has no successor in target structure and valuation shall be destroyed

The command delete_path contains one mandatory element, the source_path which is of the same PROPERTYPATH_Type as the source_path in the equiv_path command.


Example (eCl@ssXML-1.0):

    <tuf:delete_path>
 
      <tuf:source_path ac="0173-1#01-ABY226#005" cc="0173-1#01-BAE982#005">
 
        <cmn:property ref="0173-1#02-BAJ012#006" />
 
      </tuf:source_path>
 
    </tuf:delete_path>

In the above example the valuation of the undesired property BAJ012 is destroyed in the context of AC ABY226 classified as CC BAE982.


[edit] propose_value

Purpose: To introduce a value for a property. May be needed for initialization of pattern of cardinality.

The command propose_value contains a sequence of two mandatory elements

  • target_path of the property for which the value is proposed (which is of the same PROPERTYPATH_Type as the source_path in the equiv_path command)
  • proposed_value (a reference to an ontoML value group)

Note: does not occur in eCl@ss 7.0


Example (eCl@ssXML-1.0):

<propose_value> 
                <target_path cc="0173-123#01-AAA123#002" ac="0173-123#01-BAA123#002"> 
                                <cmn:property ref="0173-123#01-AAA123#002" /> 
                </target_path> 
                <proposed_value> 
                                <val:string_value>just a test</val:string_value> 
                </proposed_value> 
</propose_value>


[edit] delete_value

Purpose: To delete a value (needed for corrections)

The command delete_value contains a sequence of two mandatory elements:

  • source_path of the property for which the value is deleted (which is of the same PROPERTYPATH_Type as the source_path in the equiv_path command)
  • value_to_delete (a reference to an ontoML value group)

Note: does not occur in eCl@ss 7.0


Example (eCl@ssXML-1.0):

<delete_value> 
            <source_path cc="0173-123#01-AAA123#001" ac="0173-123#01-BAA123#001"> 
                        <cmn:property ref="0173-123#02-AAA123#001" /> 
            </source_path> 
            <value_to_delete> 
                        <val:string_value>remove this</val:string_value> 
            </value_to_delete> 
</delete_value>


[edit] select_branch

Purpose: To unfold pattern of cardinality and/or polymorphism in a predefined way

In case of complex changes it may be necessary in order to allow for automatic conversion of valuations to prepare a certain unfolding of structure to obtain the needed target paths for equiv_path commands.

The command select_branch contains one mandatory element: the target_path which is of the same PROPERTYPATH_Type as the source_path in the equiv_path command. It is to be expected that one of the attributes ordinal_number or target_class_ref is set.

Note: does not occur in eCl@ss 7.0


Example (eCl@ssXML-1.0):

<select_branch> 
                <target_path cc="0173-123#01-AAA123#002" ac="0173-123#01-BAA123#002"> 
                                <cmn:property ref="0173-123#02-AAA123#002" ordinal_number="1"/> 
                </target_path> 
</select_branch>
Personal tools