iteraplan supports two file formats for exporting/importing data and meta-model:
- XML Metadata Interchange (XMI) as standardized by the Object Management Group (OMG)
- Excel with the file format as described in Excel EA Data Format
Both formats can be used to export data as well as the underlying meta-model and to import it into iteraplan (preferrably with an "empty" iteraplan database). The XMI format is particularly designed for interoperability with other modeling tools. The Excel format in turn is intended for human data maintenance activities. In the Excel format sheets, columns, and rows can be adapted to fit the needs of the data maintenance activity at hand. In particular, bulk edits of a subset of the available data can be conducted using the Excel file format to export and re-import the updated data. The mechanisms for "round-tripping" are detailed subsequently.
Exporting Meta-model and Data
The export function of iteraplan is available via the tab REPORT, tile "Export/Import". iteraplan supports two distinct modes of export: meta-model export and datamodel export. In the mode meta-model export only the structure of the data modeled in iteraplan, but no actual data is exported. The structure describes, which types, properties and relations exist in iteraplan.
There are up to five steps when performing an import. The screen will guide you through the steps of the import. During these steps iteraplan performs different checks on the supplied data with respect to format, content, and consistency.
Changes done to the iteraplan database after the import wizard has been started and before the import has finished completely can lead to unexpected results or errors during execution of the actual data write.
The steps are:
Read file and check plausibility of the data: iteraplan checks whether the file is a correct data file, and whether it adheres to the iteraplan format definition (for the format of the Excel file see Excel EA Data Format). The checks especially ensure that the supplied data is internally consistent, i.e. that no "dangling" references or unknown values exist. In case an inconsistency is detected, iteraplan reports the detected issue to the user and cancels importing.
Determine Metamodel changes: Before starting the import, the user has the opportunity to decide whether changes at the meta-model should be taken into consideration or not. If you mark the selection, iteraplan checks whether all properties described in the file are already present, or whether it is possible to add missing properties to the iteraplan meta-model. iteraplan presents a list of missing properties and allows the user to decide whether to apply the neccessary meta-model changes, i.e. create the properties, or cancel the import process.
... that descriptions, sequencing and coloring of properties can not be imported and will be ignored.
- Write Metamodel changes: iteraplan creates the missing properties, if any. The newly created properties are not assigned to attribute groups, but are created in the default attribute group.
- Validate data: iteraplan compares the data to import with the data already present in iteraplan. Different checks are applied to detect any inconsistencies, i.e. duplicate names, that would arise from importing data into the iteraplan database. iteraplan presents the result of the comparison to the user, who can then decide to proceed with the next steps or to cancel the import. Note: Canceling the import at this point does not roll-back the meta-model changes applied in the previous step.
- Write data: iteraplan applies the data changes identified in the preceeding step to the database.
Above five step process is used to make sure that the user always knows which changes are applied to the meta-model or database of iteraplan. Therefore, the user has to acknowledge each step by checking the information given by iteraplan and clicking "Next" to go to the next step.
Steps 1-4 are usually executed fast (seconds for smaller or medium sized imports, still within only a few minutes for larger data sets).
Step 5 may take some time, especially for larger data sets. Aside from concurrent edits to the database or technical difficulties, e.g. caused by a server outage, successful completion of step 4 ensures that step 5 will also succeed. Therefore, the user should carefully follow steps 1-4, such that step 5 can run unattended.
Error Messages And Error Locations
iteraplan displays messages if it cannot read or import data from an Excel workbook. You can find the location of the invalid data cell and remove or correct it. There are different error messages for different kinds of invalid data.
Missing localization information
Error in step 1: Title sheet does not contain necessary localization information.
Reason: Starting from 6.3, Excel sheets need to contain a cell with the exported language information.
- Open the "Introduction"-sheet of the excel export file
- Add "Language" to the cell F5
- Add either "en" or "de" to the cell G5 (depending on the exported language)
Missing reference object
Error in step 1: Can not resolve related object identified by Abc over relation end parent."
Reason: A building block refers to the building block Abc as its parent, but the row for Abc is either missing or Abc is renamed.
- In all sheets of building blocks with a parent-child association, search for rows with value Abc in the column named parent.
- If you want to rename Abc, say to Def, rename the reference, too.
- If you want to delete Abc, delete the reference, too.
- If the new name of Abc is invalid, use a valid name and rename the reference, too.
Object not found
Errors like the following in step 1: "Error in sheet GP-PROJ B-8: No Object of type Project with the name "New branches" found in file."
Reason: The project "New branches" is not found and cannot be used in a relation end, therefore. This can be due to the fact that a single building block or a complete building block type sheet is missing in the import file.
- Make sure the sheets for all building blocks used in any relation end are included in the import file.
- If not present, add the project "New branches" to the sheet "PROJ".
- If you want to delete "New branches", delete all references to it, too.
Invalid position (ignored)
Warning in step 3: The value of property position for object expression with id 99 is not valid.
Reason: The position must be an integer number. The position is not imported, though.
- In all sheets of building blocks with a hierarchy with positions, search for the row with ID 99 (in the first column). Note that there is exactly one such row.
- Remove the value in the position column.
Invalid numeric value
Warning in step 4: The value of property Sample Numeric Property for object expression with id 99 is not valid.
Reason: The value of Sample Number Property must be numeric.
- In all sheets of building blocks with the property Sample Numeric Property, search for the row with ID 99 (in the first column). Note that there is exactly one such row.
- Correct the invalid value.
There are several ways how the data in the imported file can be interpreted and different changes will be applied to the iteraplan data depending on the selected import strategy, see Import Strategies.
Additional information/technical limitations
Updating element hierarchy
It is not recommended to mix updates to the elements’ hierarchy with other updates, like renaming or adding new elements.
Furthermore, a switch of hierarchies, i.e. A is parent of B to B is parent of A, cannot be achieved by a single import run, even though there may not be an error shown in the validation step (step 4). This is also true if B is a more distant descendant of A.
The Tree View of the corresponding building block type can be used to switch hierarchies. Furthermore, it is possible to perform two separate import runs, i.e. the first run to remove B from parent A and the second run to attach it otherwise.
- Due to technical constraints there is currently no way to create attributes of the type "Responsibility Attribute" by adding the attribute to the excel file to be imported. When exporting landscape data or downloading the template, each responsibility attribute will be exported as text attribute. Importing data like this into a database where the according responsibility attribute already exists works correctly, but if the attribute does not exist already the attribute type and its values will be ignored: the attribute is not added to the building block type and the attribute values are not imported.
- It is also not possible to create attributes of the type "Date Interval"
- Adding a new building block type or relation by adding an according sheet or column to the excel file is not possible and the attempt will result in an according error message.
- You cannot change whether an attribute is mandatory or not with the excel import.
- The ordering of the children of a hierarchical element may be lost after importing.
- The dates for date intervals or date attributes must be valid excel date values. Valid date values are all dates after January 1, 1900.
- When editing the attributes of a building block or association, be careful to avoid accidentally removing the ID value from the Excel row. If the ID value is removed, iteraplan tries to both delete the old element and create an identical one at the same time. This leads to an error during the fifth import step if using the strategies "Conservative" or "Overwrite". If the strategy "Additive" is used, a more graceful error occurs in the fourth step.