The XML Import option enables you to import a model on top of an existing model using SystemWeaver XML. The view is used for both imports of new items and imports to update existing items. It uses various methods to detect "same" things in the model and imports and performs updates accordingly. When using the XML import view, the match is against objects in the selected item structure tree, while the Import from XML option looks for objects in a specific library. Option settings in the XML Import view may be pre-set by a SystemWeaver Architect for specific purposes, and the view may only be available for specified item types as defined in a configuration. If you are unsure which XML Import option to use, contact your system's Architect.
- Familiar with the SystemWeaver meta model building blocks (e.g., Items, Parts and Attributes)
- Familiar with the SystemWeaver Explorer Interface and common operations
- An installation of the SystemWeaver Explorer client (swExplorer)
- You must have "Write" access rights to the library where you are importing/performing the changes
- A valid SystemWeaver XML file to import (SystemWeaver XML Schema)
Select a top-item in a structure for which the XML import view is available. Then, select the XML Import option from either the Items Ribbon, if a menu option has been configured by an Architect, or by selecting it in the View drop-down list. In the below example, the custom configuration is called "XML Import 1". The naming is set by an Architect.
Getting Acquainted with the View
The view is divided into three sections:
Select File to Import
In this section, you browse out and select the SystemWeaver XML file that contains the data that you want to import.
Once you make your selection, the following information will be displayed below the selected File:
Name lists the name of the items in the current item structure, and their parts.
Item type displays the type of the item.
Import Status indicates the status in the XML file with respect to the current model.
- Equal means that that the item in the file is equal to the item in the structure
- New means that the item in the file is a new item
- New version means that the item in the file is a new version of the item in the structure
Action lists the actions that will be performed upon import.
- Create means that a new object (item/part) will be created, with no relation to any of the existing item in the target (importing) database.
- Update means that the current version of the listed object will be updated according to the content of the file.
- New version means that a new version will be created in order to align the item and the content of the XML file.
- Force new version means that a new version must be created in order to align the item and the content of the XML file. In other words, a match in terms of version has been found, but there has been a change that means a new version must be taken out of the item to be able to update the information so that it matches the input file.
<blank> means that no action is required for the update of the current model.
The import status and actions are based on the matching of objects in the target database with those in the XML file.
Since there are many different scenarios in XML exchange, XML Import offers different methods of matching, based on identifiers and other means of identification. Refer to Identification in SystemWeaver for a general description of identification.
- The strongest matching is based on SystemWeaver IDs, including Ancestor ID.
- Secondly, if the Match on foreign id option is used, matching will be based on the Foreign ID, if such is available for the item.
- If no matching is found, new objects will be created.
Errors and Warnings
If there is any problem with the update, a box to the right, with a red border will list all such problems. An example of a problem is when the import uses types that are not defined in the importing database, or when there are versioning problems that need to be fixed.
Whether or not warnings and/or errors will be allowed during imports, is defined by a SystemWeaver Architect in configurations.
- If not defined, warnings will be allowed, but errors will not be allowed by default. Errors must be handled prior to completing the import.
- If defined, the Architect will configure whether or not errors and/or warnings will be allowed.
An activated Import button indicates that the import will be allowed. A grayed-out Import button indicates that the import will not be allowed.
Choose Access (Library)
In the Choose Access section, you define the library to be used for all new items created by the update. New versions will be located in the same library as current library. Only libraries to which you have "Write" access will be displayed by default.
This section lists available settings for the import:
Import owner to attribute specifies if the Owner property of imported items - if included in the SystemWeaver XML file - should be imported as an attribute. The attribute SID where the Owner property should be stored must be specified.
Example of Owner imported to Attribute with SID=FROM:
Owner Property in Source Database:
After Import to Target Database:
|Note: Importing Owner can generate a forced new version if the Owner has changed. The Owner property can be changed on released items.|
Import version numbers imports the version numbers according to the XML file. If unchecked, version numbers in the XML will not be imported. Instead the next sequential version number in the target database will be assigned.
Check for description changes specifies if the Description will be checked for changes. If set to "True" and there are changes to the Description of a released item (as in the example shown below), the result will be to force a new version.
Match on foreign id matches the imported IDs with the Foreign ID properties of the objects in the database. The Foreign ID property is normally used, both for items imported from some other tool or file format, and for items imported from another SystemWeaver database. In the box to the right of this checkbox, you can enter the namespace used in the source database. Prefix of foreign ID is used when you want to be able to identify which items have been created in which database, and is typically not used often.
Ignore changes to returning items is for roundtrip export/import (i.e., Items included in the import file have their origin in the receiving database). If selected, the comparision between the imported file and existing data in the database will end at the DefObj linking to the Item. All differencies between import file and existing data will be ignored for the Items that have the receiving database's prefix in the xID. The only thing that matters is that the ItemType in the import file must be recognizable. If not selected, changes will not be ignored for items that have their origin in the receiving database.
Fallback to match on ancestor tells the import to match on AncestorID in case there is no match on object ID. The version history of the imported objects will always be according to the order of import rather than replicating the version history of a source database. An import that matches on AncestorID will always result in a new import being placed last in the version chain.
Include previous versions in item matching specifies if the import should look in the version history of the objects in the database for matches.
|Note: The configuration of the view may block modification of the above options. If you do make changes to the settings, click the Refresh button afterwards to ensure that they apply prior to clicking Import.|
Things to Consider
- It is important to ensure that you are using the correct XML Import configuration for your import as it can effect the import actions.
Importing a SystemWeaver XML File
- Select the top item of an existing model structure where you want to do the import.
- On the Items tab, select the XML Import option on the ribbon (if available) or select the XML Import option from the View drop-down.
- An empty XML Import page displays.
- In the File field, use the browsebutton to open the Windows Open file dialog, and navigate to and select the XML file you wish to import. Click Open.
- Review any errors and warnings. Depending on the import configuration being used, you may be required to handle these before an import can be completed. Alternatively, you may be allowed to complete the import anyway. This will depend on the configuration.
- Typically, many of the options will not be editable if a custom configuration is in place. However, if they are editable, you can select the following options to fit your use case:
- If the Match items in import library box is checked, the import will not be a "pure" import, but will also try to match the imported item with those in the library specified according to the Choose Access (library where the item is stored) selection and possibly update matching items rather than creating new. It will also use the matching for creating the appropriate version chains. This matching is equivalent to the matching done when using the XML Import view to update a selected structure, but can potentially include many item structures while the XML Import view only updates the item structure selected in the structure tree.
- If the Import owner to attribute box is checked, the owner property of the imported items will be imported as a string attribute.
- If the Import version numbers box is checked, version numbers will be according to the one in the XML file, rather than sequential in the target database.
- If the Check for description changes box is checked, descriptions will be checked for changes. If there are changes to the description of a released item, the result will be to force a new version.
- Click Import. When the import is performed, the page will automatically be replaced by an Edit item page of the "top item*" in the import.