Category ' Hints & Tips '

20th September 2023

Project Administration Integrity Checks – Item Integrity Checker

There are situations, as with any database, where integrity issues may occur with the data not matching what is defined in the schema. This could be due to a number of reasons such as:

Items of data that have not yet been populated
Mandatory categories or frames that have not been populated

With Cradle also providing the facility for data to be imported and captured in a number of different ways, it is inevitable that the integrity of this data may be questionable. Document Loader, capture add-ins and import are some of these mechanisms and, despite some protective settings in these tools, it is still possible to bring in data that does not match the current schema.

In addition to this, it is possible to import a project schema itself or modify the project setup which would impact the data that already exists in the database:

Changing item attributes, categories and frames
Changing link rules

For these reasons, Cradle provides two utilities in WorkBench that check the data in comparison to Project Setup:

Item Integrity Check
Cross Reference Integrity Check

For both of these utilities, the user MUST have ACCESS_BYPASS privilege to instigate any changes to the data. It is highly recommended that there are no other active users in the database when the checkers are ran. One way to ensure this is to lock the project using Project Manager.

We also recommend that you take a backup of your database and/or create a snapshot prior to making any changes with these utilities.

In this blog we will focus on the Item Integrity Checker.

Item Integrity Checker

The Item Integrity Checker is split into two parts:

Frame version checks
Item checks

Frame Version Checks

Cradle item types contain a type of attribute called a frame. Each frame can store or manage up to 1 TByte of any kind of data. An item can contain any number of frame attributes.

In practice, most frames store a small amount of text.

These item types also have a mechanism called edit history that records any changes that are made to an item. Each edit contains:

The date and time the edit occurred
The Cradle username of the person who performed the edit
The reason the edit was performed, this description is optional
A list of all the attributes (predefined, category values and frames) that were changed in the edit and their old and new values

For frames, it records the frame version numbers before and after the edit. All the frames versions are held within the item’s frame.

These frame version checks detect:

Missing version of any frames
Missing records in any version of any frame

To run this utility, select the item type(s) you want to check or All to check all item types. Then press the left-most Check button.

This will check all of the items in each item type selected to ensure each frame has a version of 0 and that all history for that frame, occurs in an accumulative sequence of 0, 1, 2, 3 etc and produce both a report and a summary in the dialog.

Notice in the dialog, that the Fix button becomes activated.

Pressing this button will repair the history records and can be checked by repeating the process:

Frame Integrity Check Report - No issues — Frame Integrity Check Report – No issues

Item Checks

On the right-hand side of the Item Integrity Check dialog, you will see a list of item checks that can be selected, or press All to select and run all checks.

These item checks compare the data that is held in the database with the currently defined settings in Project Setup to ensure they are consistent. If they are not, the utility will list any possible issues.

Once you have pressed the Check button, a report is produced and a summary appears in the dialog:

As with the frame integrity check, there is a Fix button but this can only apply to a number of checks. The ones that cannot be automatically fixed will appear on the report and will require some user intervention to correct the issue.

Below is a list of the issues that can be automatically fixed:

Summary

In this post we have addressed some of the checks that can be run on items in the database to confirm their data integrity using the Item Integrity Checker.

Please remember that the user MUST have ACCESS_BYPASS privilege to instigate any changes to the data and it is highly recommended that there are no other active users in the database.

Next we will discuss the Cross Reference Integrity Checker.

7th June 2023

Creating Tables in Document Publisher

Generating Document Publisher Tables

There are various methods of generating Document Publisher tables. This short post provides a brief explanation of the following methods:

Table Tag

A Table tag allows you to generate uniform tables where the resulting items are reported in rows. This can be a list of individual items or links to other items using a defined hierarchy. Below shows an example definition of both.

Insert a Table tag:
Insert Table Tag button
Add Field tags into the table cells:
Field Tags
Tables in Document Publisher
This will output the examples below:
Table showing FEATUREs

WorkBench Table Tag

Many tables will probably have been used as a result of queries in WorkBench. For example, one shown here is a list of System Requirements linked to SBS items:

These tables can be used as a WorkBench Table tag in a Document Publisher output:

This is a quick and easy method of producing tables without any need for defining Field tags as the table attributes are already defined in WorkBench. An example output is shown below:

Inserting into Table Cells

Document Publisher also provides the ability to insert data into table cells by the use of a special Computed Insert_Table_From_Bkmk Field tag. The steps to achieve this are:

Insert a Word table and format as appropriate:
Word Insert Table option
Inserted Word table
Highlight the table and insert a Word bookmark:
Insert Word Bookmark option
Before the table, insert a Paragraph Group tag and define the item type that you would like to shown in the table. For example – FEATURE items:
Example Paragraph Group tag
The first Field tag is very important as this specifies that the fields are going to be inserted into the table using the bookmark TABLE_1 that was defined. In this example, we also create a hierarchy to show linked NEED items and PBS items:
FEATURE hierarchy
In subsequent Field tags, you can insert into a specified row and column of the table. In this first tag, it is inserting the FEATURE identity attribute into cell column 1, row 1:
Inserting FEATURE identity
You can see here that another one of the Field tags is inserting the FEATURE TEXT frame into column 1, row 3 of the table:
Insert FEATURE TEXT frame

Once you have specified all of the cells to be populated in the table, this can then be published like the example shown below:

19th April 202318th April 2023

Marking Category Values as Obsolete

When setting up a single value pick list or multiple category, you can define any number of possible values. These can be chosen by a user as the value of the category in an item.

However, over time, category values may no longer be relevant.

Removing the values from the project schema would be the wrong course of action as values could still exist in items (possibly in old baselines) that would raise errors in item integrity checks and could cause problems when data is imported. For example, data that used to be valid can no longer be imported unless extra import options are selected to ignore the validation of data.

Set Category Values as Obsolete

Instead of deleting those values from the project schema, you can set category values as obsolete so that the value can no longer be entered by users but the historical values remain valid.

In this example, Project A might have been completed so is no longer valid to set for future items. Also, Department 1 might not be responsible for any future items but they were responsible for historical ones.

Obsolete category value option — Marking a multiple value category value as obsolete

Once set, any items that had been set to the obsolete value remain valid. However, users can only enter the values that are currently valid; not the ones that are marked as obsolete.

Categories in a form — Items only allow valid values to be set

When querying the database, you can still set the query criteria to search for items that are marked as obsolete.

Querying for obsolete category values — Querying the database on category values marked as obsolete

Any validation checks on items in the database will return without error because the value remains defined in the schema.

6th April 202328th March 2023

Hiding Unused Item Types

Each Cradle project contains item types that can be linked together by cross references:

You define the types of items, their characteristics and their attributes
You define the types of cross references and their attributes, and the rules by which they link items

There are several item types that are included by default in Cradle, such as:

Source documents – captured using Document Loader
Formal documents– formal saved Document Publisher output
Requirements – standard requirement type that you might wish to replace with a system note type instead
Events – used in the analysis stage of a project to model the environment of a system and to describe how the system interacts with this environment
Essential Domain – analysis models
Implementation Domain – design models
Project plans – integration with Microsoft Project
Before hiding unused item types
Some of the item types might not be necessary in your schema so you can remove unused item types/information in the Miscellaneous section of Project Setup:
Setting item types to be hidden

Once applied and WorkBench restarted, you will no longer see the item types/information you have chosen to hide. This includes:

Project sidebar nodes
Sidebars
Menus
Item type chooser
Query, View and Form Details dialogs
After hiding unused item types

This also applies to the Web Access default and basic user interfaces.

31st March 202323rd March 2023

Next and Previous

When a query is run in WorkBench, the tool will return a list of the items matching the criteria specified.

As a Cradle database can contain any number of items of information a query could find 0 to 1 million items.

The time taken to find so many items could be excessive. Therefore, queries find and return items from the database in blocks. The default size of a block is 1000 items but can be extended to 8000 items in UI Control user preferences:

User Pref Options — Retrieve Item Options in User Prefs

This means that when you run a query it will return at most N items.

Navigating between Blocks of Data

When the block is shown in the WorkBench UI, it is preceded by Previous… and followed by Next….

If you select these, then the query is re-run to find the next block or the previous block of items.

In this example, clicking the Next… option will retrieve the next set of items in the query:

