Tips and Tricks
for System Architect

 

Creating a VBA Macro:

Creating System Architect Diagrams, Symbols, and Definitions in VBA:

 

Creating a VBA Macro -- Part 1 of 11

System Architect provides integrated support for Microsoft VBA and its development environment. The programming environment, debugging environment, and language is the same VBA found throughout the industry, including Microsoft Office products. Combining System Architect with VBA provides you with a standard development environment for creating customizable solutions incorporating all the programming developments provided by Microsoft, including IntelliSense and Microsoft forms.

This tip will be the first of a series of tips that will describe System Architect's VBA and show you how to build a simple macro. In this tip we'll take a look at what VBA enables you to do, and how it is accessed.

Reasons to Use VBA with SA

VBA can be used for various automation tasks. Some potential reasons for seeking to customize System Architect with VBA are:

Modifying application behavior -- Modify the way System Architect works to match your company’s business rules. For example, when a user creates a symbol on a diagram, your company's naming standards could be checked and the user is flagged if they are broken.

Automating repetitive tasks -- Combine sets of common manual tasks into a series of actions that can be executed over and over. For example, you could print a user-defined set of diagrams.

Extending application functionality -- Add features to System Architect that are not available 'out of the box'. For example, you could automatically create a Process Map diagram with swimlanes that is derived from a Process Chart and the assigned roles of the elementary business processes on the diagram, and the roles' Organizational Units.

Integrating with other applications -- Control another application to exploit functionality not normally available. For example, you could produce an Excel Spreadsheet of Process versus Entity CRUD information.

Accessing corporate data -- Exchange data with remote databases and applications that aren’t normally capable of database access. For example, you could automatically import information from diverse sources that cannot be imported directly.

Opening the VBA IDE

The VBA Interactive Development Environment (IDE) is accessed by selecting Tools, Macros, VBA Editor while in System Architect. Future tips will guide you through building a simple macro. This week, we'll take a look at the two main reference sources for building a macro -- both enable you to view System Architect's object model.

The Object Browser

The Objects available to VBA from System Architect can be viewed through the Object Browser in the VBA editor. Each type of object is defined as a class which contains a list of supported properties and methods. The Object Browser is accessed by selecting View, Object Browser in the VBA IDE.

The Object Model

A much easier way of viewing the whole model is by using a class diagram. System Architect’s object model is represented by a Class diagram, provided in an encyclopedia shipped with the product named Object Model.

To view the object model, perform the following steps:

  1. Open the encyclopedia located in the C:\Program Files\Popkin Software\System Architect\Encyclopedias\Object Model directory.
  2. This encyclopedia contains one diagram -- a class diagram named Object Model. Open it. The object model class diagram presents all of the classes of the object model, their attributes and functions, and the associations between other classes.
 

System Architect Object Model

×

Within System Architect, you can open the definition of each class, and examine its properties (attributes) and its methods. The methods are functions that you can use while programming to get information or do things in SA. Here is a quick summary of the classes in the Object Model:

Application Object -- This is the System Architect application object, through which the user interface can be controlled. It is the highest level object in the object model.

Encyclopedia Object -- enables access to the encyclopedia’s properties and methods.

Diagram Object -- enables access to a diagram's properties and methods.

Symbol Object -- enables access to a symbol's properties and methods. Symbols are always contained in diagrams.

Definition Object -- enables access to a definition's properties and methods. Definitions define symbols; some definitions exist independently of symbols (ie, a requirement, or an attribute of a class definition).

MetaModel Object -- provides access to the metaclass objects for an encyclopedia.

MetaClass Object -- provides information about an individual object type in the encyclopedia. It corresponds to information in saprops.cfg and usrprops.txt for specific types of object.

MetaItem Object -- provides information about an individual object type in the encyclopedia. It corresponds to information in saprops.cfg and usrprops.txt for specific types of object.

MetaProperty Object -- allows you to retrieve information about each property for a specific object in the encyclopedia. This object corresponds to the Property keyword in saprops.cfg and usrprops.txt files.

MetaKeyedBy Object -- retrieves information about the key structure of a MetaProperty Object.

Creating a VBA Macro -- Part 2 of 11

This tip is the second of a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. You will create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we introduced VBA and looked at the System Architect object model. In this tip we'll create a macro project, create a subroutine within it, and begin our coding by using the highest-level object of the object model -- the Application object. This will set the wheels in motion for coding that we will do in ensuing tips.

Create a New Macro Project
  1. In System Architect, select Tools, Macros, Macro Projects.
  2. In the Macro Projects dialog, press the Add button.
  3. In the Open Macro Project dialog, make sure you are pointing at System Architect’s main directory. We will create a new macro project called Tutorial.mac.
  4. In the File Name: text box, type in Tutorial. The Files of type property should read System Architect Macro Project (.mac). Be sure to toggle off the Open as read-only choice at the bottom of the dialog, and press Open.
  5. In the Macro Projects dialog, with the Tutorial project selected, press the Apply button. Press Yes to any dialog that comes up.
  6. Press OK to close the Macro Projects dialog.
Add Code to the Macro

Now let’s open this Tutorial project and add code to it.

  1. Select Tools, Macros, VBA Editor. The VBA Interactive Development Environment will open.
  2. Right-hand mouse click on the Tutorial project itself -- you can see that we can insert various types of objects:
    • Forms
    • Modules
    • Class Module (can create classes you can access from other applications)
  1. Choose to insert a Module.
 
  1. In the first row of the Alphabetic tab of the Properties window on the left-hand side, you can type in the name of this module, which by default is Module1. Overwrite Module1 with Example.
 
Using the General Workspace

Notice that the top-right of the VBA IDE contains a General workspace, and declarations. This is where we will create and store dimension variables that are accessible by the module, and where we will type our code.

Create a Subroutine

Let's first create a subroutine within this macro. Within the subroutine we'll place the code that will get information from the open System Architect encyclopedia.

  1. In the General workspace, type in the following:
    Sub Main()
    and hit Enter
  2. Note that the end of the subroutine is automatically added:
    End Sub
Use the Application Object of the Object Model

In the previous tip, we looked at the object model. Let's take a closer look at it now -- look at the Application class in the diagram below. Notice that an application can have zero or one encyclopedias.

 

Application is the highest level object in the object model. It is the starting point for everything. The same holds true for all applications for any object model – Word has an application object, Excel has an application object, etc.

Dimensioning an Object

Let’s dimension an Object. Dimensioning an object makes space for it in memory.

  1. Type in the following:
    Dim SAapp As
    and hit the spacebar.

As soon as you type the spacebar, VBA’s intellisense gives you a drop-down list of items. One of the things you see in the drop-down is a library called sa2001.

  1. Select sa2001
  2. Type in a period (.), now the drop-down intellisense window gives you all objects available in the SA2001 library. Choose the Application object. Your final line of code should read:
    Dim SAapp As SA2001.Application

Dim means we will make some space in memory for the application object. It doesn’t mean it is active.

Creating an Active Instance of the Application Object

To make the Application object active we have to create an instance of this object:

  1. Type in the following, selecting where appropriate in the Intellisense drop-down selections:
    Set SAapp = New SA2001.Application
Ending the Instance

It is good programming practice to kill all of your objects, or release them, at the end of the routine by setting them to Nothing. If you don’t, each object will remain active until you close Windows; the more objects you have active the more memory you take up, and at some point an overload will cause programs to freeze.

  1. Before the End Sub line, type in
    Set SAapp = Nothing

Your code should look as follows:

 
Next Tip

That's the end of this tip. So far we've created a macro project, created a subroutine within it, dimensioned the all-important Application object, and created an active instance of the Application object. Our next step will be to get information about the active encyclopedia, which we'll do in the next tip.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 3 of 11

This tip is the third of a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In the series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we created a macro project, module, and subroutine, and instantiated the Application object. In this tip we will get information about the active encyclopedia. Before we do that, however, we'll take a quick look at some of the tools available to us in VBA's environment.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. Your code should look as follows:
 
Using Tools of the VBA Environment

VBA provides three convenient tools that enable you to check your code as you write it, instead of having to compile and run it to see if you've done something wrong. Let's take a look at these tools before we continue coding our macro.

Setting a Breakpoint
  1. On the grey margin, next to the line of code Set SAapp = Nothing, click once inside the column. A red bullet will appear. You have set a breakpoint -- it will stop the code before it executes that command. What it means is that SAapp is active at the breakpoint.
 
