Cross References in a Baseline

Cross References in a Baseline

The easiest description of a baseline is, a snapshot of how the database/items were at a particular point in time. There are both items and cross references in a baseline. The more cross references you have the larger the files will be. This means that if you do have many Baselines, you could find significant space being used on the server.

Are Baselines Taking Up a Lot of Server Space?

In our latest release of Cradle 7.4, cross references are separated from the other files when a baseline is closed. The cross references in each one are now placed in separate uniquely identified folders. Each folder has an alphanumerical identity, dependent on the length of the name for the baseline. This is twice the length of the baseline name.

The Baseline Folders
The Baseline Folders containing the Cross Reference folders.

Inside each of these folders are 4 files containing the cross references and their attributes. The files will be different sizes depending on the number of cross references that existed at the time the baseline was taken.

Baselines Cross Reference Folders
Baselines Cross Reference Folders

Folder Maintenance.

As these are individual baselines, a user can then zip these folders and remove them from the Baseline folder. Taking the four older folders, they total approximately 232KB on disk. If a user zips each folder it comes to 3KB each. If zipped into 1 file it comes to 9KB and so a saving of over 220KB.

Baselined Cross Reference Folder Zipped
Baselined Cross Reference Folders after zipping

Most databases are much later than this and so the space saving could be much larger. The user could also move the zipped files to a different server if required and so saving more space.

The only downside to doing this, is that if a user wishes to use Baseline Mode to see the cross references in a baseline, they will not instantly be there. Therefore, should the cross references be required in the future, just unzip the file into the original folder. Once the file is unzipped, a user can set the Baseline Mode and they will see the old cross references.

Related Articles

For a longer more in depth description of Baselines and Configuration Management click here.

 

What’s a dangling cross reference?

Dangling Cross Reference

These are cross references in the Cradle database where one or both items at the end of the reference are missing.

It goes without saying that if you have item A linked to item B and then delete item B, the link between A and B should disappear. In usual operations this is true and this is what Cradle will do.

However, it is possible to create a dangling cross reference when importing partial data from other projects or backups. Say for example you have exported all your Definition items (one of which is item A) and separately all your cross references.  (including the one to item type Constraints one of which is item B). Into a new project you import all the cross references and then the Definition items. You plan to create new constraints. If one is not created called B there will be a dangling cross reference in the new project.

Finding and Rectifying Cross Reference Problems.

Cross Reference Integrity Checker

Dangling cross references are just one of the  anomalies that can be detected using the cross reference integrity checker. This is run from the Project ribbon.

There are a number of tests which can be selected and these are shown below.

Once a problem has been identified, it can be fixed, deleted or exported for editing as appropriate. The availability of these will depend on both the problem and the current user’s privileges.

The cross reference integrity checker and report
Cross Reference Integrity

 

Check Description
Dangling cross references Detects cross references whose from or to item do not exist.
Duplicate cross references (A-B and B-A) Cross references are considered to be duplicates if a cross reference exists from item A to item B and another exists from item B to item A and they both share the same link type.
Reversed hierarchical cross references Detects cross references that are between items where the from item has an identity that suggests it to be the child of the to item.
Cross references to be reversed Detects cross references that are invalid according to the current link rules but which, if reversed, become valid.
Cross references needing a new link type Detects cross references that are invalid according to the current link rules but which become valid if their link type is changed and where there is only one link type that is valid for the cross reference.
Invalid cross references Detects cross references that are invalid according to the current link rules.
Cross reference cardinality Detects cross references whose cardinality does not match the current link rules.
All Will perform all the above integrity checks.

Performance

Dangling xrefs can cause issues with performance when items have been deleted. If item A was linked to item B, then item B got deleted. There would be a dangling xref which isn’t linking any items, creating extra data. If another item B was then created. It would then be linked back with item A. Which could potentially cause problems?

For full information on the settings see the help on Cross Reference Integrity

Article Updated 04/02/2019 – Added performance section

Cross References Mapping in a Table for Document Loader

Item Cross References

Item cross references can be captured through Document Loader in several ways. In this blog we deal with how to set Mapping Cross References in a Table. With all items in one or more tables, the linked items are in a cell using a comma to separate them. These cells will be mapped for the cross references.

Showing different table layouts
Showing Item Per Table and Item Per Row tables

The tables above show information created in a document. The first shows each item in a separate table and the second each item is a single row.

