Many of you already know that EA consists of an API which can be used to programmatically access and manipulate the model and much more as just the model. This article shows the core types of the EA API which are used to manipulate the model. The entry point is an instance of type Repository. The repository allows access to the model and also to other project data as well as to the EA client UI. Navigating through the Object Model The repository provides a property “Models” (
repo.Models) which provides a collection of root packages. The root package is a special kind of package. That means it do not provide all possibilities of “normal” packages. The API takes care of it. For instance, setting the stereotype of a root package cause no error, but has no effect. A Package (except the root package) may contain diagrams (
package.Diagrams), elements (
package.Elements) or additional sub-packages (
package.Packages). All these properties return the type “Collection”, which is a kind of factory type. With the collection you can create additional Packages, Elements, Diagrams, etc. with the operation
collection.AddNew(string, string). The next section describes the manipulation of the object model in details. Each type in the EA API provides an ID. EA references all objects by this ID or by the element’s global unique ID (GUID). The ID is unique for the current DB, the GUID is globally unique! With the ID you can navigate through the model. For instance, if you have an instance of a model element, you can navigate to its package with
element.PackageID or to its parent element with
0 if the element is not nested within another element. Hence, the parent id is a different concept as the package id. If Element B is nested within element A and element A is in Package1,
B.PackageID == A.PackageID, because both elements are contained in the same package and
B.ParentID == A.ElementID, because B is nested within A! Hence, when you call
element.PackageID, you only get the id of the package and not the package itself. The get the corresponding package, you can call
repo.GetPackageByID(element.PackageID). Manipulating the Object Model Whenever you have an instance of a type (e.g. Package, Element, Connector, Method, etc.) you can manipulate that instance and store it again. Manipulation is simple, just set the values of the properties. To persistent your changes call
XXX.Update(). When you call update, the changes are stored again in the DB. If you forget to store your changes, they will get lost! To create new elements, you need a collection. The Collection is a kind of factory and provides a new instance with the operation c
ollection.Add(<name>,<type>). Which type is created depends on the property you have called. For instance,
package.Elements provides a collection to create new elements.
Package.Packages provides a collection to create new packages. The new created object lives only in your memory and must be persisted with the call of
element.Update()! If you create a new element with
EA.Element newElement = package.Elements.AddNew( "myNewClass", "Class" )
you get a new instance of type class with name
myNewClass. However, you can also set the name and the type, as well the container package or container element with the element’s properties.
element.Type = "Class"
element.Name = "myNewClass"
element.PackageID = 12 // the package id of the package which should contain this element
Tip: If you do not know which parameter you have to set in the
Add(<name>,<type>) operation, just provide an empty string and set the values with the type’s properties. Remember: Don’t forget to call
element.Update() when you have modified an element! When you have created a new element with the collection-factory operation c
ollection.Add(<name>,<type>), you get a new instance, the container id (
ParentID) of the new instance is automatically set. When you store the element, that element is contained in the package or element (this information is just stored in the DB), but you current object model, representing your model in memory, doesn’t contain the new instance. Hence, you have to refresh the collections when you have added a new instance. To refresh a collection, call
collection.Refresh(). This will reload all elements contained in this collection. Remember: to assure to work on the latest version of the repository, call
collection.Refresh() at any collection before you access this collection! The required update and refresh operations are always the same, independent what types are manipulated! Here is an example for the attributes of an element:
var attributes as EA.Collection;
attributes = theElement.Attributes;
var newAttribute as EA.Attribute;
newAttribute = attributes.AddNew( "m_newAttribute", "string" );
Deleting elements Elements, packages, etc. can also be deleted! To delete an element you just get the collection which contains that object and call
collection.DeleteAt(index). Here is a short example:
// Delete the attribute we just added ' List attributes for i = 0 to attributes.Count - 1 dim currentAttribute as EA.Attribute set currentAttribute = attributes.GetAt( i ) ' Delete the attribute we added if currentAttribute.AttributeID = addedAttributeID then attributes.DeleteAt i, false end if next
With this overview it should be possible to start automating you Enterprise Architect models.
Here you can find the EA API Model contained in an EA-Repository (.eapx).
Additional code examples can be found in the Local Scripts folder in EA’s scripting view. The scripting view can be found (in EA Version 12) in the main menu [View | Scripting]. If you would like more support or training, please visit our web page.