Using the Step Into Command
  1. Right-mouse click in the toolbar, and select Debug. The Debug toolbar will appear. You can dock the Debug toolbar to the main menu frame.
  2. Notice that the Debug menu gives you a Step Into Command.
 
  1. Place your cursor anywhere in the top line of the code you have written so far. Click on the Step Into command button. Click it a second time. Notice that each time you click the command, a new line of code becomes highlighted, as you step through the code.
  2. With the following line highlighted: Set SAapp = New SA2001.Application, place your cursor over the SAapp object. Notice that a popup gives you a value of the object, SAapp = Nothing.
 
Using the Immediate Window
  1. Click the Step Into button again, to highlight the line Set SAapp = Nothing.
  2. Place your cursor into the Immediate window at the bottom of the IDE.
  3. Type in the following:
    ? “Hello”
    and hit Enter.

Notice that the word Hello is printed on the next line in the Immediate window. The question mark is a Visual Basic print command. You have just asked the Immediate window to print the word “Hello”, and it complied.

Getting the Encyclopedia

We will use these VBA tools as we code. Let's now get information from the SAapp object concerning an encyclopedia's name. Take another look at System Architect’s object model, at the Encyclopedia object. Notice that it has an attribute called FullName. Let's get it.

 

First we'll use the Immediate window to test our code; this is a quick way to make sure our code is correct. If it furnishes an acceptable answer, we'll add it to our subroutine.

  1. In the Immediate window, type the following:
    ? sAapp.
    (make sure you type the 'period')

    and from the ensuing drop-down list, select encyclopedia

  2. Type in a period (.) after encyclopedia. VBA’s intellisense gives you a drop-down of all properties and methods of the encyclopedia object.
  3. Select FullName . Your final code in the immediate window should look as follows:
    ? sAapp.Encyclopedia.FullName

Hit Enter. VBA provides you with the current encyclopedia path in the Immediate window.

Now that we know this code works, we can add it to our subroutine. We'll use the Debug command, which is an internal VBA object that has a print method. The Debug.Print object and method will replace the ? that we used in the Immediate window:

  1. In the code, just below the line Set SAapp = New SA2001.Application, type/select the following:
    Debug.Print SAapp.Encyclopedia.FullName
  2. Step through the code, and place your cursor on the SAapp object. You will get the encyclopedia path printed to the Immediate window.

Finally, let’s add some text to the print statement, so that in the future we know that we are printing the encyclopedia’s path/name.

  1. Change the above line to read:
    Debug.Print "Encyclopedia = " & SAapp.Encyclopedia.FullName

Now when you step through the code, the text “Encyclopedia =” is added in front of the encyclopedia path and name.

Next Tip

The encyclopedia object in itself does not give us too much interesting information. However, in the next tip, we will look at three objects it is related to – the Symbol, Definition, and Diagram objects – to get more information from the encyclopedia.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 4 of 11

This tip is the fourth of a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we got information about the active encyclopedia. This tip focuses on getting information on diagrams in an encyclopedia, and using the Encyclopedia object, the Diagram object, and a special set of collection objects, to do so. It's a long tip, but you'll learn some crucial information about using SA's object model.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. Your code should look as follows:
 
Getting the Diagram

In the previous tips, we dimensioned the Application object, created an active instance of it, and then from it, got the Encyclopedia object's name. Take another look at the object model. The Encyclopedia object is the aggregate of the Dagram object, the Symbol object, and of the Definition object. The Encyclopedia object contains zero or many Diagrams, zero or many Symbols, and zero or many Definitions. Also, a Diagram is the aggregate of the Symbol object; it contains zero or more Symbols (ie, a symbol cannot exist outside of a diagram). Each symbol is defined by zero or one Definition (ie, some symbols exist that have not been defined). A Definition may or may not have a Symbol associated with it (for example, a Class Method definition is not represented by a particular symbol of its own). We will use these relationships to get information about the encyclopedia's diagrams, symbols, and definitions.

 

System Architect Object Model

×
Collection Objects in the Object Model

Before we continue, let's discuss three important collection objects in System Architect's object model:

  • SAObjects,
  • SACollection, and
  • OfCollection

Normally, a collection is a list of objects at a particular point in time. Because System Architect is a network tool, it is harder to get a collection because it could take hours, in some cases, with large encyclopedias. For example, if you have a large network encyclopedia with 10,000 diagrams, and you ask for all diagrams in the encyclopedia, your code will start walking the encyclopedia, locking diagrams up, and take hours to complete. Because of this, System Architect's object model presents the three special collection objects mentioned above. All System Architect objects are stored in these special collections and are immediately available. Let's take a look at each one.

 
SAObjects:

SAObjects contains Diagrams, Symbols, and Definitions. SAObjects is a special collection that you have control over -- you can decide how many items to count into that collection, when it starts, when it stops, etc. You can use it, for example, to say "give me a count of all diagrams in an encyclopedia right now".

OfCollection:

OfCollection contains a list of properties inside a definition. For example, you can use this object to quickly get a list of elementary business processes that have roles associated with them.

Using SAObjects to Get Diagrams

So far in our macro, we have gone from the Application object to the Encyclopedia object; now we want to go from the Encyclopedia object to the Diagram object. We will use the SAObjects collection object to reduce the effort to do so.

First let's dimension a variable that will hold the diagrams.

  1. Type the following:
    ‘get a list of all diagrams in the encyclopedia
    Dim myDiagrams as sa2001.SaObjects

We have dimensioned the variable myDiagrams as an SAObjects container that can contain all of the diagrams. Now we want to set the variable myDiagrams as a list of all the diagram objects.

Before we do this, take another look at the object model. Notice that the Encyclopedia object contains a method called GetAllDiagrams. Note -- and this is important -- that you wouldn’t use a method to get the diagram name from the Diagram object, since this would only return a single diagram’s name. To get a collection of diagrams, you must go to the encyclopedia that the diagrams are contained in.

  1. Type in the following (selecting where appropriate using the drop-down lists of IntelliSense):
    Set myDiagrams = SA2001.Application.Encyclopedia.GetAllDiagrams
  1. Following good programming practice, we'll set the end of the loop. Hit your Enter key a few times to open up space in the code, and type in the following to end the object:
    Set myDiagrams = Nothing

Your code should look as follows:

 

In any normal collection that would do it – you would get all of your diagrams via the encyclopedia. But in System Architect, as we mentioned before, you don't want to we want to walk a network encyclopedia and potentially lock everybody up. We'll use the facilities of the SAObjects collection object to get the diagrams quickly.

Using Methods and Attributes of SAObject

Since we have dimensioned myDiagrams as an object of SAObject, when we type in ‘myDiagrams.’, we get a list of all properties and methods of SAObject.

The ReadAll Method:
  1. In the code, above the line Set myDiagrams = Nothing, type in:
    myDiagrams.ReadAll

We are saying go away and consciously read all the diagrams and add them to the collection. Let’s try it by stepping through the code:

  1. Place your cursor in the code, and press the Step Into button to walk through the code.
  2. Step to the point where myDiagrams=ReadAll is selected, then step again and count the seconds it takes to read all of the diagrams.

Diagram is now an object in the SAObject collection called myDiagrams. Let's now use some SAObjects attributes to get further information:

The Count Attribute:
  1. When the Set myDiagrams = Nothing command is highlighted, place your cursor in the Immediate window and type in:
    ? myDiagrams.Count
    and hit Enter.

You will receive a number of the diagrams in the currently open encyclopedia. It will give you an answer rather quickly.

 

Now let’s get a particular item in the SAObject collection. Let’s get the 10th diagram in the list, and get its name. The name of a diagram is actually one of its attributes. To get a complete list of a diagram object's attributes, take another look at the object model – all the available properties (or attributes) of the Diagram class are listed.

 
The Item Attribute:

The item attribute enables us to get at a particular item in the list. It takes a number as a parameter -- the number acts as an index.

 
  1. In the Immediate window, type in:
    ? myDiagrams.Item(10).Name
    and hit Enter.

You receive the 10th diagram in the Samples encyclopedia. Now let’s get the 16th diagram in the list, and get its type.

  1. Type the following in the Immediate window:
    ? myDiagrams.Item(16).Typename
    and hit Enter.

