Enterprise Architect Datenmodell (EA API)

 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 element.ParentID. The ParentID is 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 collection.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 collection.Add(<name>,<type>), you get a new instance, the container id (PackageID or 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" );
newAttribute.Update();
attributes.Refresh();

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.