Category Archives: Automation

Information relating specifically to EA Automation – this could include scripts, VBA, API

One of our Add-Ins is missing

Prompted by 2 queries in a week about missing Add-in DLL’s I thought a quick post of the subject may be useful.

One of the problems that I have seen many times during the development and use of EA extensions is the missing Add-In DLL.

If you look at the Manage EA Add-Ins window in EA you may see an entry, as listed in the screenshot below, in the status column indicating that something is missing.

Manage EA Addins windows indicates a missing DLL

Manage EA Addins windows indicates a missing DLL

There is a error code 8000401f3 which indicates that the application failed to create an instance of a COM object using a Class which is not registered on the machine. Hence EA is unable to load the AddIn.

Having seen this issue numerous times I developed my EA Installation Inspector. This program emulates the process that EA may perform in loading your Add-in (Caveat – I don’t have insight to how EA code or how it does stuff in detail works so it’s my guess but seems to work so far).
This program provides more information about the status of the AddIn as illustrated in the screenshot below.

EA Installation Inspector illustrating a missing DLL

EA Installation Inspector illustrating a missing DLL

In this screenshot the purple line indicates that the DLL has not been registered, and hence is unknown to windows. Read the documentation supplied with the AddIn for more information.

Two steps to installing an Add-In

To be able to use your Add-In (DLL/Class) it needs to be known by:

  • EA as an Add-In
  • Windows as a class that can be loaded

I’ll look at these in turn

How does EA know about your Add-In

EA knows about AddIns through registry keys located within the HKCU\Software\Sparx Systems\EAAddins… as illustrated in the screenshot below. The value associated with any of these keys needs to be accurate as it references the class defined in you DLL with the format Assembly.ClassName

EA Add-In registry key

EA Add-In registry key

This list of keys matches the list of AddIns shown in the manage Add-Ins window.

How does Windows know about your Add-In DLL

To be able to load your class EA will make calls to Windows, hence windows needs to know about your class as well, and your DLL (Class) must be registered with windows in a specific manner.

The registration of your class may be performed in different ways. Typically it can be done manually using Regasm or performed as part of your installation by your installer. The registration process should create keys in relevant places in the registry so that when a request is made to load your class the appropriate DLL can be found. There are different versions of RegAsm depending on which .NET framework is being used.

The EA manual indicates that the version of RegAsm to use is that provided with .Net 3.5 with the example

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\RegAsm.exe “C:\Program Files\MyCompany\EAAddin\EAAddin.dll” /codebase

I suspect, but not tested, that you should use the Regasm supplied with the framework you are using.

The problem as I see it is that with the co-existence of 32-bit and 64-bit programs the location of this information is crucial. Now I’m not a windows expert but I know that by working through the trail from the EA AddIn key,a slow process, a class can be registered with keys in the wrong place. So this is where EA Installation Inspector helps. It follows the trail through the registry from the EA AddIn key to finding the DLL file that contains the class that will be loaded.

So how to resolve

Typically when EA can’t find a file then keys have not been registered correctly. EA Installation Inspector will hopefully indicate the error condition and provide an indication of what is wrong e.g. DLL file missing, keys in wrong location.

To check I will usually then manually register the DLL and rerun the installation inspector to check if the situation has improved. So far this has usually worked and leads me to check out what settings are missing or incorrectly set either in the IDE I am using or in the installer definition.

Here are some checks that you can make which may help resolve your missing DLL within an IDE.

  • Ensure that the DLL you are building is compatible with working with a 32-bit application. I always build my DLL’ 32-bit.
  • With IDE’s check setting
  • some of the defaults are geared towards 64-bit systems – e.g. default framework, default build configurations
  • check the setting Register for COM interop

For installers it is usually the case of accurately checking the definitions – usually against a know good installer.

Conclusion

Hopefully this information has been useful in finding your Add-In. However, if not I’m always interested to know what other issues exists (and hopefully solve them), let me know

Adrian

Advertisements

Customising EA – a 2nd look at scripting

Following on from my last post in which I provided an overview of the ways that you can customise EA, I have spent some time exploring more of the capabilities of EA scripting. Although I’ve used VBA extensively I’ve rarely used scripting either within EA or in a windows environment so I was keen to see how much you could really do.