The type of the 16th diagram is garnered. Now let's get the person who last touched the 16th diagram.

  1. Type the following in the Immediate window:
    ? myDiagrams.Item(16).auditID
    and hit Enter.

You get the person’s name, in this example someone named Dave Rice.

Adding Code to the Subroutine

We've been using the Immediate window to play around with various methods and attributes. Now let's add a statement to the code to get the diagram's name.

We'll first dimension a new variable called myDiagram (previously we got myDiagrams, plural).

  1. Delete everything in the Immediate window, and place your cursor back into the code, in the blank area under myDiagrams.ReadAll.
  2. Type the following in the Immediate window:
    Dim myDiagram as SA2001.Diagram
    Set myDiagram = myDiagrams.Item(16)

Notice that after typing a period after myDiagrams, you get a drop-down list of all properties and methods of the collection.

  1. Alternatively, because Item is the default property of a collection, you can replace the .Item(16) with simply (16). Change the line above so that it reads:
    Set myDiagram = myDiagrams(16)

We now have a diagram object. We can use Intellisense to get all the properties and methods available for the diagram.

  1. Type in:Debug.
    Debug.print myDiagram.Name
  2. Reset the project (click the Reset button) and step through the code (clicking the Step Into button). When you step to the above line, the name of the 16th diagram is printed to the Immediate window.
Next Tip

We've done a lot in this tip; we examined collection objects and the three special ones provided in System Architect's object model. We journeyed from the Encyclopedia object to the Diagram object, getting information from both, using the SAObjects collection object as an aide. We played a lot in the Immediate window, and even found out that Dave Rice created the 16th diagram in the Samples encyclopedia. In the next tip we'll create a loop in our code to get information on a bunch of diagrams.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 5 of 11

This tip is the fifth in a series of tips that describes System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we found out the best ways to get information on diagrams in an encyclopedia. In this tip we'll create a loop to get information on a collection of diagrams.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. By taking the previous tips to this point, your code should look as follows:
 
Getting All the Diagrams

Last week we used the Diagram object's count and item attributes to get specific diagrams in an encyclopedia (ie, the 10th one created). Normally we won’t know how many diagrams there are in an encyclopedia. Let’s set up a loop to walk all the diagrams, and print out their name. We will replace the number 16.

  1. Add a line of space in the code, by hitting your Enter key between the lines:
    Dim MyDiagram As SA2001.Diagram
    and
    Set myDiagram = myDiagrams(16)
  2. At the end of the statement, Dim MyDiagram As SA2001.Diagram, add the following code -- , i as Integer -- so that the line reads as follows:
    Dim MyDiagram As SA2001.Diagram, i as Integer
  3. Begin a loop by adding the following line:
    For i = 1 To myDiagrams.Count
  4. In the Set myDiagram = myDiagrams(16) statement, replace the 16 with the variable i, so that the code reads:
    Set myDiagram = myDiagrams(i)
  5. At the end of the Debug.print myDiagram.Name statement, add a ‘Next i’ statement.

Your final code should look like this:

 
Stepping Through the Code

Now let’s step through the code.

  1. Click the Reset button to reset the project, then click the Step Into button repeatedly. Notice how, as you walk through the loop we have created, every time you step through the Debug.Print command, a new diagram name is printed to the Immediate window.

Let’s also print out the diagram’s type along with the name, getting it using the same myDiagram object.

  1. Add the following to the Debug.print command for the diagram:
    Debug.print myDiagram.Name & " -- " & myDiagram.TypeName
  2. Step through the code again. Notice that each diagram’s name and type is printed to the Immediate window.
Run the Program

Let’s now run our program in full.

  1. Click in the gray border to the left of the break we set before, to remove the break circle.
  2. Select Run, Run Sub/UserForm, or alternatively, click on the Run button on the menu. The program will run, and print out all of the diagram names and their types in the currently open encyclopedia.
 
Next Tip

In this tip we created a loop to get all diagrams in the encyclopedia, and their type. In the next tip we'll take a look at how we can filter the list of diagrams, so that we get specific ones.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 6 of 11

This tip is the sixth in a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we created a loop to get information on a collection of diagrams. In this tip we'll filter the list of diagrams to get specific ones.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. By taking the previous tips to this point, your code should look as follows:
Filtering the List of Diagrams