The columns in the second table are;

  • Key – The Identifying number for the item
  • Name – The text name being assigned to the item
  • Description – The text to be captured into the frame of the item
  • Linked Requirements  – The list of Keys (1st column) to which this item is related. It is not necessary for every item to link From/To other items. For example 1.1 links to child item 1.1.1, it is not necessary to link 1.1.1 back to 1.1 in the table.

You can only set one item type to be linked per table.

Table Mapping

Document Loader allows you to map cross references From or To items of different item types. There will be two options for From and To item types for each item type in the schema. This includes Specifications but not Data Definitions or Diagrams. Cross References can be set To and From the document. This is not necessary as each item has a link added back to the document when captured.

The options will show in a list like the example below:

– Xref from <item type> by identity
– Xref from <item type> by hierarchical attribute
– Xref to <item type> by identity
– Xref to <item type> by hierarchical attribute

Mapping Item Per Table Cross References

Load your document and right click on the cell you want to map and select Table Details. When the Table Details UI opens if not already selected, click on Item Per Table. To map the cells, the option is pulled over to the right column to the attribute you require it. The  attribute in the right column is selected and then double click on the required option. Map the cells making sure you map one of them to an Identity or hierarchical attribute (Key). Set the cross reference cell by selecting the appropriate option.

For example in the first single table in the first screenshot, the numbers are for the Key attribute of an item. This means using the options with the hierarchical attribute in them.

As the links in the above example are to other items of the same type the option Xref to Requirement by hierarchical attribute is used. This will capture the cross reference from item 1 to 1.1. If I had put the cross reference to item 1 in the cells of the other items, I would have used Xref from Requirement by hierarchical attribute. This would then capture the cross references in the opposite direction of 1.1 from 1.

Item Per Table options
This shows the mapping of a Item Per Table option

This mapping can be exported and used for other tables within the document and selected through the Copy table mapping drop-down.

Mapping Item Per Row Cross References

Mapping Item Per Row is similar to Item Per table but instead of mapping cells you are mapping columns. As before, right click on the table and select Table Details. As before set the attributes like Key and Name etc, then set the Linked Requirement using the Xref to Requirement by hierarchical attribute option.

This shows Table Details with the Item Per Row mapped
This shows Table Details with the Item Per Row mapped

Capturing the information

Once all the paragraphs and tables are mapped with the relevant options, the user can capture the document. The cross references from these cells are created at the end of the capture so that all the items should be in the database.

The end of the Capture Results showing the cross references created
The end of the Capture Results showing the cross references created

 

Load Cross Reference Links

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:

  • Cradle
  • 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.

Example

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
Define Cross References in Excel

Load Cross Reference Links

You can load the CSV file containing your links by:

  1. Select Import from the Project tab in WorkBench
  2. Set: File Type to be: CSV
  3. Then, set: Info Type to be: Cross References
  4. Also, set: Overwrite to be: Off, as this is safer than the other options(!)
  5. And set From file to be where your CSV file is stored
  6. Click Import
load cross reference links
Load Cross Reference Links

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:

load cross reference links
Load Cross Reference Links – Field Mapping

Click OK to load cross reference links from the CSV file.

Link Rules

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.

Dangling Links

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:

https://www.threesl.com/cradle/help/

You can access the detailed help for Cradle’s CSV file format here:

https://www.threesl.com/cradle/help/7.3/Import%20Export/Other/csv_fileformat.htm

Cardinality Control in Link Rules

The Cardinality Values and Uses

In the latest release of Cradle using Cardinality in a cross reference has been introduced. This extends the capability of controlling cross references to the point of how many relationships an item can have.

The Many-to-Many Relationship

This is the default option for a rule when it is first set. This is also the default option when a rule is imported from an older version which does not have this option. This cardinality relationship is applied to:

  • Most of the link rules in the as-supplied Cradle demonstration databases DEMO and SYSM
  • Most of the link rules in the as-supplied default schema and quick-start
Demo Link Rules showing the Cardinality
Showing One to Many and Many to Many Cardinalities

The One-to-Many Relationship

This cardinality is used for parent-child relationships between items of the same type. Furthermore this option is applied to:

  • Parent-child link rules in the as-supplied Cradle demonstration databases DEMO and SYSM
  • Parent-child link rules in the as-supplied default schema default and quick-start

The Many-to-One Relationship

This option will allow many items linked down to a single item. Many users can be assinged to one Requirement.

The One-to-One relationship

This is mainly for links like a single result file to a single test file.

Link Rule Setup options
Showing the Cardinality option within the Link Rule Setup

The new cardinality option is for all item types which includes all the modelling types as well.

Hence if a user tries to set linked items which are against the rule they will see an error which will deny the links and the links will not be created.

