A Description Reference is a practical way of creating hyperlink references to other items or parts in the system. These references are pasted in the Description in the Overview view. There are two types of references - Item and Part.


Item references are for hyperlinks pointing to items and part references are for hyperlinks pointing to parts. Item references will not automatically update should a newer version be made. How to handle version updates of item references is explained in more detail below in Updating Item Reference Version. Part references will automatically updated should a newer version be made.


Example

In the below example, three "CruiseControlManager" parts are copied and part references to them are then pasted into the "CruiseControlManager" description.


Creating a Description Reference

Description References can be created by using the context menu in the Overview view or by simply copying and pasting.


Context Menu Options

SystemWeaver will actually guide you in your reference type selection in that the context menu options provided to you are the ones that are available for the particular item or part that you have copied. You can only paste a part reference for a part within the scope of the item that is pointing to the parts that you are pasting. In the example shown above, part references can be pasted for the selected items because they are parts of "CruiseControlManager", the selected item, where the references are being pasted. The part reference option will not be available for an item. In the below example, if you want to add a hyperlink reference to the top-level "SystemWeaver - demonstration" baseline architecture to the Description of another item, the only option will be to add an item reference to "SystemWeaver - demonstration" because it is not a part belonging to an item; it is an item.



When pasting parts, you can choose to create an item or a part reference. In the below example, the "Radio" function specification is a part of "Function requirements". It has been copied to the clipboard and when you right-click in the "Function requirements" Description, there are two paste options for the "Radio" part: 



Selecting Paste part reference to 'Radio' will paste it as a part reference. This option is available because "Radio" is a part of "Function requirements". Should a new version of "Radio" be made, this reference will point to the new version.

Selecting Paste item reference(s) will paste it as an item reference. Should a new version of "Radio" be made, this reference will continue to point to the version that was copied when the reference was created. 


How do you tell if an item you have copied to your clipboard is a part or not? If you get the Paste part reference.. and Insert part reference options in the context menu, it is a valid part type of the item type you have selected.


Tip: You can also select an item you are pasting to and open the Parts view to see a list of possible parts.


When given a choice, as in the above scenario, If you want a reference to a part to update automatically to a newer version, if one is available, it is recommended that you paste it as a part reference.


Insert Part Reference(s)

The Insert part reference option is always available for any item that has or can have parts. You do not have to first copy a part. The sub-menu lists all parts types of the selected item type. Part types that are allowed for the item, but not currently represented, i.e., there are no parts of that type currently belonging to the selected item, are displayed in gray. 



When you select a part type, you can then select among all of the parts of the selected type using the Select Part dialog. In the below example, the "Audio control" item is selected and using Insert Part Reference, the "Requirement" part type was selected and then the specific part called "Activation command" of the Requirement type is selected. Click OK to paste the selected reference(s).


Multi-select

All of the above context menu options support multi-select and pasting multiple references simultaneously. 


Edit Item Reference

The menu offers an edit option for item references. This is basically a shortcut to the item referenced. To use it, hover over the item reference, right-click and select the Edit option. The item will open in a new tab. 



Copying and Pasting References

If you do not want to use the context menu options for pasting references, you can simply copy the item or part you want to reference, navigate to the Description where you want to paste it and use Ctrl+V. 



Select Paste object as description reference.



Just like with the context menu, using this option will follow the meta model structure and complete the paste operation that is available for the selected item or part. In other words, an item will paste as an item reference. A part will paste as a part reference. As is always the case with parts, you can only paste part references within the scope of the item that is pointing to the parts that you are pasting. In the below example, the "Maintain speed" part under "Adaptive cruise control" Requirements has been copied. If pasted to the Requirements description for "Adaptive cruise control", it will paste as a part reference. If pasted to the Requirements description for "Constant cruise control", it will paste as a item reference since it does not have a part relationship to "Constant cruise control" requirements.



There is also an option to paste a copied object as a URL.  


Batch Copy and Paste

Using the same copy and paste functionality described above, you can multi-select items, copy them and then paste them as description references. 


Item References

Multi-select the items in the structure and use Ctrl+C or right-click and select Copy in the context menu.

Place your cursor in the Description where you want to paste the item references and select Paste in the context menu or use Ctrl+V. As shown in the previous section above, select Paste object as description reference. They will paste as item references.


Part References

In the exact same way as described above, you can multi-select parts, copy them and paste part references to them, however, as described earlier, you can only paste part references within the scope of the item that is pointing to the parts that you are pasting. If you paste outside of that scope, the description references that you create will be item references. 


Removing References

To remove a description reference, delete it from the Description content in the Overview view using the Del or Cut (Ctrl+C) option. Description References cannot be removed using the Parts view.


Updating Item Reference Version

As mentioned above, if you paste an item reference, the reference will not automatically update should a newer version of the item be made. Item references must be updated manually. This ensures the stringent version handling that is one of SystemWeaver's strengths. A strict version handling means fewer errors. When you work in SystemWeaver, you are working in smaller contexts and references are not typically meant to be fluid throughout the database. We recommend using item references sparingly to minimize maintenance of them. The quickest way to update an item reference to the latest version is to use the Parts view. In the below example, there are three item references in "Text A": 


The Parts view displays an item's parts including any description references. It will also indicate if there is a Next Version available. Below, there is a version (2) available for each of the three item references.



If there is a Next Version and IF you need to update the item references to the next or another version, right-click on them (multi-select is available) and select Replace to next version or Replace to any version, whichever is applicable.



 As a rule, avoid turning on (i.e., set as viewable) the Description References and References in a structure tree as doing so can result in an extremely long load time for the structure and, potentially, an Out of Memory message.