I start by assuming that most of the stuff I do when accessing an EA project model with an EA AddIn can be done with scripting, however I needed to check this out as well as look at some other areas which are needed to support potential EA related applications.  Hence, look at scripting and how to interact with the user, system and other applications.

The mindmap below illustrates my target list and I warn you I don’t get to the end in this post. But let’s start and look at what I found during my exploring so far:

Explore the capabilities of scripting for each of these areas?

Explore the capabilities of scripting for each of these areas?

Well, let’s start and look at what I’ve found so far  – basically items 1 .. 7  – where my aim for each is as follows:

  • User Interface – what can I do in providing the user with information and getting results back
  • Library access – what existing code exists that I can use and what capabilities does it offer

External access – can EA scripts interact with stuff outside of EA for example:

  • File access – can I read / write files?
  • Network access – what communication capabilities exist?
  • System access – what services exist?
  • Application interoperability- can I interact with other applications e.g. Office

I’ll now outline what I found and in a future posts look at the missing items as well as resolve some of my outstanding issues.

In each of the areas I’ve been testing using VBScript, and assume but not tested, that the functionality I outline is available with the other scripting engines; that may be a very bold statement!  Also you need to remember in writing the code it’s important to note that VBScript is not VB,  as I found out and I often needed to check the syntax.

1. EA model access

This is the area I expected all to work but wanted to check access to packages, elements, diagrams etc and that information can be exchanged between the script and EA projec. To do these tests I used the code samples provided in the EA manual and, with making relevant syntax changes, all seemed to work fine.  No surprises and none expected so that was a good start.

Key to the operation is access to the currently open repository through a predefined object “Repository”.  Methods are selectable using Intelli-sense with access to the help file for access to the EA Object Model reference material. All fine so far.

2. User Interface

For me the user interface is a key component,  so I was keen to understand what capabilities are available.  I half expected it to be a basic command line text interface but as you will see there is potential for much more.

To start with it is worth a moment looking at how a user will access scripts.  There are 2 basic mechanisms that I would expect to be used.

The scripting window access from Tools | Scripting which presents a list of the available scripts.  And either using the run button in the tool bar or context menu the user can run the script.

Running a script from the content menu

Running a script from the scripting list window

or from the context menu – in which case those scripts created for the relevant script group will be available i.e. if you create a script with a Diagram group then that script will only be available when working within a diagram.

Running a diagram script within the context of a diagram

Running a diagram script within the context of a diagram

So having got the script started in most cases there is a need to interact with the user whether asking questions, capturing data or presenting results.

To support this requirement EA provides a Session object which supports input, output and prompt methods which provide a basic capability e.g.

Session.Output “Some information for the user”

The prompt method can capture a result from user input.

Also provided with EA is a library of helper functions (EAScriptLib).  This is supplied as an MDG so if not present in your list of scripts then check your Settings | MDG Technologies to ensure that it has been enabled.

Enable the EAScriptLib

Enable the EAScriptLib

You then have a set of scripts functions available in several scripts in the EAScriptLib group.  You will need to look at the script source to see the available functions and usage information.

EA Script Library

EA Script Library

If you want to use any of the functions within these library files you will need to include the relevant library in your script e.g. !INC EAScriptLib.VBScript-Dialog before you can use it.

For example, a simple input box could be accessed as illustrated below.

EAScriptLib Input box

EAScriptLib Input box

When looking into other options I soon discovered there were more options.

For example, VBScript provides some standard functions such as

MsgBox(prompt[, buttons][, title][, helpfile, context])

I also found other functionality via the windows shell application object.  For example, using the BrowserForFolder to select a filename, and get its path.

Function BrowseForFile()
Dim shell : Set shell = CreateObject("Shell.Application")
Dim file : Set file = shell.BrowseForFolder(0, "Choose a file:", &H4000)
if (not file is nothing) then
BrowseForFile = file.self.Path
else
BrowseForFile = "No file selected"
end if
End Function

It soon became clear that it was possible to create quite sophisticated dialogs, although I found nothing as powerful as a custom form; perhaps I have missed something.

3. Libraries

As with most programming languages there are libraries of functions available for scripting, as you will have read I have already discovered a few. But when I started with VBScript I was unaware of the range of functions that were available and just a quick search on the Internet found many more.  For example, there are scripts covering most things that I needed including:

  • Hardware information
  • Messaging
  • Networking
  • Operating systems information
  • Security