Stopped by Link Rule Error Message
Error Message

Restrictions on use

Finally there are restrictions in how this option is accessed. For instance a Link Group cannot be used in conjunction with the Cardinality. Also the options to create or modify cross references must be checked or the Cardinality option will be disabled.

For information on getting started in Link Rules click here

Initial Expansions in Project Sidebar

Sidebar Expansion

The project sidebar offers a ‘raw’ view of the data stored in the Cradle Database. When first opened a list of item types is displayed. If there is a [+] indicator, then you can expect to expand the tree to lower levels.

In the example below Reference item type has been set up with an auto numbered ID and the Key being the  hierarchical attribute. A rule has been defined to allow the items to be linked to items of the same type with the “RELATED TO” link type.

  • All (All Items) This will show all the items of that type (subject to the user preference limits) when the node is expanded. Other than in very sparse databases this is not usually that a user wants to show.
  • Top (Top Level Items) This is more akin to looking at the level1 headings in a document. These are the items you have designated as having the most significance. They have no links down to them links. In the example you’ll see that item REF-4 (3.1) may appear to be a sub level item, but it has not been linked to a parent.
  • Bottom (Bottom Level Items) These are the leaves of the tree, the items that have no further downward links to children.
  • Disconnected (Not Linked to Anything) These items have no parents or children,  REF-6 (3.1.2) is shown here. This indicated an item that has been unlinked or its parents have been removed and either needs re-linking or reordering below a new parent.
Expansions of the main Project tree
Tree Levels

The last Disconnected  (Not Linked to Other Item Types) option in the menu looks at item of different types when deciding to list the item or not.

Can I control the shape of a HID?

Hierarchy Diagram Output Control

Yes you can control the shape of a HID (Hierarchy Diagram). In the hid properties you can control the shape and data shown in your HID.

The cross reference links between each item control the connections shown on the HID.  The whole HID layout can be Vertical or Horizontal. The number of levels shown when first rendered (rather than dynamic click and expand) can be controlled. Whether an item is shown more than once if it has multiple cross references and general layout parameters. These are further detailed in How to Set Hierarchy Diagram Properties. Once you are happy with the layout it can be saved for use next time you need a similar pattern.

The HID properties dialog
HID Properties Dialog

Your data may produce a short wide tree or a long narrow tree. This can be difficult to see on the screen. This video shows how changing the pivot point, (the node at which the orientation changes from listing horizontally to vertically) can alter the overall display yo be more usable.

Related Articles

Make a Hierarchy Diagram (HID)

Getting Started with Link Rules in Cradle

What Are Link Rules?

Link rules are used in Cradle as a way of defining constraints for cross reference operations within a project. They specify who can manipulate cross references, the link types that can be used, between what types of item, and which items of these types. This guide to getting started with link rules will help first time users understand the concepts.

The level of detail for each link rule can vary as required for your project’s needs. On one hand they can be very simplistic, allowing links of any link type between all item types. On the other hand they can be more detailed and specific, allowing links between different item types, models and individual item identities.

Throughout this blog post, and future posts, we will explore the Link Rule Setup dialog. These posts will cover the different options available and the result this will have on cross references between items in your project.

Continue reading “Getting Started with Link Rules in Cradle”

Linked Items in Views

Displaying Linked Items in Views

You can expand and collapse items shown in a table in Table view or Document view displaying linked items in views. This is similar to expanding nodes in a tree using the current navigation. When an item is expanded (double click the number in the first column) in a table,  a dot(.) is displayed in the first column representing the level:

. (1 dot = level 1 item)
.. (2 dots = level 2 item)
(3 dots = level 3 item)

Screenshot showing linked items in views
Linked items in views

For further information please see the Cradle online help.

Query Delete State of Linked Items

New Cradle Query Feature

Selection of linked item's delete state
Query Details -Linked items delete state

In the query details dialog, users can now set the ‘Delete State’ of linked (or not linked items).

Those states are:

  • Normal an item considered live and accessible
  • Recoverable an item that has been deleted but could be brought back, hidden in most operations
  • All a combination of the two.

Why is Delete State Important?

It would be logical to run a query to check that all your Requirements are linked to System Requirements. Therefore, setting a query to return Requirements ‘Not Linked’ to System Requirements that are of a Normal Delete State would give you the required list.

On the other hand, before permanently deleting a batch of items, you may want to check that they are not linked to Recoverable items first. In that way you can ensure those items linked items are deleted too.

Since the state of both the primary item and the linked items can be set  this gives all query combinations for an item’s deleted status.