Selecting Previous… again will return you to the previous block of items.

Reporting Items

If you are creating a report or publishing a document using a query, it is likely that you would NOT wish to be restricted by blocks of items.

Reports allow you to specify:

Selected items – items highlighted in the query
All items in this set – the block of N items
All matching items in database – the totality of items matching the query criteria
Publish Table options

16th March 202315th March 2023

Baseline Integrity Check

In certain situations, it may be necessary to stop a baseline from being closed if a condition has not been met. For example, if items have been registered in the baseline but items that are linked have not been.

Having this option set will ensure that all relevant data will appear in your completed baseline.

Setting the Baseline Item Integrity Check

To set this option, navigate to the Configuration Management options in Project Setup and tick the Baseline Item Integrity Check option:

You also have the ability to set a rule for the direction of the link/dependence:

All items linked to baselined items are also baselined (default option)
Baselined items’ source items are also baselined
Baselined items’ destination items are also baselined

Exclusions

You can also exclude item types or link types from being bound by this setting:

Failing the Check

If any of the checks fail, an error message will be shown with a report showing the items that caused the close baseline operation to fail:

10th March 20232nd March 2023

Adding Data to Multiple Selected Item Frames using CSV Export / Import

Introduction

WorkBench has the ability to select multiple items and modify some attributes and categories using the Properties dialog.

However, what if you wanted to add data into selected item’s FRAMES?

In this example, we will show how this can be achieved using CSV export / import.

Adding data to multiple selected item FRAMES

Create a CSV File

Export your item type to CSV. You only need to map the default attributes Identity, Type, Draft and Version that are already pre-set. The other attributes/frames/categories do not need to be exported.
Export Items Dialog
Setting Required Attributes
Open the CSV file in Excel and add a column representing the new frame.
In this example, we are adding a new frame named TEST and adding the text “My Text” in this frame for all (or selected) items.
You could, of course, add different text content for each of these cells.
Add Frame Column to Excel
Add a Frame in your WorkBench Project
If you don’t already have the frame, you can add a new frame to the item type in Project Setup now. This is the frame where we will add content en bloc.

Importing The CSV File

Select Import with the file type CSV and the required item type ensuring that the Overwrite option is set to Merge and press Import.
Note also that there are options here to update the modification date / last modifier and also whether to add an entry to the items’ edit history.

Map the fields ensuring that the added frame is mapped

You will see that the new frame has been added with content for all items and the previous content remains intact

2nd March 20239th March 2023

3SL Support and Call Logging

Sources of Information

3SL provides several sources of information should you or your colleagues require some assistance in your usage of Cradle.

Extensive documentation in PDF documents accessible from the Help Ribbon
Reference on our website – http://www.threesl.com/pages/reference/
Blog – https://www.threesl.com/blog/
Help – https://www.threesl.com/cradle/help/
Twitter – https://twitter.com/threesl
LinkedIn – https://www.linkedin.com/groups/4027985
YouTube – https://www.youtube.com/c/3SLCradle

However, should you require additional assistance, reporting a bug or suggesting an enhancement, additions to our documentation etc, you can contact 3SL directly via Support Services:

Contacting 3SL

When seeking support, we suggest assigning a Cradle liaison/Project Administrator as the users’ first point of call as they should already have undergone some form of Cradle training. If this person cannot provide an answer, then our support team will be available to assist.

3SL Support Services

Technical Support Department is available 9am – 5pm GMT Monday to Friday but often also available outside of these hours via email support@threesl.com . Our landline is +44 (0)1229 838867.

Support Call Logging

When communicating with 3SL via email, we will initially assign you a call number and a support engineer to address any problems that you might have. Please provide as much information about this call as possible so we can quickly resolve the call without any misunderstanding. The details that we like to receive are:

Name and full contact details
Area of Cradle with the problem
Your perceived priority for the problem
Operating system information
Cradle version
Means of reproducing the problem

Screenshots, error logs and data (sanitised or raw) are especially welcome to allow us to quickly and easily reproduce any problems.

Any bug reports or enhancements will be tracked in our database and you will be informed when an update is available.

Web Meetings

Should there be any confusion or further information required about a call, you or 3SL may suggest a demonstration via a Web Meeting.

