Revision Support

Revision Support

General concept #

This section describes the concept of ‘Revisable Entity’. This concept can be applied to various SICS domain objects, see following sections.

A revisable entity can have multiple revisions (versions). Revisions are identified, and ordered, by a sequentially assigned revision number. A revision is ‘current’ if and only if it is the newest revision.

Each revision has attributes for ‘comment’ and ‘is current’. There is also typically an audit object attached, with attributes for ‘created by user’, ‘created timestamp’, ’edited by user’, ’edited timestamp’.

Each revision knows if it is ‘in use’, i.e. if it is referred to by some SICS object.

A revision can be deleted, subject to existing rules for deleting such an entity (for example, an Output Pattern cannot be deleted if it is used in a Mapping).

Every view window showing a revisable entity has a ’navigator’, which makes it possible to navigate between various revisions of this entity.

List windows showing a list of a specific type of revisable entity, shows the newest (current) revision of each item. From such a list, an item can be edited (current revision), or edited ‘as a new revision’.

Revisable entity types typically have an export/import facility. Importing may create a new revision, or update the current revision, depeding on the entity type.

Mapping #

ADH Mappings are revisable. On the Transformation tab, it is possible to change revision of a selected output structure / output pattern (see Output Pattern below).

Editing a mapping ‘as new revision’, or importing a mapping with an existing name, will create a new revision for that name. Existing ADH documents will not be changed, they will still refer to what is now older revisions of this mapping.

Documents can be (re)linked to any mapping revision, though by default the current revision will be suggested. (Re)linking uses a window which lists available mappings. This list will show the current revision of each mapping. A popup menu on a selected mapping will allow the user to open a window showing all revisions of this mapping. From here a specific revision other than the current one, can be selected for (re)linking to the document.

When viewing a document that is linked to some mapping revision, and asking for view/edit mapping, the linked revision will be used, not the current revision.

View windows that show the name of a linked mapping, will show the revision number in addition to the mapping name, if the revision is not the current one.

The xml file produced when exporting a mapping, refers to output pattern(s) (used in the mapping) by name. When importing the mapping, it may be the case that a referenced output pattern has more than one revision. In such a case the current revision of the output pattern will be used in the newly created mapping revision. See additional note (1) below.

When importing a mapping and linking to a referenced output pattern, the mapping will be updated to fit the output pattern. For example, assume the referenced output pattern was recently updated by removing an output pattern field. If the imported mapping has connections to this field, these connections will be removed and the mapping will be flagged as inactive and invalid.

Note (1) Assume the following. In some SICS database DB1 revision x of mapping M refers to revision y of output pattern P. A new revision y+1 of P is created and updated with a new OP field F. A new revision x+1 of M is then created and updated to refer to revision y+1 of P. A connection to F is also added to the mapping. Then M.x+1 and P.y+1 are exported. Now, the correct way to import the mapping and pattern in another SICS database DB_2 is to import the pattern first, then the mapping.

Fingerprint #

To uniquely identify version comparisons in mappings between databases, a visual ID will be assigned for the mappings in different databases to check if the mapping has the same/identical contents. So a calculated fingerprint on the mapping will be displayed in the UI which is a 7-character value using characters 0-9 and a-z, without storing this value in the database. The 7-character value reflects the essential contents of the mapping, for instance

  • Name of mapping
  • Document Type
  • Input Pattern structure (group and field names with attributes)
  • Output Pattern structure (pattern name, group and field names with attributes, offset of duplicated groups)
  • Blocks (type, properties, connections in/out)
  • Connections

Mapping_Fingerprint.png

Output Pattern #

ADH Output Patterns are revisable. When an existing revision of an Output Pattern is edited and fields are removed or added, or group repeatability is changed, all mappings linked to this revision will be updated to reflect the change. These mappings will be flagged as inactive.

Editing an output pattern ‘as new revision’, or importing an output pattern with an existing name, will create a new revision for that name. Existing mappings will not be changed, they will still refer to what is now older revisions of this output pattern.

The output pattern list view (which shows the current revision of each output pattern) has a menu option ‘Update mappings to this revision’. By selecting this menu option, any mapping which refers to a different revision of this output pattern, will be updated to use the current revision, and the mapping will be updated to fit the output pattern. For example, assume the referenced output pattern was recently updated by adding an output pattern field. Referring mappings will be updated to show this field.

When editing a Mapping, the palette will show the ‘current’ revision of each active OP.

Output Pattern(s) used on a mapping will show their revision number in their heading, if the revision is not the current one.

When editing a mapping that contains an Output Pattern, the popup menu on this Output Pattern will show a menu option ‘Change Output Pattern Revision’, which will open a window showing all revisions of this Output Pattern. Another revision can then be selected and transferred back to the mapping window, replacing the precent Output Pattern revision while keeping as many Output Pattern connections as possible.

Fingerprint #

To uniquely identify version comparisons in output patterns between databases, a visual ID will be assigned for the output patterns in different databases to check if the output pattern has the same/identical contents. So a calculated fingerprint on the output pattern will be displayed in the UI which is a 7-character value using characters 0-9 and a-z, without storing this value in the database. The 7-character value reflects the essential contents of the output pattern, for instance

  • Name of output pattern
  • Output Type
  • Group and field names with attributes

Output_Pattern_Fingerprint.png

Lookup Table #

Lookup tables are revisable. It is possible to manually edit an existing revision, or edit as a new revision (from a copy of the existing revision).

It is possible to update an existing revision, or create a new revision, by choosing to import a lookup table file with ‘merge rows’ or ‘replace rows’ option.

When creating a new revision through either import or manual edit, businesses that link to the ‘old’ revision will be re-linked to the new revision if:

  • The product is SICS Life and
  • The system parameter ‘Business - Conditions - Allow Lookup Table updates to affect all linked business’ is active.