Category Archives: VBA

Information relating to the use of VBA within automation

Customising EA

In my last post I started to look at how we can access tools from within EA by customising the tools menu.  My plan was to continue looking  at accessing tools however in starting to pull together ideas for this post, I realised that I was going to be talking about stuff which may be new to some.  So I thought that I should step back and, rather than continue with detail, provide an overview of the range options that exist for customising or enhancing EA.  With that in place, it should make it easier to delve into the detail for each area in turn. I can then use this as a reference for my exploring (and posts).

An EA programming model

To help with the descriptions I’ll start by presenting a version of my EA programming model.   I always like a picture to help me understand the components and relationships.

Below is a diagram that provides my view of EA and the interfaces that it provides within the our current area of interest.

An EA Programming Model

My “EA Programming Model”

So let me describe each component in turn.

The Enterprise Architect world box within the green boundary contains those components that are within and managed by EA.  The boxes outside (green and brown) represent components that are outside of EA.  The EA Database is placed on the boundary as, by default, EA provides its own database engine to work with EAP files or could be configured to use a server based database, which would be completely outside of EA (please don’t complain about the detail of this point!)

So starting with the Enterprise Architect world box:

  • EA – represents the EA code, UI and all the bits I’m not going to discuss any further.
  • EA Database – already covered above, so no further discussion at present

Then possibly the 2 most important components for anybody enhancing EA:

  • The EA Object Model  presents an API through which other components can access information within the EA Model and perform a wide range of tasks.  It is through this interface that changes to the EA model (and underlying database are made).
  • The EA AddIn Framework supports the use of external code (DLL) to enhance the functionality of EA.  The ability to produce your own code that can be recognised and integrated with EA is a brilliant step in making EA the powerful and flexible tool it is. More on this later.

There is one more component in the box:

  • The Scripting engines.  EA provides several scripting engines that are accessed within the EA UI, and hence always within the context of the current EA model.  These scripts can make use of other libraries which are provided as well as access external services. NOTE: Scripting is not available in the Desktop or Professional editions, and not all libraries are provided in the Corporate edition.

So now let’s look outside of the green box:

  • The External Client Application represents a windows application that can connect to the EA Object Model API.  The function of these applications could be varied and really only limited to the imaginative of the developer.
  • My AddIn DLL represents the most powerful and flexible type of enhancement implemented between EA and 3rd party code. Using the EA Addin Framework the AddIn will be known to EA and becomes an integral part of the running process whose functionality defined by the developer.

From this brief outline we can now look at the capabilities of the key programmable components in some more detail.
Scripting

I’ll start with Scripting, which is probably the easiest means for enhancing EA, not least as the capability to write and run scripts is provided within EA.  The user can write scripts within EA using a either VBScript, JScript or JavaScript.

Here are the basic steps to getting going with scripting. You access the scripts and script editing use “Tools | scripting”.

There are different types of scripts within EA, used for different purposes.  A quick look at the group menu items lists the groups that are provided – illustrated below.

EA Script Types for different purposes

EA Script Types for different purposes

If you look at the scripts tab you will see scripts in these different groups.  You can select an existing group or create a new group and then create a new script – as below.  Note:  Some groups may be read-only.

Create a new script

Create a new script

If you double click or use the context menu you can now open the editor and start writing – illustrated below.

Example of newly created script

Example of newly created script

‘m not going to go into more detail at present, the point is just to illustrate how easy it is to start scripting.  You can look at the learning centre with EA to follow through the steps and create/debug your own scripts.

In addition to having the development tools to hand within EA, scripts have access to the current EA object model (referred to as EA within a script) as well as use of other supplied libraries (System and with the correct EA edition MathLib). In addition, Sparx provides, via an MDG its EAScriptLib, a set of helper functions in the libraries; list of help scripts provided illustrated below.

EAScripLib listing of libraries provided

EAScripLib listing of libraries provided

Scripting is very powerful and in my opinion great when you:

  • Have a well defined limited functionality (scripts do not provide a rich UI)
  • Want to do something quickly
  • What to test ideas or have a one-off task
  • Will need to make code changes regularly

Scripting can be applied to all aspects of the EA model. There are different script types to support different areas of EA which provides the necessary hooks to access these different types at the appropriate places

