Category Archives: Object Model

Information about the EA object model and related items

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

 

Advertisements

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