Already we have seen that EA has its own Sparx provided EAScriptLib which provides some helper functions – see above for details.  Then there is the standard VBScript library ( see VBScript language reference at MSDN)  plus access there is access to a range of other application objects such as:

And with that I think I can do most of the tasks I need so onto a few tests.  A quick search provides examples for most of these.

4. File access

With the ability to interact with users and libraries available, accessing files should be straightforward.  And this was indeed the case. The function below worked fine –

Sub MakeHelloWorldFile (FileName)
'Create a new file in C: drive or overwrite existing file
Set FSO = CreateObject("Scripting.FileSystemObject")
If FSO.FileExists(FileName) Then
Answer = MsgBox("File " & FileName & " exists ... OK to overwrite?", vbOKCancel)
'If button selected is not OK, then quit now
If Answer <> vbOK Then Exit Sub
Else
'Confirm OK to create
Answer = MsgBox("File " & FileName & " ... OK to create?", vbOKCancel)
If Answer <> vbOK Then Exit Sub
End If
'Create new file (or replace an existing file)
Set FileObject = FSO.CreateTextFile (FileName)
' and put some content into the file
FileObject.WriteLine "Time ... " & Now()
FileObject.WriteLine "Hello, World"
FileObject.Close()
MsgBox "File " & FileName & " ... updated."
End Sub

With that I was happy that basic file functionality is available using the File System Object so left it there.

5. Network access

Next on the list was communication.  Perhaps a simple test to retrieve information from a web server, so try accessing a web page. Once again network access was straightforward using the HTTP request. For example, the few lines below were able to read a web page and output as text string.

Set o = CreateObject("MSXML2.XMLHTTP")
o.open "GET", "http://eaforms.exploringea.co.uk", False
o.send
' o.responseText now holds the response as a string.
Session.Output(o.responseText)

Looking at script examples I found there is clearly I much more functionality readily available whether it be parsing the content, sending emails,..

6. System access

Next I looked at system access, and this was probably the biggest surprise to me. How much could I do from scripts in terms of accessing and manipulating system information? Well it turns out that you can do a lot, although I suspect that windows security will prevent normal users doing anything catastrophic (I hope so!).

My findings were that EA can happily run the scripts that access all types of system tasks using WScript or get information using the winmgmts objects.

For example, using the File system object you can create a batch file and then using the shell object run the batch file. e.g.

Set objShell = CreateObject("Wscript.Shell")
objShell.run("%comspec% /c C:\Users\adrian\Documents\mybatchfile.cmd")

This was clearly an area with plenty of functionality that would go far beyond the normal day to day needs of the EA user.  For those interested there is plenty to explore – I stopped myself as I suspect I could have spend hours or even days as I have only scratched the surface.

7. Application interoperability

So to the area of greatest interest to me – applications working together.

Having used VBA more than a decade ago to transfer information from Excel to EA my first task was to discover what could be done the other way round, then look further at the general capabilities for interacting with external applications.

With the knowledge that it was possible to create an application object with VBScript, and my experience of writing several EA AddIns for MS Office products applications, I was confident that I should be able to connect.  And this was the case .

For an external application that is available as a COM server you can create a reference to the server, and use that to interact with the relevant files. In the case of Excel this is done as follows:

Set objExcel = CreateObject(“Excel.Application”)

And the following lines illustrate how to create a workbook, adding some dummy data into the worksheet and setting some cell formatting.

dim strFileName
dim objExcel
dim objWorkbook
dim objRange
strFileName = "C:\Users\adrian\Documents\c1.xls"
Set objExcel = CreateObject("Excel.Application")
objExcel.Visible = True
Set objWorkbook = objExcel.Workbooks.Add()
' now makes visible and then puts some data into the sheet
objExcel.Visible = True
objExcel.Workbooks.Add
objExcel.Cells(1, 1).Value = "Name"
objExcel.Cells(1, 1).Font.Bold = TRUE
objExcel.Cells(1, 1).Interior.ColorIndex = 30
objExcel.Cells(1, 1).Font.ColorIndex = 2
objExcel.Cells(2, 1).Value = "Test value 1"
objExcel.Cells(3, 1).Value = "Test value 2"
objExcel.Cells(4, 1).Value = "Test value 3"
objExcel.Cells(5, 1).Value = "Test value 4"
Set objRange = objExcel.Range("A1","A5")
objRange.Font.Size = 14
Set objRange = objExcel.Range("A2","A5")
objRange.Interior.ColorIndex = 36
Set objRange = objExcel.ActiveCell.EntireColumn
objRange.AutoFit()
objWorkbook.Saveas(strFileName)
objExcel.Quit