My use of scripting within EA has been limited so I’m keen to explore further. For example, with:

  • Searches – having used simple selections or SQL – what else if anything does the script offer?
  • Workflow – I did have a look at this when developing AddIns for MS Project, but decided at the time it wasn’t able to help with that work so kept all my code in the AddIn
  • UI Interface modelling Sparx provides some helper scripts for Win32 – so what do they do?
  • External access – I’ve written VBA (more later) in MS Office tools to access EA. I assume it will work the other way – does it? What else can I do?
  • Script UI capabilities – what can be done?

External Client application

EA presents its object model as a COM service, hence any client application that can act as a COM client could access EA. Applications could be written in wide range of languages such as VB.NET, C, C++, C#, Java… A standalone client can be tailored to meet your requirements with a UI and functionality to reflect the task in hand. For example, an application could be used to support data entry from users who don’t want to or need to use EA directly, or to transfer information between an EA model and a 3rd party application.

Also we mustn’t forget the power of some of our standard tools such as MS Office. These can act as client applications by using their own scripting capabilities to interact with the EA model. For example, I’ve used VBA scripts in Excel extensively to transfer information between the two tools.  The biggest challenge for me was the practical task of configuration management -tracking scripts.  To help with this issue you could employ an Excel  (Word …) AddIns, which does require more coding, but does help.  My own experience has been with an AddIn for MS-Project which provides project managers with access to information within the EA model whilst operating in their familiar environment.

But what else would I want to be do with a client application?

External App 2

In my programming model, I included a second external application which accesses the EA database directly.  This is possible and dependent on the requirement may be useful, HOWEVER – yes a big HOWEVER – in bypassing the EA Object Model API you open yourselves up to a set of risks which could result in corruption your model.  You should note that:

  • You need to ensure that any changes are complete, you may need to make changes to multiple tables, so ensure that you modify the relevant table entries correctly.
  • Sparx may make changes to the database which will require updates to you code to work correctly.  I’m not sure how one would monitor when these changes are made since it is internal to EA’s workings.

So if you ever consider working with the database directly you need to be careful. My only use of accessing the database directly has been to perform bulk name changes – it worked and the model survived (of course I did have a back up before so I could do a model comparison after the changes – good practice!)

EA AddIn’s

So now onto the EA AddIn which is potentially the most powerful enhancement and is at the top of the list in terms of integration with EA.  The EA Framework provides the means to:

  • Add your own menu items (EA extensions menu – available in the main menu, diagram context menu and project browser)
  • Add you own UI –  with your own windows/ dialogs or using EA’s Custom Views as either an EA AddIn window or an EA Tab.
  • Respond to EA events.  These normally happen as a consequence of user initiated actions (note unlike scripting the user is not explicitly calling the code directly). These events cover a range of situations such as:
    • Add-In Events – which primarily relate to the connection  between EA and the AddIn as well as calls relating to menus that the AddIn may provide
    • Broadcast Events – which primarily relate to changes initiated through user action in the EA UI such as creating, modifying, deleting items or MDG loading or activation or validating a model
    • MDG Events – associated with the operation of MDG’s the AddIn may support

The fact that the AddIn exists within the current context means that, like EA scripts, it has direct access to the current EA model.

An EA AddIn is developed as a DLL (Class library) that EA, if registered within windows and enabled within EA, will load at start-up ready for use.  The EA AddIn Framework defines the interface which the AddIn code can implement and if specific methods are provided by your class library then EA will make calls at the appropriate time for your code to perform its task. Not only can your code work with the EA Object Model to access the current EA model it can initiate and work with other running process e.g. Excel.

So if you need any of this capability you have no other choice. Although, on the downside, writing a simple AddIn may be a few hours work in my experience developing production tested products is much longer – I know since writing AddIns’s is my bread and butter!

Where next?

As I stated at the start of this post my aim has been to provide an overview of the capabilities EA has for customising EA and set out a road map for my explorations.  Below is a mindmap summarising the areas covered with a guide to some of the areas I need to look at.

Customising EA - items to explore

Customising EA – items to explore

If you have any related questions or topics for customising EA do let me know and, although I cannot guarantee I’ll find the answers, at least I can take a look see whilst EXploringEA.

Adrian

Advertisements