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.
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.
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 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.
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:
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.
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.
Now let’s open this Tutorial project and add code to it.
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.
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.
Sub Main()and hit Enter
End Sub
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.
Let’s dimension an Object. Dimensioning an object makes space for it in memory.
Dim SAapp Asand 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.
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.
To make the Application object active we have to create an instance of this object:
Set SAapp = New SA2001.Application
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.
Set SAapp = Nothing
Your code should look as follows:
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.
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:
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.
? “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.
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.
? sAapp.(make sure you type the 'period')
? 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:
Debug.Print SAapp.Encyclopedia.FullName
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.
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.
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.
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:
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.
Before we continue, let's discuss three important collection objects in System Architect's object model:
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 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 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.
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.
‘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.
Set myDiagrams = SA2001.Application.Encyclopedia.GetAllDiagrams
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.
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.
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:
Diagram is now an object in the SAObject collection called myDiagrams. Let's now use some SAObjects attributes to get further information:
? myDiagrams.Countand 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 enables us to get at a particular item in the list. It takes a number as a parameter -- the number acts as an index.
? myDiagrams.Item(10).Nameand 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.
? myDiagrams.Item(16).Typenameand hit Enter.
The type of the 16th diagram is garnered. Now let's get the person who last touched the 16th diagram.
? myDiagrams.Item(16).auditIDand hit Enter.
You get the person’s name, in this example someone named Dave Rice.
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).
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.
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.
Debug.print myDiagram.Name
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.
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:
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.
Dim MyDiagram As SA2001.Diagramand
Set myDiagram = myDiagrams(16)
Dim MyDiagram As SA2001.Diagram, i as Integer
For i = 1 To myDiagrams.Count
Set myDiagram = myDiagrams(i)
Your final code should look like this:
Now let’s step through the code.
Let’s also print out the diagram’s type along with the name, getting it using the same myDiagram object.
Debug.print myDiagram.Name & " -- " & myDiagram.TypeName
Let’s now run our program in full.
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.
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:
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.
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.
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.
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.
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.
SA2001.Application.Encyclopedia.GetFilteredDiagrams(“”,GTOOUSECASE)
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.
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:
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.
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):
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.
For i = 1 To myDiagrams .Countand
Next i
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.
Debug.Print “Diagram = “ & myDiagram.Name & “—“ & myDiagram.TypeName
Now we will get a list of symbols on a diagram. Our code will look similar to the code we wrote to get diagrams.
‘get a list of all symbols for the diagram
Dim mySymbols As SA2001.SAObjects
Since we already have diagrams in the collection ‘myDiagram’, we can get symbols from there.
Set mySymbols = mydiagram.GetAllSymbols
We will use the ReadAll command to get all the symbols on the diagram.
mySymbols.ReadAll
Debug.Print mySymbols.Count
Your code for this section should look as follows:
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.
Dim mySymbols As AS20001.Saobjects, saSymbol As SA2001.Symbol
For i =1 To mySymbols.Count
Set saSymbol = mySymbols(i)
Debug.Print mySymbols.Count
Next i
Debug.Print “Symbol = ” & saSymbol.Name & “ -- “ & saSymbol.Typename
mySymbols.Count
Your code for should look as follows:
In this tip we got symbols on a diagram. In the next tip we'll get information about the symbols on the diagram.
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:
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.
Let’s try one more:
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.
We will use the diagram object’s show and hide functions to open and close 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.
myDiagram.Hide
Your code should look as follows:
Let’s now step through the code from the beginning of our program.
Now let’s get diagrammatic properties of this symbol.
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.
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:
Let’s take a look at the object model again. Remember that a symbol has zero or one definitions.
Debug.Print “Symbol = “ & saSymbol.Name & “ – “ & saSymbol.TypeNametype 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.
Now we have a definition handle called mydef. Let’s take a look at the methods and properties available with the Definition object.
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.
Debug.Print “Definition = “ & mydef.Name & “ -- “ mydef.TypeNameYour code for this area of the module should look as follows:
In this tip we got the definition of a symbol; next week we'll examine using the GetPropertyAsCollection method.
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:
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.
Debug.Print "Definition = " & mydef.Name & " -- " & mydef.TypeNametype 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.
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.
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.
If myDef.TypeName = “Use Case” Then
Else
End If
Your code should now look as follows:
Let’s use the immediate window to get some information about a Use Case Step.
? 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:
? mySteps.Item(2).Name
The name of the second Use Case Step in the definition will be printed to the Immediate Window.
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.
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:
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:
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.
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:
Dim j As Long
Finally, let's tidy up our presentation a bit.
Debug.Print "Step " & j & ". " & mySteps.Item(j).Name
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:
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.
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:
Let's add a new subroutine to our module that will create a diagram in System Architect.
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.
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.
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".
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.
Set MyDiagram = sa.Encyclopedia.CreateDiagram("My Diagram", GTCATPROCESSFLOW)
Let's test it and create a diagram.
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.
In the next part of this VBA Tip series we will add symbols to our newly created Process Chart diagram.
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.
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.
Dim saSymbol1 as SA2001.Symbol, saSymbol2 as SA2001.Symbol, saLineSymbol as SA2001.Symbol
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.
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.
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.
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.
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).
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.)
We again find many Mandatory Sequence symbols used in different diagrams in System Architect. The line we want is number 428, ETCATPDMANDATORYSEQ.
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.
Now you are ready to step through the code.
Note how the diagram is created and the three symbols are added to the diagram.
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.
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".
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:
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.
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.
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.
SaSymbol2.ConnectFrom saLineSymand hit Enter.
The two EBP symbols should now be connected to each other by the line.
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.
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:
Let's now use the XPos and YPos properties of the symbol object to place one of the symbols on the diagram.
SaSymbol1.XPos = 200and hit Enter.
Notice how Symbol1 is moved on the diagram.
Now let's try the YPos command.
SaSymbol1.YPos = 400and hit Enter.
Notice how Symbol1 is moved on the diagram.
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.
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:
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.
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.
SaLineSym.SetField(
saLineSym.SetField (SYMFLD_NAMELOC, "400 190")then delete the open and closed parenthesis to make the line:
saLineSym.SetField SYMFLD_NAMELOC, "400 190"
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.
Sasymbol1.FillColor = RGB(0, 0, 255)and hit Enter. Notice how the color of Symbol1 changes to blue on the diagram.
Sasymbol2.FillColor = RGB(0, 0, 255)underneath Set saSymbol2 = MyDiagram.CreateSymbol("Symbol2", ETCATELEMBUSPROC)
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.
MyDiagram.Save
Your final code should look as follows:
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.
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.
Let's start a new subroutine in which we will create a definition.
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".
Dim sa as SA2001.Application, myDefinition as SA2001.Definition
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.
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.
The definition is NOT saved in the encyclopedia and will automatically deleted if you do not use the Save method.
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 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.
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.
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.
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 allows you to return meta information about the current definition. The MetaItem properties you can retrieve are:
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.
Dim metColl as SACollection
Set metColl = myDefinition.MetaItem.MetaProperties
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.
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.
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.
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.