For other MS Office applications (Word, Project, Powerpoint, Outlook) the approach should be very similar, although I have not tested all.  But what other applications?  Using Create object I assume that a script could connect to any application that provide a COM interface.  So I started Visual Studio and looked at the COM references are available.  There are 100’s on my system, however I suspect that not all are available and/or useful.  I did test with a few application objects and soon realised that I have a lot more exploring to do in this area.  Although, I suspect, purely for general interest as I’m not sure many of these applications will be useful with EA. I’ll find out.

Roundup

Although there are still some areas, as listed on my mindmap, left to explore and I will get onto these in due course. However, as usual I’ve discovered some interesting stuff along the way which I want to explore further, and find some answers before moving onto the next  topic.  So I’ll leave it here for today, with some questions in my mind regarding application interoperability, and the promise that I’ll check out some more of the EA Scripting capabilities.

If you have experiences of scripting or questions feel free to add a comment.

Have fun EXploringEA

Adrian

 

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

Accessing your favourite tool from within EA

I’m not sure if this is just me, but there are a few things that frustrate me when working within a tool such as EA.

  1. Firstly, there is often more information I want to view at the same time than is possible because I just don’t have enough screens! There is a potential solution to this.
  2. Secondly, is when I want to do a related task using a different tool, so need to switch context. This is frustrating especially when I have my head down producing stuff and I just want to press a button.  This may be unique to me but the need to switch to another tool, which is more about the need to go back to windows and select the program, open it and establish context etc

So is there a way to improve the situation by having the tools I want operate within the context of EA?  Let’s do a little exploration to check out what EA provides and see if it can help me.

1. EA Tool menu

First up, in looking at the tools menu there are shortcuts which start an external application, albeit in it’s own window but at least it is just a single click.

I think the standard installation comes pre-configured with a few tools:

  • MS Paint
  • ODBC sources
  • System information

And you can add any application to the EA tools menu.

EA tool menu - add your own tool

EA tool menu – add your own tool

To add an application you use the “Tools | Customize | Tools tab” to configure the application. You need to provide:

  • A command – the application you want to run
  • Arguments – and EA supplies a range of parameters that can be set and passed to the external application
  • Initial directory – this can be set but doesn’t appear to have any dynamic options.

As an example I use IrfanView for doing a lot of image manipulations. So I can add a new tool item to support my access to this tool within my working context.

Configure EA tool menu item to open IrfanView with clipboard

Configure EA tool menu item to open IrfanView with clipboard

You see I have set the application, however there are no parameters available from EA that make sense within the context of the IrfanView arguments. However, the reason I want to open IrfanView from within EA is usually to manipulate an image, hence if I assume that I have saved my desired image to the clipboard with EA (ctrl+B) and then add an IfranView argument “/clippaste” it will open with the current clipboard contents all ready for editing.

Although this is no major advance it does improve productivity when producing help documentation!

2. Using the EA parameters

So what applications could benefit from the arguments that are available from EA.  I needed to think about this as it wasn’t clear what applications other than something specifically written to work with EA would attribute meaning to the arguments – initial and final thought was that this is only useful for applications you write.  I am sure there are some really good examples, however none come to mind so I’ll just illustrate a simple application to demonstrate the use.

Below is the code for a simple console application which takes EA arguments, opens an instance of EA with the project file name provided and prints the name of the current package.

==== Code starts =====

