This article explains the action “Force new version” when using the SystemWeaver New Item>Import from XML option and its potential consequences.

Background: Versioning in SystemWeaver

In SystemWeaver, Items have version chains. A version chain is indicated by Items sharing the same AncestorHandle, i.e., the ID of the first version of the item. In a chain, every individual Item also has its own (version specific) id called the Handle. The below picture illustrates the principles:

When importing data from other tools or from another SystemWeaver database, the principles are the same, but they are oriented around the Item properties Foreign Id and Foreign ancestor Id. These properties are used to keep track of identifiers from external systems. There is still a Handle and an AncestorHandle for the Item in the SystemWeaver database, but they are not used for identifying version chains and matches for imports from the external system. The below example contains a version chain of an Item that has been imported, which has Foreign Ids and Foreign ancestor Ids:

Force New Version: What it is and When it Happens

When using New Item>Import from XML in SystemWeaver, the action “Force new version” indicates that a change in the data has been detected and there is already an existing Item in the target database that has been Released with that Foreign Id. An example of this is shown below. In this case, there is a Part ("Req10") that has been deleted.

The resulting import is shown below in the Versions view. There are two versions of an Item in SystemWeaver, sharing the same Foreign Id and Foreign ancestor Id:

For some scenarios the action "Force new version" should be considered an error and the data import should be aborted. In other scenarios this status is inevitable and will be seen for every change. Guidelines for when to accept and when to abort a "Force new version" are provided below in more detail. 

When to Accept "Force new version" 

For the scenario where an integration is based on the fact that the sending system can only provide data corresponding to Foreign ancestor Id, as the below picture illustrates where Foreign ancestor Id and Foreign Id are always the same, the action "Force new version" is considered safe:

Typical scenarios where this can occur

• ReqIF-based integrations where there is no version id present or configured to be used
• Any integration based on a sending system that can only provide data corresponding to the Foreign ancestor Id. This includes name-based integrations which are sometimes necessary, but never recommended

In this scenario, "Force new version" will occur every time a change in the imported data is identified, since the providing system is unable to provide a version-specific id corresponding to the Foreign Id. However, since there is no risk for branching in this scenario, "Force new version" is an acceptable action.

When to Avoid "Force new version"

For the scenario where an integration is based on the fact that the sending system can provide data corresponding to both Foreign ancestor Id and Foreign Id, as the picture below illustrates, the action "Force new version" should not be allowed to occur when importing.

Typical scenarios where this can occur

• SystemWeaver to SystemWeaver database integrations
• ReqIF-based integrations where a version id is present and configured to be used
• Any integration based on a sending system that can provide data corresponding to both Foreign ancestor Id and Foreign Id

Normally "Force new version" indicates some kind of breach of the contract in these cases, where the sending system has either added more data to the information being sent or sent data that was not in the status corresponding to the SystemWeaver status Released previous to the current import.

For this scenario, the "Force new version" action is a fallback behavior to ensure that the data imported into SystemWeaver shall correspond to the original file, potentially at the cost of the version history. 

Description of "Force new version" Scenarios

Scenario 1: Version Chain Intact

The scenario in this example occurs when two versions of version "v2" have been imported with the "Force new version" action. When importing data and there are multiple Items with the same Foreign ancestor Id and Foreign Id, the matching algorithm defaults to identifying the last version in trunk, using that for comparison. The result in this scenario is that the "Force new version" action has placed the new version of the Item as the next version in trunk. The next time an import is performed, the version chain will match towards the correct item.

Scenario 2: Version Chain Broken

The scenario in this example occurs when two versions of version "v2" have been imported with the "Force new version" action and there was already a later version imported. As described in the previous scenario, when importing data and there are multiple Items with the same Foreign ancestor Id and Foreign Id, the matching algorithm defaults to identifying the last version in trunk, using that for comparison. The result in this scenario is that the "Force new version" action has placed the new version of the item as a branch based on the previous import of "v2", since it is unable to put it as the next version in trunk.

The result is that, according to the fallback behavior of the matching algorithm where the last version in trunk is used, future imports containing the the branched version "v2" will all result in a new branch "v2", according to the picture below:

The imported data is correct, but the version chains are not aligned to the exporting system. In practice, this means that there will be "false" updates when comparing the current import of data to previous ones.