Can I keep an item’s change history when exporting?
The simple answer is yes!
I certain scenario’s you may need to export items from one Cradle database and import them into another. Depending on your reasons for this, you may want to retain an items change history. However, this is only possible when using the Standard Cradle Export Format and Change History is enabled for your item types.
Enabling Change History
Each item type can have change history enabled in the Project Schema via the Project Setup dialog. You can see how to enable change history in this Cradle help article. Once enabled you should start to receive a change dialog pop-up when making changes to items of that type.
You can choose to enter a change comment, which can include your reasons for making this change. This can prove useful in situations where there are a large number of users in one database enabling full traceability.
Standard Cradle format
Cradle export format files are unique to Cradle and can store every piece of PDB (Project Database) information which does include an item’s change history. However, the type of information that is stored can be further defined by you in the export interface.
Cross references, or links, are used to connect items in the database. Each cross reference connects two items. A cross reference represents the fact that the two items are related in some way. Sometimes, it is helpful to load cross reference links en masse from an external file.
Types of File to Load
Cradle can load data from files in three main formats:
CSV / TSV, comma separated value or tab separated value
XML, there are many possible dialects of XML
Microsoft Excel® can easily produce CSV files. Also, it is easy to work with collections of simple data in Excel. Therefore, we recommend that you use Excel to load cross reference links into Cradle using CSV files.
In this blog entry, we will assume that you want to load cross reference links between user-defined items, such as system requirements and verifications, or test cases to test results. So, if you want to do anything else, please look in the reference section below for links to the Cradle help.
In our example, we will create links of type FRED from PROCR items to SR items.
Create Cross Reference Links
You will need the following columns in your Excel spreadsheet:
Type, use the value: NOTE_NOTE
Link Type, the link type of the cross references that you want to create. In our example, this is the link type: FRED.
From Info Subtype, use the value: NULL_INFOSUB
For From Model Namespace, use the value: MH_IGNOREMODEL
From Number, this contains the Identity of the item at the from end of the cross reference. In our example, this is the Identity of the PROCR item.
From Type, this contains the type of item at the from end of the cross reference. In our example, this is: PROCR.
To Info Subtype, use the value: NULL_INFOSUB
For To Model Namespace, use the value: MH_IGNOREMODEL
To Number, this contains the Identity of the item at the to end of the cross reference. In our example, this is the Identity of the SR item.
To Type, this contains the type of item at the to end of the cross reference. In our example, this is: SR.
These fields can be in any order.
Load Cross Reference Links
You can load the CSV file containing your links by:
Select Import from the Project tab in WorkBench
Set: File Type to be: CSV
Then, set: Info Type to be: Cross References
Also, set: Overwrite to be: Off, as this is safer than the other options(!)
And set From file to be where your CSV file is stored
You will be asked to define the mapping between fields in the CSV file and the attributes of cross references. Because the column headings in Excel match the names of the attributes, everything is mapped automatically:
Click OK to load cross reference links from the CSV file.
The link rules defined in your schema are used to control if cross references will be imported from your CSV file. You can set an option to ignore your link rules, if you want to.
Importing cross references this way may create dangling cross references. A cross reference is dangling if the item at its from end, or its to end, does not exist. Cradle allows you to import these cross references because it would be too restrictive to prevent you doing this.
You can detect and remove dangling cross references using the Cross Reference Integrity check in the Project tab in WorkBench.
Reference in Cradle Help
You can review the details of Cradle’s CSV file format in the Cradle help. Every Cradle system contains the Cradle help. You can access this help from the Help tab in every Cradle UI, and (on Windows) from the Cradle Help item in the Start menu.
We also provide the Cradle help on-line in our website:
Exporting either a whole project or just a query can take a long time if the database is huge. The quickest and easiest way to do this is use c_io.exe in a batch file during down time e.g. night
The options available are:
Required Export Options
So the first option is, of course, the export option that needs the user to specify a location and a name for the exporting file:
The Type Options
The -type option is required for the export option and allows users to define the type of export they require:
params will export only this projects parameters (Project Schema) all will export all items and definition files the user has access to pdb will export all items the user has access to but not definition files query export items matching a named query.
Options used with query
-query will specify the query to be used. This is required if the type is set to query -qloc will specify the location of the query. This is required if the -query option is used.
expformat is for exporting all files set in a saved format.
Options used with expformat
-expname is the Export Formats name. -exploc is used in conjunction with -expname to state the location of the export format -identity can be used with -expname and will override the Identity set in a query.
basesum requires the user to use -basename with the Baseline Name and -sumformat which allows the user to specify how the data is output either as CSV or standard (Note: the user must have the PROJECT_RO privilege for this option)
Options used with basesum
-basename needs to have a Baseline name currently either open or closed. – sumformat allows the user to state they format -basesum is output as CSV or standard.
The standard output is <BASEHIST> records in the normal format:
Other export options are not required but can be used with –type all and -type pdb: – since can be used to state a date or date and time since which items were created or modified. The format for this is yyyymmdd or yyyymmddThhmmss so 20170119 (19/01/2017). For example 20170119T183030 (19/01/2017 18:30:30)
-until will only export items that have been modified up to a certain date or date and time or a time after the -since was set. The format for this is the same as -since.
-delete_state allows the user to specify if they want the items being exported to be (Same as in the Export UI):
normal – Not marked as delete recoverable – Items marked as deleted but can be recovered all – All items not matter what they are marked as will be exported
-scope controls how an item is output either on its own or with all the items cross referencs. Using item will make sure only the item on its own is output. Using item_xref will output the item and any items cross referenced to it.
-binarytodir sets a folder for the binary data. So a user would use -binary “C:\Temp\binary” and all binary data would be output to unique files and the path to this file would be output in the export file next to the binary frame:
-sanitise will output items but without any binary frames. It will also change all text including item names, comments descriptions, text frames, change history, diagram symbols, discussions and user defined cross reference attributes.
C_io.exe can be useful when importing large files or when a user has a lot of files. When c_io is in a batch file, it can import different files into different projects within one batch file. This file is then run when no one is in the database and so there should not be any issues.
The options available are:
Required Import Options
The first option for importing needs the user to specify a location and a name for the file: -import “C:\Temp\import1.exp”
All saved Import Formats in WorkBench can be used with -import
-impname is the Import Formats filename. When an Import Format is being used -overwrite, -owner, -ipid, -cpid and -noalerts are set from this file.
-imploc is the location of the Import Format file.
Elective Import Options
-overwrite is used when a user requires any items in the database to be overwritten, merged or not overwritten. If not in the command line the default of off is used.
off – no data will be overwritten and only new items added
-owner sets by whom the items imported are going to be owned by. Depending on the option set depends on the owner of the items:
user option is owned by the user in the login option e.g. -login ADMIN the items will be owned by the ADMIN user.
File option is the owner as stated in the import file
A user can be specified and all items imports will be owned by that user e.g. -owner REQMAN
-ipid is the option to let c_io know whether to use the PIDs in the file or in the project it is being imported into.
Off means the PIDs will be generated.
On means the PIDs in the file will be used.
-cpid allows a user to specify the PID to be used for the items being brought in.
-noalerts option stops alerts from being generated during the import
-ignorelinkrules allows any cross references to ignore projects link rules in the current project but only if the user has the correct privileges. The user must have either ACCESS_BYPASS or PROJECT for this to work.
-noautoid allows the original numbering for items rather than any auto numbering set in the Project Schema.
-nocheckdata option stops data being checked so it is all imported.
-add_itemhist is the same a Auto update modification details and sets the current user, date and time, not what is specified in the file.
-itemhistcomment will include a Change History comment which will include the last modifier, modification date and time
-add_imphist will create a log with the history of the import. It shows the options used, who performed it and the date and time of the import.
-set_modify uses the current date and time instead of the date and time specified in the imported file.
Cradle can import data from external files in different formats. One of the most common formats is CSV / TSV (comma separated value and tab separated value). When data is imported from CSV / TSV files, you can choose different import overwrite options. The option that you choose will control whether your data is imported and, if it is imported, which existing data in your database will be kept, or replaced by data from the import file.
Items and Attributes
To explain these options, let’s use a simple picture to represent an item and the attributes inside it:
Lets say in your Cradle database you have an item with the following attributes:
meaning that the item in the database has values set in the 2nd, 4th, 5th and 6th attributes.
In a spreadsheet you have a row with data in columns corresponding to the 1st, 2nd and 5th attributes of the item in the database:
Import Overwrite Options
Option A – Overwrite On
If Overwrite is On then, for each row in the spreadsheet or each record in the CSV / TSV file, Cradle will find the work-in-progress item (if any) and delete everything inside it, and completely replace the contents of the work-in progress item with the data from that record or spreadsheet row.
You would get the following result:
As you can see, only the data from the file or spreadsheet (the yellow cells) are now in the item, all previous attributes (the blue cells) are now gone.
Option B – Overwrite Off
If Overwrite is Off then if there is an item in the database for the record in the CSV / TSV file, or row in the spreadsheet, no import will occur. If there is no item in the database for the record or row, then the result is the same as Overwrite set to On.
Option C – Overwrite Merge
This is the more interesting case!
If Overwrite is Merge then, for each row in the spreadsheet or record in the CSV / TSV file, Cradle will find the work-in-progress item (if any) and replace the attributes of that item with the columns from that row in the spreadsheet (or field i the CSV / TSV file) so any attributes in the item that have not been mapped to a column in the spreadsheet row (or field in the CSV / TSV file) will be left alone.
So the attributes that already exist in the item in the database and the attributes in the spreadsheet row or file record are merged:
You would get the following result:
Attributes in the spreadsheet row or file record have been loaded into the item. All other attributes in the item have not been changed.
Setting Overwrite to Merge is useful to add data to database items from an external CSV / TSV file or Excel spreadsheet. Any attributes not in the external file are not affected by the import.
To get more help importing information into Cradle, explore the Cradle help here.