class Program
{
public static void Main(string[] args)
{
// the arguments from EA will be the project name – which may have spaces so need to be wrapped in “‘s
//
// command line input
// arg 1 – EA project full path filename ($f)
// arg 2 – name of calling application ($F)
// arg 3 – current package ID ($p)
// arg 4 – current package GUID ($P)
// arg 5 – ID of associated diagram  ($d)
// arg 6 – GUID for associated diagram ($D)
// arg 7 – CSV of ID’s for all selected elements in current diagram ($e)
// arg 8 – CSV of GUID’s for all selected elements in current diagram ($E)

Console.WriteLine(“Number of command line parameters = {0}”, args.Length);
foreach( string a in args)
{
Console.WriteLine(a);
}
//            Console.Write(“Press any key to continue . . . “);
//            Console.ReadKey(true);

// open EA

Console.WriteLine(“\r\nProject file = ” + args[0]);
Console.WriteLine(“Openning EA, please be patient!”);
EA.Repository EAR = new EA.RepositoryClass();
EAR.OpenFile(args[0]); // open EA

// now just use one of the arguments to do some processing
int packID = Convert.ToInt32(args[2]);
if (packID != 0)
{
Console.WriteLine(“Package ID = {0}”, packID);
EA.Package p = EAR.GetPackageByID(packID);
Console.WriteLine(“Name of current package = {0}”, p.Name);
}
Console.Write(“Press any key to continue and close EA “);
Console.ReadKey(true);
EAR.CloseFile();
}

===== code ends =====

So with the application written I use the EA customise to add my application to the tools menu.

EA Console Tool - example of an application that can handle EA arguments

EA Console Tool – example of an application that can handle EA arguments

And when run from my tools menu the output is as shown below.

Example output from the EA Console Tool test application

Example output from the EA Console Tool test application

As such this is an example that doesn’t do a lot other than illustrated that the mechanism works.  It is possible to call an external application and pass it information within the current user context – I repeat the current user context – as this is where the value will come.

A brief recap

In looking at accessing external tools I have reviewed how to existing tools as well as a custom tool.

In the case of the existing 3rd party tools, unless they are written specifically for EA, it is unlikely they can do much, although the ability to open my graphics application with the clipboard presented is really useful, and I am sure with some creativity there are some excellent use cases.

In the case that we have a custom application then we have a greater degree of freedom limited only by the application.  It provides the user with the ability to initiate some action within their current context.  I know I need to think about potentially other applications for this use case.

 

But can we bring our application closer?

In both these instances the access to out application is a manual process.  The user initiates the application.

In our custom application example we saw how the information provided to open a new instance of EA can be used to perform some operations.  Of course, our application could be used stand alone, i.e. without being called by EA, but in that instance we wouldn’t have the contextual information which was my starting point.

One downside is that our application runs as a separate entity and to access EA requires us to create a new instance, with the inherent start up time lag.  So is there a better way of adding functionality to EA as well as integrating with 3rd party tools.  The simple answer is yes – EA provides an AddIn framework which can address the shortfalls of working at “arms length” and I’ll come back to that in a future post.

In the meantime, I hope that this post has been interesting and at least made you think about how you use other tools with EA.  If you have any specific use cases that haven’t been covered please feel free to share your requests, ideas..

Thanks

Adrian

What EA Add-Ins do you use or need?

As you have probably gathered, if you’ve read any of my blog, I spend a lot of my “day job” writing EA Add-Ins.  It’s one of the great advantages of EA, and along with the general mechanisms to access the core EA object model, and some of the key reasons I selected EA so long ago. It wasn’t that I could enjoy spending my time writing Add-Ins (that came much later) but more that there was a mechanism to interact with or expand its functionality in the way that I may need.  

In fact, by removing a dependency between the features that Sparx may add to EA, and the specific needs of the users, means that functionality can be added as required, and in a timely manner. Furthermore, this functionality can be added by those who may have more insight into the need and/or other tools with which any integration may be required.

Writing an Add-In may not be for all – and I would argue that it may not be the best solution – (I’ll write my thoughts on this one day) – however, it can be entertaining.

Personally I make use of the following Add-Ins on a regular basis:

  • eaDocX – I wrote the Excel part and for me it is one of the most useful tools for getting stuff into and out of EA, especially when developing new models and using information from many different sources.
  • HoTools, written by Helmut Ortmann, which helps make my lines pretty (available from download off the Sparx community site) – so much easier than using the diagram tools!
  • Plus the tools I’m developing / testing such as eaForms plus some other project management tools.

If you take a look at the list of Add-Ins list on the Sparx site (Sparx 3rd Party List),  – many of them are very specific to a domain and very much in line with my expectation that the experts of the associated product have authored them.  If you then do a Google search you’ll find some additional Add-Ins, once again many provide integration with another tool, whilst others provide some enhanced functionality.

What interests me is what Add-Ins really people use? I know users of my own Add-Ins, but in terms of the broader EA community is there widespread use of Add-Ins?  What Add-ins are used?

I know the ones I use regularly are those that provide general functionality and this seems to intuitive.  Although I found it interesting that I had very little interest in an EA Add-In I wrote for MS-Project (I also write an Add-In for MS-Project which would work in reverse); I just put that down to the fact that there were very few project managers using EA – which wouldn’t surprise me. So it may not general purpose tools and need for an Add-In may not be the general rule.

If ignoring the very specific tools integration products, are there any other “general” tools for which an Add-In is required and doesn’t exist?  What do users want and why? It’s not obvious to me but would welcome any thoughts.

So with that final question I’ll go and look at one of my current projects – another Add-In!

Adrian

BTW: You may have noticed I’ve added information on some of my current Add-In developments in the sidebar – just a flavour of what we do at EXploringEA.

 

 

 

eaForms – an element properties editor which can extend and enhance the EA experience

For the last few months I’ve been developing an EA Add-In which has taken longer than originally planned, hence my lack of time for other experiments.  As the project unfolded, we discovered more, expanded the idea, added more features (scope creep!), and then a few redesigns of the UI to provide users options. And even now we still have more ideas to explore.

All in all its taken a few months longer than planned.  I suppose I should believe my rule of thumb which is, when asked by a project manager how long will something take to do – take your first estimate and multiply the time by PI (3.14159265359….   – perhaps not to that level of precision!), and its the number you don’t want to believe, as it could well put you off starting the project at all.

So 2 months becomes 6 and I am now nearing the end of completing the initial phase of this new Add-In – eaForms.  I  had expected to be where I am now before my summer break in July, but instead spent much of my break coding albeit in the sun and must admit it was fun – especially learning more about what you can / can’t do with EA all the time.   I have lots of material from my discoveries for some posts on writing Add-Ins – hopefully I’ve get some time to write up soon.

So what is eaForms – simply it’s an Add-in that allows users to design and run alternative element properties editors.

The idea came from my work in trying to capture knowledge from people who had no knowledge (or interest) in modelling and when pushed to found EA too techie to use.  This led to confusion, frustration and often a bit of a mess for your’s truly to sort out. So why can’t they have something that is a bit more accessible.  They may still have to use EA and so accept that they will be using a modelling tool.  Also there is no getting away from them needing some training to cover the basics plus monitoring afterwards, but at least I could make life a little easier by removing some of the complexity for data entry/editing.  In addition, in doing this I could also help drive consistency by, for example, providing them with a defined set of values instead of a free form text box etc…  less mess for me:-)

eaForms operates in 2 modes:

In Designer mode – the EA user can configure a form, using the eaForms toolbox,  to produce a form that will be displayed for a specific Element type/stereotype combination (support is included for both core element as well as MDGs that are enabled at design time). The content, layout and appearance of this is up to the designer.  The form designer is free to produce forms of different shapes, sizes, colours and perhaps more importantly content using “controls” that go beyond that provided by the standard EA dialogs.  For example:-

  • Combobox (with options for user defined values, to restrict users selections)
  • Checkbox – to provide that quick “yes/no”, “true/false”, as well as other booleans
  • Related elements – with the ability to link to one or more other elements without dropping the current editing context
  • Listviews that display collections with some options to edit items in the list, once again without dropping the current editing context.

Plus built into the design is the ability to add further “gadgets” that as the need is identified.

As an example – here is the basic design of an eaForms in EA – drawn using EA’s drawing tools on an eaForms diagram

BasicDesign

In User mode – the EA user, assuming eaForms is enabled, need do nothing.  When they edit an element for which there is a matching form available eaForms will present this instead of EA presenting its standard dialog – below is a screenshot for the form design above:

AsItLooks

All in all no real magic but pretty useful.

Of course, for the experienced EA user the benefits are different.  They can produce forms that help them by bringing information together in a single place in the way that they want (I do this for classes, where I have a single form with the class information, its attributes and operations). And bearing in mind it only takes a few minutes to produce a form it can be time well spent, of course, for the artistic it’s easy to spend more time enhancing the look of the form!

