Scripting the Impossible

In eaDocX V3.4 we have introduced a new feature which allows you to write your own mini document generators, using code contained in EA Scripts.

At first glance, this seems to go against the whole idea of eaDocX: everyone should be able to create great documents from their EA models without needing to be a programmer. So we thought we needed to explain why this feature has been added.

Like all builders of software products, we want to help as many of our customers as possible, and so we welcome all the feedback you give us via the eaDocX forums, and face-to-face at conferences and EA user groups.

A lot of these comments are asking for new function, and most of them start with 'I just want to be able to...'. Some of the most important eaDocX features have started out like this, so keep the ideas coming! But there are some requests which don't make it into the product feature backlog, and we feel bad about this. After all, even if it's just one customer who wants a new feature, for that one customer, theirs is the most important feature. 

We need a way to make the impossible possible.

We're always trying to balance the need to keep the product simple, with the desire to please as many people as possible with new function, so there is an obvious tension here. And we really don't like saying 'you can't do that with eaDocX...'.

So we looked around for a way to allow you extend eaDocX, without making the existing product more complicated, and using EA Scripts seemed the obvious answer.

How it Works

Regular eaDocX works by creating a Profile for all the Element Types and Element Stereotypes which you need to print. Each one can print differently: inline, as a table row, or not at all.

Scripted Formatting just adds a new option to this list. You can tell eaDocX to use a script to print either all instances of an element or of a  type+stereotype. You write the Script in EA, and (with a little effort) you can access many of the regular eaDocX features, such as Word styles. Your script will get sent a set of elements which eaDocX wants to print for you - all the elements of the same type or type+stereotype -  so your script can decide whether to print the elements one at a time (like inline) or as some kind of table.

An Example

This works best with a simple example.

A while ago, a customer asked us for an option to print a list of elements as a bulleted-list:

  • Requirement 1
  • Requirement 2
  • Requirement 3

As is often the case, when we asked for more details, the requirement expanded into "..and I'd like the option to print the 'notes' as well....

  • Requirement 1
    These are the notes for Requirement 1
  • Requirement 2
    etc...

..and before long, we're thinking about creating an option to make the 'name' in bold, or color, or printing the Alias as well..

This is perfect candidate for a simple EA script.

There are just 4 simple steps to creating eaDocX scripting in EA:

  1. Write the script in the EA Script editor  - prefereably using one of our examples as a template
  2. Test it
  3. Tell eaDocX what kinds of elements you'd like to print with your script
  4. Use it!

 

1 - Writing the Script

Writing scripting in EA is an established way to expand what EA can do, so it's natural that eaDocX uses the same mechanism.

Your script is a mini-document generator, which just needs to create a piece of HTML each time it needs to print some elements. It needs to create HTML, because that's what the rest of eaDocX creates, then inserts the HTML into Word.

Each time your document is generated, eaDocX will call your script, and send it some elements to print: just a list of the GUIDs of the elements. A typical script will therefore:

  1. Chop-up the list of GUIDs into individual ones
  2. For each GUID, fetch the EA.Element from the EA Repository, so that you're ready to print any aspect of the Element
  3. Start creating a single string of HTML, containing data from your EA Elements
  4. Send the string back to eaDocX, so it can be included in your document

We have created some sample scripts, to show you what's possible.

2 - Testing

This isn't as easy as it sounds. Sure, you can just skip this step, and run your new script from inside eaDocX, but that might just not work. What do you do then? You can't use the EA debugger, as the Script isn't called from EA - it's from eaDocX.

But you can run the script from within EA, by 'pretending' to pass-in a list of GUIDs. Some of the example scripts still have some GUIDs in them, commented-out (remember, they are GUIDs from our test model, so don't expect them to work in your repository). Just replace them with some GUIDs from your model. You can find the GUID of an EA element by selecting the Element Properties window from the EA main menu, and opening the Project set of values.)

If you paste-in some hard-coded GUIDs then you can test-out your script in EA, using all the great debug facilities. Then when you're OK with the output, comment-out the hard-coded GUIs and replace it with code to process GUIDs which eaDocX passes.

3 - Defining the Profile

If you're an eaDocX user, you're probably already familiar with the idea of a Profile. It's what eaDocX uses to decide how to format your document. For more details, see the help.

So you'll need to tell EA which elements should be using Scripts, and which script to use. Just Add the element type in the Profile tab, and choose the 'Scipt' option, instead of Inline or Table. Then choose the script from the list.

4 - You're now ready to use your script to create an even better document!