3SL generally uses GoTo Meeting as our meeting platform but we can also use your corporate default platform such as Microsoft Teams.

Cradle Training

3SL offers training courses in the administration and practical usage of Cradle as:

Online “public” training interspersed throughout the year
On-site or online “private” training

These training courses cover subject areas such as:

System Administration
Project Administration
General User
Requirements Management
Document Publisher
Configuration Management
Risk Management
Test Management and Execution
Systems Modelling

17th February 202325th January 2023

Customising the Quick Access Bar

WorkBench provides a Quick Access Bar that allows you to launch queries by item type from the bottom of the WorkBench main screen. It’s intended to provide quick and easy access to all of the relevant types of information in your Cradle database.

Default Queries

By default, WorkBench is initialised to show a standard (Automatic) set of queries each ordered by the Identity attribute

All – Lists all items that you can access.
Bottom-Level – Lists all bottom-level items that you can access. Bottom-level items are items that do not have any cross references from them to other items of the same type. For example, they have no children.
Document – Lists the latest instance of items that you can access and displays them as a document. For example in Document style.
Document (Simple) – A simplified version of the Document query.
History – Lists the latest instance of items that you can access and displays them in a view showing change histories.
Latest – Lists the latest instance of all items that you can access. There can be many instances of each item, such as many versions of the item.
Recoverable – Lists all items that are in a recoverable state.
Suspect – Lists all items that are deemed suspect.
Top-Level – Lists all top-level items that you can access. Top-level items are items that do not have any cross references to them to other items of the same type. For example, they have no parents.
Unlinked – Lists all items that you can access that don’t have cross references to or from them from any other items.
Yours – Lists all items that you own.

Query options from Quick Access Bar — Quick Access Bar query options

These queries may be useful as a starter set of queries. However, it is likely that you will want to tailor the queries shown in the Quick Access Bar to meet your own project needs and use the Project queries and views to display the data.

Note that all automatic queries are ordered by Identity. You might wish to order your Quick Access Bar queries by Key, especially when working with hierarchies of items.

Adding Project Queries to the Quick Access Bar

In Project Setup, you can select the item type that you wish to tailor and press the Quick Access Bar button. In this example, we will use Requirements:

Quick Access Bar option in Project Setup — Project Setup – Quick Access Bar option

This presents you with a dialog that allows you to add up to 10 Project or System defined queries to your Quick Access Bar.

You can still show the Automatic queries by selecting the Append automatic queries checkbox:

Once applied, all users in the project will see the changes to the Quick Access Bar:

Quick Access Bar showing additional queries — Additional Queries in Quick Access Bar

These additional queries will use the view as defined in the Query Details dialog.

Quick Access Bar - Query Details — Quick Access Bar – Query Details

Personalising the Quick Access Bar

You may wish to personalise the Quick Access Bar for your own use to only show the item types that are relevant to you in the order that you wish them to be displayed. You can achieve this in the Preferences:

Preferences - QAB Option — Quick Access Bar options in Preferences

If you select the Append remaining item types checkbox, all other item types are still shown on the Quick Access Bar after the ones you have selected:

Quick Access Bar with highlighted item types

For further information on the Quick Access Bar functionality, refer to the help page https://www.threesl.com/cradle/help/7.7/#workbench/other/wrk_qab.htm.

10th February 202316th February 2023

Renumbering a Sequence of Incorrect Key Values

Scenario

You have captured a number of items into Cradle. However, the KEY attribute that defines the hierarchy has incorrect values. Do you have to open each item individually to correct this numbering?

For example, the items below should have a sequence of 1.1.1 to 1.1.8:

Numbering of items in a hierarchy — Incorrect hierarchical numbering

Solution

No, you can actually define the key sequence by selecting all of the items to be changed and pressing Properties:

In the Item Properties dialog, you will see that the Key attribute is listed with the value As Is. This is due to the items having different values:

Item Properties dialog showing Key As Is — Item Properties dialog

In this field you can add the value sequence within chevrons <<#=>>. In this case, you could enter the value 1.1.<<1+>>:

The result of this operation is shown below in which the Keys are now numbered sequentially as required:

Any changes to the items will be stored in the items’ histories.