Although we think this is a great tool it is important to remember eaForms is just another tool in the EA toolbox. It is an Add-In that can extend and enhance the users’ experience. Using EA still requires guidance from those responsible for the models. Our aim with eaForms is to help in making EA more accessible, reducing some barriers and helping ensure data consistency. Not for everybody but useful to the many.

We have more ideas on where we could go with eaForms and could just continue developing but probably better to let you play (and hopefully provide feedback).

We plan to start trialing eaForms soon – so watch this space.  In the meantime we have started with some short videos that demonstrate the product and its use which you can find on YouTube Channel.

Be back soon.

Adrian

Notes on revisiting MDGs

Recently there has been a lot on the forums about MDG.  This seems to coincide with my need to develop an MDG to support my current project. To date my experiences of MDGs have been somewhat limited, however when used have been a very valuable resource to enhance EA modelling.  For my current project my use is somewhat different in that I am using the MDG as a means for users to provide inputs to on which my AddIn will respond.

Previous MDG developments have been somewhat difficult, not least as its a task that is done infrequently, there is a lot to remember and it’s pretty easy to do something silly.  So I was pleased to use the new Profile Helper to get the basic MDG developed pretty quickly.  However  the Profile Helper doesn’t do everything and has some limitations which I thought worth sharing.  I will also take this opportunity to share some other notes that I took during this phase of the development.

Please note: This is not meant to be an exhaustive list as I am sure there are further limitations that I have yet to discover. Also any suggestions at making edits to existing or your own MDG’s should be taken with care and knowledge; it’s pretty easy to get something wrong.  Backup your work, test with test data that can be destroyed and convince yourself that you have fully tested before deploying.

Using the EA Profile Helpers

For an overview here are the basic steps for building a MDG with the Profile Helpers.

  • Start with “Add a new model using wizard” – select the “MDG Technology Builder” and then select the “Basic Template” which includes both a pattern and examples. If you are familiar then the “Simple Template” is fine.
  • Then in turn build and save the following profiles:
  • Stereotype profile
  • Diagram profile
  • Toolbox profile
  • Use the “Tools | Generate MDG Technology File” to create the MDG (XML file) that can be imported/loaded as required.
  • Import the “Tools | MDG Technology Import” to import the file – this places the file in your “C:\Users\YOURNAME\AppData\Roaming\Sparx Systems\EA\MDGTechnologies” folder – EA looks into this folder every time it startsup and will load file present.

That is the basic process.  There is a lot of information in the EA User Guide – in fact too much to keep in your mind at anyone time so unless you are doing MDG’s frequently a lot will be forgotten.

There are several online tutorial examples which provide some useful background:

