In general, to create a user-defined matrix, you must do three things:
1 Plan the matrix.
2 Changes the USRPROPS.TXT file for an encyclopedia to support the definition relationships of the matrix. Depending on the type of matrix, you may also need to create an intersecting cell definition in USRPROPS.TXT.
3 Use the Matrix Designer to create the new matrix. The Matrix Designer provides you with a user interface to make changes to the USRMATRX.XML file, provided in the System Architect installation directory, to create one or more new matrices. Using the Matrix Designer, you make additions to the USRMATRX.XML file to specify the name of the matrix, the name of its command in the Matrix Browser, the definitions it will interrelate, and so on.
Planning the matrix
Matrices created by users are referred to as user-defined matrices. You can create any matrix type and select any definition type, as long as they can cross-reference each other. User-defined matrices are placed in the Matrix Browser under the User Defined tab.
The steps that you need to take to create a matrix depend on the type of matrix and the level of customization you want to apply to it. For example, you can create a definition that acts as a container for your relationships. Suppose you create a matrix with definitions X and Y. By customizing System Architect, you can create a definition type named X/Y. This way, for every X and Y definition that you cross-reference, an X/Y definition type is created.
Some variables to consider when creating matrices include the following:
▪What definitions will be cross-referenced (for example, Components vs System Requirements)
▪Is one or both of the definitions keyed to other properties? (if so, you will need to take account for this in the USRPROPS.TXT code supporting the matrix).
▪What is the type and function of the matrix you would like to build? Will you force input matrix only, or will you allow cross-referencing to be done through definition dialogs and the matrices?
▪Where would you like definitions to be displayed in the related definition? Should the dialog for definition X contain a field for related Y definitions, and vice versa? Will only one definition dialog display its related definition, or will neither? (For example, will the component definition contain a list of related System Requirements? Will the System Requirement definition contain a list of related Components? Will both? Will neither?)
Note If each Row definition stores a list of Column definitions, and each Column definition stores a list of Row definitions then the intersection information is duplicated. In such a case, you should make the properties in the definitions that store the information read-only so that they cannot be modified accidentally by a user. (For example, a user could enter a Component definition and add the name of a System Requirement, and not go to the System Requirement definition and add the appropriate Component).
▪If a definition dialog will display its related definition, what is the name of that property? (For example, the Component definition dialog might contain a list of System Requirements, but you might simply want to label it, Related Requirements.)
Editing USRPROPS.TXT to support the matrix
The second step to building a matrix is to create the USRPROPS.TXT entries that will support the definition relationships of the matrix.
As an example, we will create a matrix of UML Components vs. System Requirements. The first thing to do is open the USRPROPS.TXT file.
1 In System Architect, select Tools > Customize User Properties > Export USRPROPS.TXT (Encyclopedia).
2 In the Export User Properties dialog, select a target folder and then click Save. The file will be automatically from that location.
3 The Component definition type already exists as a default in all System Architect encyclopedias, however the System Requirement definition type is a new definition type that we will add to the encyclopedia.
Although the Component definition type already exists, we want to add a property called Related Requirements into the definition of a Component, which will contain a list of the System Requirement definitions.
Next, you need to create a definition that will contain information concerning the intersection of the two related definitions.
6 Add the following lines to USRPROPS.TXT:
At the top of the file, add:
Rename Definition "User 3" To "Component/System Requirement"
At the bottom of the file, add the following:
{ DEFINITION "Component/System Requirement" { PROPERTY "RowDefinition" { KEY EDIT OneOf "Component" RELATE BY "is part of" } } { PROPERTY "ColumnDefinition" { KEY EDIT OneOf "System Requirement" RELATE BY "is part of"} PROPERTY "Description" { EDIT Text LENGTH 255 HELP "Appears in the cell of a matrix" } PROPERTY "Intersection?" { EDIT Boolean LENGTH 1 } }
7 Save and close the USRPROPS.TXT file.
8 Import USRPROPS.TXT from the Tools menu, Customize User Properties, Import USRPROPS.TXT (Encyclopedia) command.
9 Reopen the encyclopedia (File, Encyclopedia Open) in order for the changes to take effect.
Creating the matrix Using the Matrix Designer
1 Run the Matrix Designer by selecting Tools, Matrix Designer.
2 In the General dialog of the Matrix Designer, set these properties:
Matrix browser caption
Specify the name of the matrix's menu command that will invoke it off of System Architect's Matrix Browser, User Defined tab. You may place an ampersand ('&') anywhere in the name, directly preceding any letter that you might want to act as a 'hotkey' to invoke the matrix through your keyboard. Menu entry, appears in the sub user menu.
Matrix Title
Specify the name of the matrix. It will appear as a heading in the matrix itself.
Matrix Type
Specify the type of matrix: SAGenericMatrixProc is the standard generic matrix.
X in Cell
Select this to display the matrix in a simple cross-reference mode, regardless of whether it is possible to display text in cells. In this mode, if the Column property and Row property are empty strings, then the CellDef property must be filled with valid values. A non-checked setting indicates that text should be shown in cells. In this mode, the CellDef must be given valid values.
Show Pick List
Select this to display the pick list of Column and Row definitions before the matrix is presented. You also have the option at this point to save the matrix configuration.
Multi dimensional matrix
The ID of the Multi-Dimensional Matrix group to which the matrix belongs.
Default Matrix
The name of the matrix, which should be selected from the list of matrix configurations, by default. On loading User Matrices (that is matrices of type SAMatrixSelectProc) a list of matrices saved by the user appears. In case the field 'SAMatrixDefaultMatrix' contains a matrix name, then that matrix is opened up by default instead of asking for the user to specify a preference through the list.
3 In the example, fill in the following properties of the General dialog of the Matrix Designer:
4 In the Matrix Definitions dialog of the Matrix Designer, specify the definitions that will be involved in the matrix, and the properties in each that will list the related definitions. You may also specify the definition type that will hold cross-reference cell information:
Column
Specify the definition that will be in the columns of the matrix.
Property
Specify the name of the property in the column definition that will store the list of related (row) definitions (ie, the property that will store cross-reference information).
Row
Specify the definition that will be in the rows of the matrix.
Property
Specify the name of the property in the row definition that will store the list of related (column) definitions (that is, the property that will store cross-reference information).
Cell
Specify the name of the definition type that will contain (as text) the contents of the column and row intersection. You might call this the “container” definition.
Mirrored
A matrix that has the same row and column definition types can be displayed as mirrored matrices.
In our example, we fill in the following properties of the Matrix Definitions dialog of the Matrix Designer:
5 Select Save and close the Matrix Designer.
6 Restart System Architect. Select View > Matrix Browser.
The matrix will be available in the Matrix Browser under the User Defined tab.