So far we have acquired and printed (to the Immediate window) all diagrams in the currently open encyclopedia. Now let’s get a particular diagram type – this will often be the case when building macros, when you only want to deal with a particular diagram type such as ER diagrams, Process Charts, Use Cases, etc.

  1. Go back to the line that reads:
    Set myDiagrams = SA2001.Application.Encyclopedia.GetAllDiagrams
    Delete the ‘.GetAllDiagrams’ syntax at the end of this statement, and replace it with ‘.GetFilteredDiagrams’, as shown below (be sure to type an open parenthesis at the end of the statement):
    Set myDiagrams =SA2001.Application.Encyclopedia.GetFilteredDiagrams(
 

Once you type in the open parenthesis, Intellisense will provide you with a pop-up that tells you the parameters and the parameter types for this method. There are two parameters: WildCardName, with a parameter type of String, and SAType, with a parameter type of Long.

For WildCardName, we must type in the name of the diagram as a text string. We will provide a null name (ie, nothing); this will get any diagram.

  1. Type in an open and closed quote with a comma, as shown:
    SA2001.Application.Encyclopedia.GetFilteredDiagrams("",

Now the SAType As Long parameter (which Intellisense makes bold) must be specified. Every diagram type in System Architect is known by a name and a number. For example, the diagram type “Entity Relation” is known by the type name “Entity Relation” and an internal number, 4.

Getting the Diagram Type's Internal Name and Number

Each diagram's type and internal number is specified in a file called Diagrams.bas, provided in System Architect's main executable directory. For ease of use, we can insert a module into our VBA project and import this file so that it's information is readily available.

  1. Right-mouse click on the Modules selection in the left-hand window of the VBA IDE, and select Import File.
 
  1. Browse to the System Architect main directory and select the Diagrams.bas file, and click Open.
 
  1. In the lower left-hand corner of the VBA IDE window, rename the new module Diagrams.
 
  1. Double-click on the Diagrams module in the upper left-hand window to open the module and examine it. This file, Diagrams.bas, contains a list of all diagrams with their internal name and number. It includes, at the end of the list, user diagrams that are provided so that users may create their own diagram types via USRPROPS.TXT (to create their own diagram type, a user renames one of the user diagrams).
 

For our example, we need either the diagram type’s internal name (starts with ‘GT’) or internal number.

Note: You may either use the diagram type’s internal name or number. It is preferred to use the name, since it is less apt to change than the number.

  1. In the left-hand pane, double-click on Example to get back to the code.
  2. After the comma that we previously typed in, type in GTOOUSECASE and close the parenthesis, so that the code looks as follows:
    SA2001.Application.Encyclopedia.GetFilteredDiagrams(“”,GTOOUSECASE)
  1. Reset the project (click the Reset button) and step through the code (click the Step Into button). Notice that two Use Case diagrams are printed to the Immediate window.
Next Tip

In this tip we filtered the list of diagrams to get specific ones. In the next tip we'll use the fact that we have a diagram, to get information on the diagram, and the symbols drawn on it.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 7 of 11

This tip is the seventh in a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we filtered the list of diagrams to get specific ones. This week we'll open a specific diagram, and get the symbols on that diagram.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. By taking the previous tips to this point, your code should look as follows:
 
Looking at Symbols

For this section of the tutorial, we will look at how to garner and manipulate symbols on diagrams. We will change our code so that we only look at a particular diagram, and focus on the symbols on it.

Reading a Particular Diagram In

Let’s continue using SAObject’s ReadAll function, and read a particular diagram in. Looking in the Samples encyclopedia, you can see that there are two Use Cases (we printed them to the immediate window earlier):

  1. In System Architect’s browser, select the All Methods tab, and open the Use Case diagram selection. There are two Use Case diagrams: Hotel Reservation Use Case Context and Make Reservation.
  2. In the VBA code, in the line specifying the diagram name, replace the null name (open and closed parenthesis) with the name Make Reservation, as shown below:
 

Because we know that we are specifying a single diagram, let’s remove from our code the loop that walked diagrams for this next part of the tutorial.

  1. From the end of the Dim myDiagram As SA2001.Diagram line, remove the ‘, i As Integer
  2. Remove the lines:
    For i = 1 To myDiagrams .Count
    and
    Next i
  3. Also, in the line Set myDiagram = myDiagrams.Item(i), change the ‘i’ to the number ‘1’.

Your code should now look as follows:

 

For the diagram print command, let’s specify that this is the diagram name, to separate it from the symbol names that we will soon go after.

  1. In the line Debug.Print myDiagram.Name & “—“ & myDiagram.TypeName, change the line to look as follows:
    Debug.Print “Diagram = “ & myDiagram.Name & “—“ & myDiagram.TypeName
Getting a List of All Symbols on a Diagram

Now we will get a list of symbols on a diagram. Our code will look similar to the code we wrote to get diagrams.

  1. Under the line Debug.Print "Diagram = " & myDiagram.Name & " -- " & myDiagram.TypeNameType, type in the following comment to explain the upcoming block of code:
    ‘get a list of all symbols for the diagram
  2. Type in the following to dimension a new variable mySymbols as an SAObjects collection:
    Dim mySymbols As SA2001.SAObjects

Since we already have diagrams in the collection ‘myDiagram’, we can get symbols from there.

  1. Type in the following:
    Set mySymbols = mydiagram.GetAllSymbols

We will use the ReadAll command to get all the symbols on the diagram.

  1. Type in:
    mySymbols.ReadAll
  2. Add the following command to print the number of symbols on the diagram:
    Debug.Print mySymbols.Count
  3. Step through the code (click the Step Into button on the menu). Notice that the number of symbols on the diagram is printed to the Immediate window.

Your code for this section should look as follows:

 
Add a Loop to Get Each Symbol on the Diagram

Finally, let's replace the count command, and instead add a loop to get each symbol on the diagram.

First let’s dimension a new variable that will catch each symbol as we walk the loop.

  1. Add the following to the end of the code line Dim mySymbols As SA2001.SAObjects, so that the line looks as follows:
    Dim mySymbols As AS20001.Saobjects, saSymbol As SA2001.Symbol
  2. Begin the loop -- add the following before the Debug.Print command:
    For i =1 To mySymbols.Count
    Set saSymbol = mySymbols(i)
    Debug.Print mySymbols.Count
  3. End the loop -- add the following after the Debug.Print command:
    Next i
  4. Finally, remove the Count command from the Debug.Print statement, and instead add code to get each symbol’s name and type -- change the Debug.Print mySymbols.Count command to look as follows:
    Debug.Print “Symbol = ” & saSymbol.Name & “ -- “ & saSymbol.Typename
    mySymbols.Count

Your code for should look as follows:

 
  1. Step through the code (by clicking on the Step Into button) to make sure your code is working correctly – you should get each symbols name and type printed to the Immediate window as you step through.
Next Tip

In this tip we got symbols on a diagram. In the next tip we'll get information about the symbols on the diagram.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 8 of 11

This tip is the eighth in a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we got a list of all symbols on a diagram. In this tip we'll get information about those symbols.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. By taking the previous tips to this point, your code should look as follows:
Getting Information on Symbols

Certain information about symbols (for example, name, typename, auditID, etc) is obtained directly from the symbol. To obtain diagrammatic information, however, you must have the diagram open. Diagrammatic information includes its color, size, positioning on the diagram, etc.

Let’s take a look at some of the properties of symbols that we can get at directly.

  1. First, place a ‘halt’ on the line Debug.Print "Symbol =" & saSymbol.Name & “ – “ & saSymbol.TypeName by clicking in the grey, left-hand margin. A red bullet will appear in the margin.
  2. Step through the code (clicking the Step Into button on the menu) until you highlight this line.
  3. Place your cursor in the Immediate window and type: ? sasymbol.Name and hit Enter. You will see the name of the current symbol printed in the Immediate window.
  1. Type ? sasymbol. UpdateDate and hit Enter. You will see the date when this symbol was last changed in the Immediate window.

Let’s try one more:

  1. Type ? sasymbol.FillColor and hit Enter. You will get an error message that tells you that you have a ‘Run-time error … Diagram is not open’.

System Architect is telling you that you must have a diagram open to get at this property (whereas the previous properties are all carried in the symbol). Let’s adjust our code to open a diagram.

Opening a Diagram

We will use the diagram object’s show and hide functions to open and close the diagram.

  1. In your code, after the statement in which you get the diagram,
    Set myDiagram = myDiagrams(1)
    add the following statement:
    myDiagram.show
    (be careful to type myDiagram, not myDiagrams)

This will open the diagram. After the loop to get all symbols, we must close the diagram.

  1. After the line Next i, add the line:
    myDiagram.Hide

Your code should look as follows:

Let’s now step through the code from the beginning of our program.

  1. Click the Reset button (rectangle) in the VBA toolbar (or select Run, Reset).
  2. Click on the Step Into button to begin walking through the code. Notice that stepping through the line myDiagram.Show opens the Use Case diagram that we specified in System Architect.
  3. Continue stepping into the code, walking the loop through symbols until the symbol Reject Customer Because of Bad Credit – Use Case appears in the Immediate window.

Now let’s get diagrammatic properties of this symbol.

  1. In the Immediate window, underneath the statement Symbol = Reject Customer Because of Bad Credit -- Use Case, type the following: ? sasymbol.FillColor and hit Enter.

    Notice that the ASCII code for the color is printed in the Immediate window.
  2. Type ? sasymbol.XPos and hit Enter. You will see the symbol's position from the top left-hand corner in hundreds of an inch (so 587 = 5.87 inches). Here we are reading the position of a symbol – remember that everything that we read we can also use to specify something; in this case, the Xpos and Ypos properties can be used to position symbols on a diagram if we were writing a macro that created a diagram automatically.
Next Tip

In this tip we got information on symbols, then opened a diagram and got diagrammatic information on a symbol. In the next tip we'll get the definition of a symbol.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 9 of 11

This tip is the ninth in a series of tips that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we got information on symbols, then opened a diagram and got diagrammatic information on a symbol. In this tip we'll open a specific diagram, get information about the definition of a symbol.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. By taking the previous tips to this point, your code should look as follows:

tipofw1_1.gif
 
Getting Definitions

Let’s take a look at the object model again. Remember that a symbol has zero or one definitions.

objectmodel3_small.gif
  1. Within the loop that gets symbols, after the statement:
    Debug.Print “Symbol = “ & saSymbol.Name & “ – “ & saSymbol.TypeName
    type the following lines of code:
    Dim mydef as SA2001.Definition
    Set mydef = sasymbol.Definition
    Debug.Print “Definition = “ & mydef.Name & “ -- “ mydef.TypeName
    Set mydef = Nothing

Notice that we specify the property Definition -- there is no GetDefinition – that is because there may not be a definition (as we said, there may or may not be a definition for a symbol – that is what is meant by the zero or one cardinality of the relationship). (Remember that a diagram has a collection of symbols, and a symbol may or may not have a definition.)

Let’s test the code by stepping through it. First we must be sure to close the diagram our code has opened in System Architect.

  1. In System Architect, close the Use Case diagram that was opened by previously stepping through the code.
  2. In the VBA IDE, click on the Reset button to reset the project.
  3. Click on the Step Into button to step through the code. Notice how the encyclopedia, diagram, symbol, and definition information is printed to the Immediate window.

Now we have a definition handle called mydef. Let’s take a look at the methods and properties available with the Definition object.

  1. At the end of the line of code Debug.Print “Definition = “ & mydef.Name, add the following: & “ -- “ mydef. and notice the drop-down list of available properties and functions once you type the period. There are a number of useful functions in the list.

The function GetRelatedObjects, for example, gets all relationship between objects in the repository – these are the same relationships used by the reporting system, such as “used by”, “is a”, “is defined by”, etc. Next week we'll take a look at a very useful function, GetPropertyAsCollection. For now, we will simply use the TypeName attribute to get the type of the definition.

  1. Complete the line as follows:
    Debug.Print “Definition = “ & mydef.Name & “ -- “ mydef.TypeName
    Your code for this area of the module should look as follows:
  1. In System Architect, close the Use Case diagram that was opened by previously stepping through the code.
  2. In the VBA IDE, click on the Reset button to reset the project.
  3. Click on the Step Into button to step through the code. Notice how the encyclopedia, diagram, symbol, and definition information is printed to the Immediate window, and the type of the definition is now provided next to the name of the definition itself.
Next Tip

In this tip we got the definition of a symbol; next week we'll examine using the GetPropertyAsCollection method.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 10 of 11

This tip is the tenth tip in a series that describe System Architect's VBA and show you how to build a simple macro that gets information from the repository. In this series, you create a macro, use System Architect's object model to access an encyclopedia, access diagrams in the encyclopedia, get symbols on a diagram, and get information from the definition of a symbol.

In the last tip, we got the definition of a symbol. In this tip we'll examine the advantages of using the GetPropertyAsCollection method.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. By taking the previous tips to this point, your code should look as follows:
tipofw2.gif
Using GetPropertyAsCollection

The function GetPropertyAsCollection is a very useful method of the Definition object that gets you a list of properties as a collection – this gives you more control on getting a list of properties than the GetRelatedObjects function.

For example, a Use Case definition contains a list of Use Case Steps – Use Case Step is a definition in itself. You can use the GetPropertyAsCollection to get all of the Use Case Step definitions as a collection, so that you may then work with each Use Case Step individually.

Let’s get Use Case Steps of a Use Case using the GetPropertyAsCollection method. To begin we will dimension a new variable called mySteps.

  1. Within your code, under the line
    Debug.Print "Definition = " & mydef.Name & " -- " & mydef.TypeName
    type in the following:
    Dim mySteps As OfCollection

Now we want to use the GetPropertyAsCollection method to get all of the Use Case Steps for the Use Case definition that we have a handle to.

  1. Type in:
    Set mySteps = mydef.GetPropertyAsCollection("Use Case Steps")

The GetPropertyAsCollection method needs the exact name of the property – in this case “Use Case Steps”.

Note: If you are unsure of the name of the property that you are getting, you should look it up in SAPROPS.CFG, contained in the encyclopedia path. Oftentimes the real name of a property is not the same as what shows up on a definition dialog; for example, in an Elementary Business Process of a Process Chart diagram, the "Locations" property is actually a rename – the real property is “Location Types”. You would only know this if you looked up the definition of an Elementary Business Process in saprops.cfg and saw that the property is actually called “Location Types” but has been ‘labeled’ “Locations”:

Property "Location Types" { Edit Listof "Location" Label "Locations" LENGTH 2000 HELP "Supporting Location Types (Matrix)" READONLY }

Let’s run through the code and see the results.

  1. Make sure that all diagrams are closed in System Architect, reset the VBA project (click on the Reset button), and click on the Step Into button to step through the code.

As you walk through, and get the first symbol and definition, which is that of a class, you get an error message that says “Property does not exist”. This is because we are trying to get the property “Use Case Steps”, but this property is not contained in a class definition, only a Use Case definition.

We need to set up a while loop that only invokes the GetPropertyAsCollection method if the definition type is that of a Use Case. We have the definition, and the definition object has a property called TypeName. Let’s use it.

  1. Before the line Dim mySteps As OfCollection, type:
    If myDef.TypeName = “Use Case” Then
  2. After the line Set mySteps = mydef.GetPropertyAsCollection("Use Case Steps"), end the loop by typing:
    Else
    End If

Your code should now look as follows:

  1. Close all System Architect diagrams, reset the project, and step into the code until you step through the first few Use Case definitions. You should be able to step through the definitions without any error messages popping up.
  2. Stop at the Set mydef = Nothing command, with the Use Case definition Make Reservation captured (see picture below).

Let’s use the immediate window to get some information about a Use Case Step.

  1. In the Immediate window, let’s print the number of Use Case Steps for a Use Case, using the Countmethod. Type in the following and hit Enter:
    ? mySteps.Count

Now let’s use the GetItem method to get the name of one of the items in the collection. Let’s get the name of the second Use Case Step in the definition:

  1. In the Immediatewindow, type in the following and hit Enter:
    ? mySteps.Item(2).Name

The name of the second Use Case Step in the definition will be printed to the Immediate Window.

Next Tip

In this tip we used the GetPropertyAsCollection function of the Definition object to get a step of a Use Case. In the next tip we will create a loop to get steps of all Use Cases, and then wrap up this series of VBA tips.

  1. Continue with the next tip, or select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.

 

Creating a VBA Macro -- Part 11 of 11

This is the last tip of this VBA series. By now you've been introduced to System Architect's VBA and learned what you can do with it, you've seen the object model and learned how to use it, and you've built a simple macro that gets information from the repository -- in particular you've gotten diagrams in the encyclopedia, symbols on a diagram, and information from the definition of a symbol.

In the last tip, we used the GetPropertyAsCollection method to get Use Case Steps from a Use Case definition. This week, we'll put the final touches on our macro by building a loop around our code to print out the names of all steps of a Use Case. Then we'll wrap the whole thing up.

If you have closed the work you did in the last tip, reopen it by performing the following steps:

  1. In System Architect, with the Samples encyclopedia open, select Tools, Macros, VBA Editor to open the VBA IDE.
  2. Within the IDE, open the Example module that we created in last week's tip. By taking the previous tips to this point, your code should look as follows:
Creating a Loop to Get the Names of the Use Case Steps

We learned in the last tip that once we used the GetPropertyAsCollection method to get all of the Use Case Steps of a Use Case in one fell swoop, we could use the immediate window's print command (the ?) to print out various properties of items in the collection. For example, we used ? mySteps.Count to get the count of the steps for any Use Case. To get the name of a particular step -- for example the second step -- we used the ? mySteps.Item(2).Name command.

Obviously, if we wanted to get all the steps of a Use Case, we'd have to 'walk' the collection -- set up a loop that would start at 1 and end with the total number of steps in any particular Use Case -- which is what mySteps.Count gives us.

So let's try it:

  1. In your code, after the statement in which you get the Use Case Steps as a collection,
    Set mySteps = mydef.GetPropertyAsCollection("Use Case Steps")
    add the following code:
    Dim j As Integer
    For J = 1 to mySteps.Count
       Debug.Print mySteps.Item(j).Name
    Next j

Pretty simple stuff -- we first tell Visual Basic that this new variable, j, that we are going to use to 'walk' the collection (in other words, it is an index) is an integer. Then for every Use Case Step collection that we encounter, we walk the collection, printing out the name of each 'jth' item -- or Use Case Step.

Seems simple, but maybe not. Let's try it.

  1. Make sure that all System Architect diagrams are closed (press the Reset button), and step into the code (press the Step Into button).
  2. Notice that you immediately get a compilation error -- ByRef argument type mismatch:

This is because the Item attribute was expecting a Long (you may have noticed this via intellisense as you were typing it in), but we set our variable 'j' to an Integer. We did this on purpose to make sure you were paying attention. Easily rectified:

  1. Change the line ByRef argument type mismatch to read:
    Dim j As Long
  2. Now step through the code, and you should see the Use Case Steps for the Use Case Make Reservation printed to the Immediate window.

Finally, let's tidy up our presentation a bit.

  1. Change the Debug.Print command to look as follows -- this will print the step number before each step:
    Debug.Print "Step " & j & ". " & mySteps.Item(j).Name
  2. Close any open diagrams, reset the project, and step through the code again. You will get the step number before the steps, as follows:
  1. Select File, Save Example and close the VBA environment by selecting File, Close and Return to SA2001.
That's Its

Ok, that's it for this 11-part series on learning VBA. Although it may seem like you've learned a lot, you've just touched on the beginning of an exciting world wherein you can manipulate System Architect to do what you'd like, for example:

  • Automatically export information directly into other tools, like Microsoft Word, or Access, or Project Manager, or some other third-party tool,
  • Automatically import information from a third-party tool into System Architect, so that you can use it in your designs,
  • Automatically create diagrams in System Architect from a compilation of other information,
  • Modify the behavior of the tool to suit you or your users needs,
  • Or simply figure out how to print the Use Case Steps of the macro we created above, to something more interesting than the Immediate window.

To answer these, and any other VBA questions, you can inquire about System Architect's advanced training courses. You can also check back regularly with UNICOM's series of tool tips.

 

Creating System Architect Diagrams, Symbols, and Definitions in VBA -- Part 1 of 7

System Architect's integrated support for Microsoft's Visual Basic for Applications and its development environment is a powerful feature that allows users to control SA's environment programmatically and develop many customizable solutions. This multi-part Tip of the Week series will explore the creation and manipulation of diagrams, symbols, and definitions that can be done within the System Architect VBA Editor. This behind-the-scenes, customizing functionality enables users to modify the way System Architect works to match their companies' business rules and processes, as well as add features to SA that are not available out of the box.

In our last VBA Tip series, Creating a VBA Macro, we introduced System Architect's support for VBA. Through the extensive eleven-part tip, we created a simple VBA Macro, while at the same time, explored the System Architect Object Model and its respective classes, attributes, and methods.

If you are unfamiliar with building a VBA macro and/or System Architect's Object Model, it is recommended that you go through the previous VBA Tip series, Creating a VBA Macro.

We left off from that Tip series with the following code:

 

 

Creating Diagrams

Let's add a new subroutine to our module that will create a diagram in System Architect.

  1. In the VBA IDE, select Insert, Procedure.
  2. In the Insert Procedure dialog, type Main2 as the name of the new procedure. (Keep its Type as Sub and its Scope as Public.)

Let's dimension a variable called sa as an sa2001 application. At this point, our module knows we are working with the application of sa2001, since we declared it at the top of the first subroutine. We really only need to dimension sa as application; however it is good practice to specify the 'sa2001' before 'application', since this will enable our code to be portable to other applications.

  1. Type in the following to dimension the sa variable, set it to the application, and free memory by setting it to nothing at the end:
    Dim sa As SA2001.Application
    Set sa = New SA2001.Application
    Set sa = Nothing

Let's now dimension a new variable, myDiagram, and use the encyclopedia's CreateDiagram method to create a Process Chart diagram.

  1. Dimension the new myDiagram variable by adding the following to the Dim sa As SA2001.Application:
    Dim sa As SA2001.Application, MyDiagram As SA2001.Diagram

Now let's use the Encyclopedia object's CreateDiagram method to create a new Process Chart diagram. We'll call it "My Diagram".

  1. Type in the following:
    Set MyDiagram = sa.Encyclopedia.CreateDiagram("My Diagram", 

As you type in the final comma, you see from the Intellisense pop-up that you need to specify the type of diagram for the CreateDiagram's second parameter -- SAType as Long.

  1. To get the internal constant name of the Process Chart's type, you must import the System Architect diagrams.bas file, which contains a list of every diagram's internal name and number, from the File, Import File menu. Double-click on the Diagrams module in the VBA IDE browser (upper left) to view the diagrams.bas file. Search the right-hand column for Process Chart. Once you find it, note that the diagram constant and number is GTCATPROCESSFLOW = 89.
  2. Finish the Set MyDiagram line by typing in the following:
Set MyDiagram = sa.Encyclopedia.CreateDiagram("My Diagram", GTCATPROCESSFLOW)

 

 

Let's test it and create a diagram.

  1. Make sure all System Architect diagrams are closed, reset the project (click the Reset button or select Run, Reset), place your cursor within the second subroutine (for example, in the Public Sub Main2( ), and step into the code (click the Step Into button or select Run, Step Into).
  2. Notice that a new Process Chart diagram is created and opened in System Architect. By default it has a first swimlane on it (two horizontal lines in the upper left-hand corner of the diagram workspace.
Model and Packaged Based Diagrams

Models and packages are used to facilitate and denote groupings of items (diagrams and definitions) as belonging to a particular model or package. This allows the re-use of commonly shared definitions among different models and packages while also allowing for the re-use of item names. The following is a list of all SA diagrams that are either model or packaged based.

 

 

If you are creating a diagram that is model or packaged based, then you MUST specify a model or packaged through the relevant property, SetProperty. For example:

Call myDiagram.SetProperty "Model","Sales"

Or

Call myDiagram.SetProperty "Package","Sales"

Note that by setting the Model or Package property, those items now belong to that particular model or package.

Next Tip

In the next part of this VBA Tip series we will add symbols to our newly created Process Chart diagram.

Creating System Architect Diagrams, Symbols, and Definitions in VBA -- Part 2 of 7

This tip is the second in a series of tips that explain how you can create and customize your own diagrams, symbols, and definitions by utilizing System Architect's integrated support for Microsoft's VBA and its development environment.

In the last tip, we created a Process Chart diagram from the encyclopedia's CreateDiagram method. This week we will add symbols to this new diagram by further accessing the System Architect Object Model.

Creating Symbols on a Diagram

We will use the CreateSymbol method of the diagram class to create symbols on the Process Chart we have created. We'll create two elementary business process symbols, and a Mandatory Sequence line symbol that is capable of linking the two EBP's. Let's first dimension three new variables to hold these symbols.

  1. Type in the following, above the Set MyDiagram = Nothing command:
    Dim saSymbol1 as SA2001.Symbol, saSymbol2 as SA2001.Symbol, saLineSymbol as SA2001.Symbol
  1. Now let's use the CreateSymbol method of the diagram object to create a new elementary business process symbol on the diagram. Type in the following:
    Set saSymbol1 = MyDiagram.CreateSymbol("Symbol 1", 

CreateSymbol is looking for two parameters, the first (Name as String) is a text string for the name of the symbol, which we call "Symbol 1". The second parameter (SAType as Long) is looking for the symbol type.

Note: We are not restricted to the symbol types belonging to the diagram we are working with - you can add any symbol from any diagram type onto the diagram. The only restriction is the toolbar of the diagram - System Architect only permits certain symbol types to appear on each diagram's toolbar - so you can't for example, add a Use Case symbol bitmap to a Process Chart diagram's toolbar, but you can, through VBA, add a Use Case symbol to a Process Chart diagram. This would be the same as if, in System Architect, you copied a symbol from one diagram and pasted it onto another.

For our example, we want to add an elementary business process symbol. Similar to when we were creating a new diagram, we need to know the internal constant name of the symbol we wish to create. To get this information for diagrams we imported the diagrams.bas file; to get this information for symbols we need to import the symbols.bas file.

  1. Right-mouse click on the Modules folder under Tutorial in the browser on the left-hand side of the VBA IDE, and select Import File.
  2. In the Import File dialog, browse to the System Architect main executable directory, select the symbols.bas file, and click Open.
  3. In the VBA IDE browser, under Properties, within the Alphabetic tab, highlight Module1 and rename it to Symbols.
  4. Double click on the Symbols icon in the browser to view the file.

Note: Finding the particular symbol that you want is tricky. There are many symbols of similar names appearing within different System Architect diagrams of different methodologies. There are a number of process type symbols, for example. If you are unsure which symbol is the correct one for the diagram, you can reference SA Diagrams and Symbols.pdf.

  1. Select Edit, Find and type in Symbol in the Find dialog. Click Find Next to begin searching the symbols.bas file.
  2. Continue clicking Find Next until you arrive at the Elementary Business Process symbol pictured below.

 

 

Notice that the constant name for this symbol is ETCATELEMBUSPROC. We will add this to our code. If you wish you can highlight this name and select CTRL-C to copy it and paste it into your code in the next step. Note: copying the internal constant number into the code (in this case 445) works just the same.

  1. Click on the Examples module in the VBA IDE browser to get back to the code.
  2. Complete the code line started above, by typing (or pasting) in:
    Set saSymbol1 = MyDiagram.CreateSymbol("Symbol 1", ETCATELEMBUSPROC)

Your code should look as follows:

Let's add another line of code almost identical to the one we have just typed, but this time make it create Symbol2.

  1. Add the following line:
    Set saSymbol2 = MyDiagram.CreateSymbol("Symbol2", ETCATELEMBUSPROC)

(Note: since this line is almost identical to the line we have just typed, the quick way to do this is select and copy (CTRL-C) the entire line you have just completed and paste (CTRL-V) it down again underneath, then change Symbol1 to Symbol2 for both occurences).

  1. Now let's create the line symbol. Type in the following:
    Set saLineSym = MyDiagram.CreateSymbol("Line",

Again, we must provide the constant name of the type of the line. We want to draw a Mandatory Sequence line. (On a Process Chart, Elementary Business Processes are connected to each other either by Mandatory Sequence lines or Optional Sequence lines.)

  1. Double-click on the Symbols module in the VBA IDE browser, and select Edit, Find. In the Find dialog, type Mandatory Sequence and click Find Next.

We again find many Mandatory Sequence symbols used in different diagrams in System Architect. The line we want is number 428, ETCATPDMANDATORYSEQ.

 

 

Step Through the Code

Let's now step through the code to see how it is working. Since we have already stepped through the code, we have already created a diagram called My Diagram. If we step through now, we will get an "SAIMF" error, since the code will be trying to create a diagram that already exists.

  1. In System Architect, close any open diagram and do not save it (choose No if you are presented with a dialog asking you to save the diagram).
  2. In the All Methods tab of the browser, expand Process Chart. If there is a diagram named My Diagram, right-mouse click on it and select Delete.

Now you are ready to step through the code.

  1. Reset the project (click the Reset button or select Run, Reset), place your cursor within the second subroutine (for example, in the Public Sub Main2(), and step into the code (click the Step Into button or select Run, Step Into).

Note how the diagram is created and the three symbols are added to the diagram.

 

 

Next Tip

We have just created a Process Chart and two Elementary Business Processes and a Mandatory Sequence Line in it. In the next tip we will explore ways to position our symbols with VBA.

  1. Click on File, Save Tutorial and exit the VBA Editor.

Important Note: DO NOT save My Diagram when closing System Architect! An SAIMF error will appear next time you step through the code, stating that "My Diagram already exists".

 

Creating System Architect Diagrams, Symbols, and Definitions in VBA -- Part 3 of 7

This is the third part in a series of VBA tips that show how a user can create and modify his own System Architect diagrams, symbols, and definitions. As stated previously, System Architect's support for Microsoft's Visual Basic for Applications can be very beneficial in modifying and extending SA functionality. So far, we have created a diagram and in the last tip we added three symbols to it.

In this tip we will show how you can use a line, link, or association symbol to connect other symbol, by utilizing the ConnectTo and ConnectFrom methods of the Symbol class. The following is the code we had written previously:

 
Making the Line Symbol Connect To Other Symbols

In our Process Chart, we created two elementary business processes and one mandatory sequence link. Now we must connect the two EBP's to show which route an object will follow in the Process Chart. We will use the symbol class' ConnectTo and ConnectFrom methods.

Let's try connecting the line symbol to the two EBP symbols.

  1. In the Immediate window, type:
    SaLineSym.ConnectTo(

Notice that the ConnectTo method needs a Line as Symbol as a parameter. Since we are already working with the line, this is obviously not the way to go. Let's instead start with one of the symbols, and specify that the line get connect from/to it.

  1. Delete that line, and type in the following:
    SaSymbol1.ConnectFrom(

Again, it is asking for Line as Symbol for its parameter. Add the following to the line and hit Enter:

SaSymbol1.ConnectFrom(saLineSym)

When you hit Enter, you should get an error message that says Run-time error.. Object doesn't support this property or method. When you type a parenthesis around the method's parameter, the method will provide a return type; you would normally have an '=' at the front of the line, specifying a variable that the return is put into. For our example, we don't need to use the method this way; we'll simply delete the open/close parenthesis.

Adjust the line in the Immediate window to look as follows:

SaSymbol1.ConnectTo saLineSym

and hit Enter.

Take a look at the diagram, and notice that the line symbol has been connected to the first EBP symbol.

 

Let's use the ConnectFrom method to connect the line to the other symbol.

  1. In the Immediate window, type the following:
    SaSymbol2.ConnectFrom saLineSym
    and hit Enter.

The two EBP symbols should now be connected to each other by the line.

 
  1. Select the two lines of code you have written into the Immediate window, cut them (CTRL-X) and paste them (CTRL-V) into your code, so that your code looks as follows:
 
Next week

We have just connected two symbols with a line symbol in VBA, an important step in creating a detailed and useful diagram. In the next tip, we will explore how you can position the symbols anywhere on the diagram.

  1. Click on File, Save Tutorial and exit the VBA Editor.

    Important Note: DO NOT save My Diagram when closing System Architect! An SAIMF error will appear next time you step through the code, stating that "My Diagram already exists".

 

Creating System Architect Diagrams, Symbols, and Definitions in VBA -- Part 4 of 7

This is the fourth part in a series of tips, in which we are exploring System Architect's ability to customize its application behavior and extend application functionality through its integrated support of Microsofts VBA. We have already created a Process Chart diagram and three symbols by utilizing the SA Object Model, and last week we connected two Elementary Business Processes with a Mandatory Sequence Link.

In this tip we will show how you can position symbols on a diagram in VBA. This is especially useful if you importing symbols from another diagram. By setting the XPos and YPos attributes in VBA, you can prevent the symbols from being imported on top of each other in the new diagram.

So far, our code in the subroutine looks as follows:

 
Positioning the Symbols on the Diagram

Let's now use the XPos and YPos properties of the symbol object to place one of the symbols on the diagram.

  1. In the previous exercise, you should have stepped to the Set MyDiagram = Nothing command. Set a breakpoint at this Set MyDiagram = Nothing line (click your cursor in the left margin so that a red bullet is placed in the margin).
  2. In the Immediate window, type the following:
    SaSymbol1.XPos = 200
    and hit Enter.
 

Notice how Symbol1 is moved on the diagram.

  1. Experiment with this command a little - change 200 to 1000 and hit Enter, and notice where the symbol is placed on the diagram. Change the XPos number to 350, and hit Enter again.

Now let's try the YPos command.

  1. In the Immediate window, under the line you just typed, add a new line - type:
    SaSymbol1.YPos = 400
    and hit Enter.

Notice how Symbol1 is moved on the diagram.

  1. Change the YPos number to 200, and hit Enter again. See where the symbol has moved on the diagram.

    Note:
    As mentioned previously, the Immediate window is a great place to experiment with code, before actually adding it to your real code and having to step through the code to see the results. It gives you immediate feedback.
  2. Cut the lines out of the Immediate window (select both lines and hit CTRL-X), and paste (CTRL-V) them into your code, above the line Set MyDiagram = Nothing.
Next Tip

Setting the location of the symbols in our diagram is just one example of using the Symbol Class attributes to enhance the design and add utility to the diagram. In the next tip, we will experiment more with the aesthetic attributes of symbols in our diagram.

  1. Click on File, Save Tutorial and exit the VBA Editor.

    Important Note:
    DO NOT save My Diagram when closing System Architect! An SAIMF error will appear next time you step through the code, stating that "My Diagram" already exists.

 

Creating System Architect Diagrams, Symbols, and Definitions in VBA -- Part 5 of 7

This is the fifth part in a series of VBA tips, in which we will demonstrate how the user can create and customize his or her diagrams, symbols, and definitions in System Architect. From within the VBA editor in the Tools, Macros menu, we created a Process Chart and two elementary business processes connected by a line symbol.

In the last tip, we explored the positioning of a symbol in the diagram. In this tip, we will take a closer look at the many properties available to the user within System Architect. We will experiment with the Symbol Fields as well as some more Symbol class attributes to use in manipulating the aesthetics of our diagram.

We finished last week with the following code:

 
Manipulating the Aesthetics of Symbols on a Diagram

Every symbol has a number of properties associated with it. Many of these are accessible directly through the object model; additional ones are available through the SetField method of a symbol.

  1. In the Immediate window, type the following (making sure to type the period at the end) and view the drop-down list of properties and methods):
    SaLineSym.
 

Notice you can set properties such as FillColor, FontColor, PenColor, PenStyle, etc. These properties were added to the object model because they were deemed the most used properties. However, there are a raft more that can be set or obtained by using the SetField or GetField methods. This internal collection of properties is know as the Symbol Fields.

  1. Type the following in the Immediate window (be sure to type the open parenthesis):
    SaLineSym.SetField(
 
  1. Review the list of field properties for a symbol that you can set. All of these properties are explained in the Extensibility Guide.
  2. We will select the field that sets the location of the line symbol's name. Select SYMFLD_NAMELOC and provide a value as a text string - in quotations specify an X-position of 400 and a Y-position of 190 -- completing the line in the Immediate window as follows:
    saLineSym.SetField (SYMFLD_NAMELOC, "400 190")
    then delete the open and closed parenthesis to make the line:
    saLineSym.SetField SYMFLD_NAMELOC, "400 190"
  3. Hit Enter and view the open diagram in System Architect. Note how the name of the line symbol has been repositioned.
  4. Cut and paste this line from the Immediate window into your code, above the Set MyDiagram = Nothing line.
Coloring Symbols

To color a symbol, you must specify an RGB (red, green, blue) color. Exact numbers for RGB colors can be found in most paint programs - for example, black is (0 0 0), red is (255 0 0), green is (0 255 0), blue is (0 0 255), white is (255 255 255), purple is (192 0 192), etc.

Let's change the color of the first EBP symbol to red.

  1. In the Immediate window, type in the following:
    Sasymbol1.FillColor = RGB(0, 0, 255)
    and hit Enter. Notice how the color of Symbol1 changes to blue on the diagram.
  2. Cut and paste this line into your code, placing it under the line that reads Set saSymbol1 = MyDiagram.CreateSymbol("Symbol1", ETCATELEMBUSPROC).
  3. Let's change the color of the other symbol to blue, adding the following line:
    Sasymbol2.FillColor = RGB(0, 0, 255)
    underneath Set saSymbol2 = MyDiagram.CreateSymbol("Symbol2", ETCATELEMBUSPROC)
Save the Diagram

Finally, let's add a command to save the diagram. This will save the our diagram and symbols in the System Architect repository. Note: if you do not invoke the Save attribute, all the symbols on the "My Diagram" diagram will be deleted when you close System Architect. Thus, it is necessary to save the diagram at the end of our macro.

  1. Before the line Set MyDiagram = Nothing, add the following statement:
    MyDiagram.Save

Your final code should look as follows:

 
  1. Save the VBA project by selecting File, Save Tutorial in the VBA IDE.
Next Tip

In this tip we illustrated how using the Symbol Fields can add to our design, and experimented with the FillColor attribute to add a bit of flavor to the diagram. In the next tip, we will create a definition and later on explore its meta properties.

 

Creating System Architect Diagrams, Symbols, and Definitions in VBA -- Part 6 of 7

This is the sixth part in a series of VBA tips showing how a user can create and manipulate diagrams, symbols, and definitions from within System Architect's VBA Editor. In the last tip and before, we have created a diagram and placed upon it several symbols. We then modified and experimented with the aesthetics of our symbols, by utilizing the Diagram and Symbol classes' attributes and methods as well as the Symbol Fields.

In this tip we will begin with a new subroutine and create a new SA definition by using the Encyclopedia class' CreateDefinition method.

Creating Definitions

Let's start a new subroutine in which we will create a definition.

  1. In the VBA IDE, select Insert, Procedure.
  2. In the Insert, Procedure dialog, type Main3 as the name of the new procedure. (Keep its Type as Sub and its Scope as Public.)
  3. Like we did when we created a diagram, add the following code to dimension a variable and set it to a System Architect application, and then free its memory.
    Dim sa as SA2001.Application
    Set sa = New SA2001.Application

    Set sa = Nothing

Now we will dimension a new variable, myDefinition, and use the Encyclopedia Class' CreateDefinition method to create a new Elementary Business Process definition, which we will call "My Definition".

  1. Dimension the new myDefinition variable by adding the following to Dim sa as SA2001.Application:
    Dim sa as SA2001.Application, myDefinition as SA2001.Definition
  2. Create a new Elementary Business Process by typing the following:
    Set myDefinition = sa.Encyclopedia.CreateDefinition("My Definition",

As you type in the final comma, you see from the Intellisense pop-up that you need to specify the type of definition for the CreateDefinition's second parameter -- SAType as Long.

  1. To get the internal constant name of the Elementary Business Process' type, you must import the System Architect defns.bas file, which contains a list of every definition's internal name and number, from the File, Import File menu. Double-click on the definitions module in the VBA IDE browser (upper left) to view the defns.bas file. Search the right-hand column for Elementary Business Process. Once you find it, note that the diagram constant and number is DFXELEMBUSPROC = 308.
  2. Finish the Set myDefinition line by typing in the following:
    Set myDefinition = sa.Encyclopedia.CreateDefinition("My Definition", DFXELEMBUSPROC)

Quick Tip: You can take advantage of the intellisense features of VBA by pressing ctrl & spacebar and then typing DFX to go to the first definition type n the list of constants.

 
Saving the Definition

The definition is NOT saved in the encyclopedia and will automatically deleted if you do not use the Save method.

  1. Type the following above the Set myDefinition = Nothing line to save My Definition in the encyclopedia:

Your code should look like the following:

 

After stepping through the code, the Elementary Business Process definition, My Definition, should appear in the System Architect browser.

 
Keyed Definitions

Keyed definitions exist where the definition name is only unique within the context of any keyed fields. For example, an Entity in an Entity Relation diagram is only unique within a given Model. Therefore, the Model Name keys the Entity or the Entity is keyed by the Model Name.

To set the key properties for a definition, you will need to use the SetProperty method of the Definition class. For example, in the case of the an Attribute of an Entity, you might type:

myDefinition.SetProperty "Model", Chr(34) & "Main Model" & Chr(34)
myDefinition.SetProperty "Entity Name", "Customer"

Some definition types require that you must set the keys before you save the definition. These definitions have the term REQUIRED placed within their syntax in the saprops.cfg file.

Next Tip

The next tip will be the last in this series of VBA tips. We will explore the MetaItem and MetaProperties classes and retrieve the metaproperties of the definition we created in this tip.

 

Creating System Architect Diagrams, Symbols, and Definitions in VBA -- Part 7 of 7

This is the last part in a series of tips that go through the steps of writing a VBA macro that creates SA diagram, symbols, and definitions. So far we have created a Process Chart, added two node symbols and connected them with a line symbol, and adjusted the symbol attributes and fields to add to the aesthetics of the diagram. In the last tip we created an Elementary Business Process definition.

In this tip we will create an SACollection of MetaProperties belonging to the definition and retrieve selected ones through a For…Next loop.

Retrieving Definition Meta Data

System Architect's definitions are held inside an encyclopedia. The encyclopedia understands the structure and composition of the definition types inside the encyclopedia. The System Architect Object Model allows you to access the structure and composition of the definition types inside the encyclopedia by using the meta classes. The only way to modify the meta classes in the encyclopedia is through the USRPROPS.TXT file.

The MetaItem Class

The MetaItem class allows you to return meta information about the current definition. The MetaItem properties you can retrieve are:

  • Class Attribute - returns 1 for a Diagram type definition, 2 for a Symbol, and 3 for a Definition.
  • TypeName Attribute - the textual name used for the definition, i.e. Class Attribute
  • TypeNumber Attribute - the System Architect assigned constant number for the definition (a list of definition TypeNumbers exists in the System Architect defns.bas file)
The Definition MetaProperties

Each item in the encyclopedia has associated properties. For example, when you are editing an Entity, you will notice that it has Volume, Business Description, etc. as properties. You can extract further detail about the properties for a definition type by accessing the MetaProperty class. This class opens the door to attributes that define the structure of the definition property, such as Name, Edit Type, and Default Value. A complete list of MetaProperty attributes can be found in the System Architect Object Browser.

We will take a look at the Meta Properties of the definition we created last week by retrieving the MetaProperties attribute of the MetaItem class. This will return a collection of MetaProperty classes for our definition.

  1. First, we must create a collection of MetaProperty classes for the definition, "My Definition", by typing the following:
    Dim metColl as SACollection
    Set metColl = myDefinition.MetaItem.MetaProperties
  2. Now we will dimension an integer to serve as a counter, with which we will retrieve each individual MetaProperty class of the definition. Type in the following:
    Dim i as integer

In order to print the collection of meta properties, we need to insert a For...Next statement. This will create a loop that will repeat itself as many times as there are meta properties in the collection.

  1. To create the loop, type in the following:
    For i = 1 To myColl.Count
    Next i

Note: The Count attribute of the SACollections class is the numeric value of the number of collection members, which we are therefore using as the last value of the counter.

Within our loop, let's print several of the MetaProperty attributes.

  1. After For i = 1 to myColl.Count, insert the following code:
    With myColl.Item(i)
    Debug.Print .Name, .EditType, .EditLength
    End With

Note: Using a With...End With statement allows you to only refer to the object once.

  1. Run the macro. In the Immediate window, you should be able to see that the Debug.Print command has printed the Name, Edit Type, and Edit Length of every meta property of the definition.
 
Wrap Up

This concludes our second series of tips on System Architect's integrated support for Microsoft Visual Basic for Applications. With VBA you can extend System Architect functionality in many ways. Through System Architect's extensive Object Model, you can access and utilize numerous attributes, methods, and fields to build macros that better suit your company's needs and specifications. By mastering VBA, you can enhance the overall precision and effectiveness offered by System Architect.