And of course searching through the forum (http://www.sparxsystems.com/cgi-bin/yabb/YaBB.cgi?board=Automation) can be a useful source of information  – and a great place to post questions.

Now for some of the items that weren’t covered.

Tag Groupings

In my MDG I have several elements extending a single metaclass with their own set of tagged values and I wanted to present the tags in their own groupings.  It wasn’t clear to me at first, but obvious when pointed out, that to support the different groupings you need to duplicate the metaclass that is being extended – so an element with the same name, one for each different set of tags/tagGroupins.   Once aware it was easy to resolve and the tagged values appeared as I wanted.

Set a shape script. 

I found that the basic elements without a shape script was a bit messy.  It is is possible to do some pretty amazing things by defining your own shape scripts for a stereotype.  I didn’t do much but would suggest making the element look clean, for example, the following script provides a rectangle with just the name of the element.

shape main{
noshadow = “true”;
h_align = “center”;
editablefield = “name”;
rectangle(0,0,100,100);
println(“#name#”);
setfillcolor(“white”);
}

Modifying the XML

I mentioned that there were several posts on the Sparx forum recently, many of which were from users keen to get access to the source of an MDG.  I understand why MDG owners don’t want to release their source, not least if they want to maintain control so that they are responsible for the updates etc.  So if a user wishes to make changes they are not responsible for supporting them!

In trying to resolve some of my issues I spent some time looking into the XML and I found this relatively straightforward – reason for XML is the structure.  The MDG file provides building blocks and most of them can be modified or moved around;  of course some elements such as the scripts cannot be decompile but I don’t see any reason they can be moved around if needed.  However, my main reason was to manipulate the tags, in part to understand why things were working (such as the tagGroupings above).  In doing this I also discovered some really useful information and would recommend checking out the “Special Attributes” section in the user guide. Here are some notes on some of the tags I have looked at are:

_subtypeProperty

This allows for the use of submenus each time an element is added from the toolbox. So for an existing MDG if you want to change the menu selected or remove completely this can be achieved by modifying the relevant XML.  For example, in the BPMN MDG if you want to change the menu for an activity from the standard taskType then the line

<Property name=”_subtypeProperty” value=”BPMN2.0::Activity::taskType”/>
could be modified to
<Property name=”_subtypeProperty” value=”BPMN2.0::Activity::whatevertagyouwant/>

If you want to set the default value that is used by the submenu then as an example when the _subtypeProperty default for “taskType” is set as “Abstract” as below:
“<Tag name=”taskType” type=”enumeration” description=”” unit=”” values=”BusinessRule,Manual,Receive,Service,Send,Script,User,Abstract” default=”Abstract”/>”

you can change the default value to one of the other VALID items

Modifying and updating the MDG tagged values within your models

Of course, if you change the MDG for example add more tagged values, and you have existing models can you apply the MDG retrospectively.  Well yes but..

If you modify an MDG profile you can apply a “global sync” by selecting the relevant element in the MDG toolbox, right click to get the context menu and select Synchronize Stereotype. This will update all the relevant stereotyped elements however it doesn’t put any newly added tagged values into their relevant tagGroup.

If you want to have the tagged values grouped correctly I have observed that if you “apply type” by dragging the relevant toolbox item onto an existing element it will perform the update and ensure that the tagGroupings are set correctly.  For more information see “Synchronize Tagged Values and Constraints” in the user guide.

MDG related events

Now the main reason for my MDG was to support users input, with changes to MDG tagged values initiating actions within my AddIn.

My plan was to use a range of predefined tagged values (Settings | UML Types | Tagged Value Types) e.g. Boolean, Color, Enum as well as Addin Broadcast type.

For the “AddIn Broadcast” types my AddIn would respond to the EA_OnElementTagEdit events’ whilst for other changes my EA_OnNotifyContextItemModified method would be called. One of the unfortunate differences is that for EA_OnNotifyContextItemModified there is no indication of the value that has been modified, hence it is necessary to check what had changed and take the appropriate action. So I have my plan and started coding, however, all was not as I expected.  Here are a few of my observations which may help you avoid some issues.

When using Predefined taggedvalues you need to be very careful to check the type of the values that are provided. I’m not sure whether this is an EA issue or a language issues, but, for example, when using “Type=color” the user guide states tat it returns an integer.  However when experiencing problems I checked the type that was return and it was identified as Type “String”. Well I can cope with that until I discover that sometimes it returns an integer string whilst at other times it returns a hex string. Not sure how to resolve that and with that inconsistency I decided the solution was to provide my own color picker and use the “Type=AddinBroadcast;”. In fact for anything other than the basic value types I found this a more reliable means to get correct values.  Furthermore, by handling the tags myself I had the advantage that I what item I had changed.

Tagged values color editor
Tagged Values with Colour Editor – note “…” alongside the tagged value being edited

For the “normal tags” I did use the EA supplied types and these were handled by the EA_OnNotifyContextItemModified.

In both cases having captured the tagged value changes I may respond with some updated values either directly or indirectly. What is disconcerting is when I know the changes have been made in the data structures and the tagged value window does not update. So remember to execute the “Repository.AdviseElementChange” method to ensure the update to the EA UI.

Adding tags.

Finally, when adding a new MDG element programmatically don’t forget that you do NOT add the tagged values but use the “element.SynchTaggedValues” method  – see user guide for more information.

Final comments

By using the Profile Helpers I felt more comfortable in coming back to working with MDG’s.  Although the helpers help by providing a quick start, there is still a lot of information you may need to consider when developing an MDG, so don’t expect it to be a quick task.

I have found it useful to become familiar with the XML that is produced, and a place to make quick edits before going back into the model to “do it properly”.

So my MDG seems to be working fine.  It took longer than expected to produce due to some if the issues I’ve detailed above, however the result is that I now have a user interface with which most users will be familiar, and therefore easier to use – my primary aim.