Writing in the Eclipse database: Change the field’s Id based on Gantry angle.

João Castelo
7 min readJul 28, 2020

Hey guys!

This is the first article of the blog about an interesting feature that most of us always wanted, using the writing capacities of ESAPI.

Everything I’m sharing here is for educational purposes, I advise you to learn first and then implement any script on the clinical environment. This is not a recommendation or a clinical validated script.

Photo by Roman Synkevych on Unsplash

It is important to acknowledge that, in the clinical environment, writing via ESAPI is allowed in versions of Eclipse above 15.1.1.

Script Approvals and TBOX:

Varian Testing Station, also known as TBOX, has a mimic of the clinical environment, in which you can test your scripts freely.

Version 15.6 guide to each permission

In my initial guide for ESAPI, I showed how to build single file, binary plugins and executables for read-only scripts. Writable plugins keep the same properties, but if they are going to be used in the clinic, they need to be approved in the Eclipse UI, and you can’t approve a single file plugin.

Declaring we are going to write in the database:

In executables we declare in the start of the code the [STAThread] flag. ESAPI needs in any file of the code you are building (executable or binary) to exist the following flag:

[assembly: ESAPIScript(IsWriteable = true)]

And run the Patient.BeginModification() method before modifying any property of a patient’s object.


Remember to use both.

I’ve noticed that in TBOX the later is not needed. But it surely is in clinical environment.


For binary plugins this should be the code to begin with:

For executables:

Remember you can save via script in Executables, in Plugins you have to save in the UI after the script finished its task.

If you really want to automate a task and have no human contact, but run each patient at a time, you can always emulate a plugin via executables (see How to emulate a plugin).


We will cover the following steps of a clinical acceptance of a writable binary plugin:

  1. Script Development
  2. Testing the script in TBOX using Carlos Anderson’s Eclipse Plugin Runner
  3. Evaluate the script function in Clinical Environment
  4. Approve it

Dev Work:

What’s the problem?

Suppose that when you start planning a 3DCRT case, you add multiple fields and do not assign ID or name to them. Then you start doing Field in Fields and Complementary Fields, and in the end you get this lovely picture:

What’s the solution?

We will automatically assign Id’s to the static fields based on their gantry angle. And also add a FF or Comp flag, if the field is one of them.

Wanted result:


We’ll create a binary plugin, so create a new .NET Framework 4.5 Class Library solution called FieldIdFromGantry. Change the assembly name to FieldIdFromGantry.esapi and the CPU config to x64.

In this project, we’ll create a single class called BeamIdChanger. Create a new .cs class File (Ctrl + Shift + A), called BeamIdChanger.cs :

Also rename Class1.cs to Script.cs:

You should have this two files now:

Reference the VMS.TPS libraries:

Paste the following code in BeamIdChanger.cs:

And in Script.cs, paste:

The following flowchart describes the decision making process that happens in Beam Id Changer:

Testing on TBOX:

We could just build the code in visual studio, and run it on any valid calculated dose plan in TBOX. However, you may not be interested in copying and pasting, but rather creating and testing your writable scripts and test during development. In my ESAPI initial guide, I briefly discuss about the need to restart eclipse or change the assembly name each time we want to test a binary plugin. We can solve this problem using executables, or when testing in TBOX we can simply use Carlos Anderson’s plugin Runner solution.

Carlos Anderson’s ESAPI Plugin Runner and Git:

In my opinion, the best suited option to test your scripts is to create a solution that contains the NuGet packages ESAPI Plugin Runner and ESAPI Essentials, and every new project you get into, you branch the Plugin Tester solution via Git and add the project you’re working as an external reference.

The plugin runner allows on the run Debug, this is very very helpful.

By doing that way, you do not need to reference this testing libraries in your clinical script.

Let’s test our project with ESAPI plugin Runner.

Close the FieldIdFromGantry solution:

Create a new .NET Framework 4.5 WPF solution, called PluginTester.

Change to x64 architecture.

Remove the MainWindow.xaml file from the project!

Install the highlighted libraries from NuGet Manager:

After installing the packages, reference the VMS.TPS libraries.

Your solution explorer should look like this:

Create a file called ScriptTesting.cs.

You can use the shortcut (Ctrl + Shift + A).

Insert the following code in this file:

Now this is an important part!

Since we removed MainWindow.xaml from the project, we need to rewrite App.xaml by changing the line:




In the App.xaml.cs, we will create the App_OnStartup Method:

This should be it’s content:

This is the template for Eclipse Plugin Runner.

Now create the git repo, using the visual git tool in Visual Studio:

Branching and testing:

Create a new branch from the master via git.

Call it based on the FieldIdFromGantry solution:

In the new branch reference FieldIdFromGantry project, right clicking in the solution name:

Find the project folder, and click open on the FieldIdFromGantry.csproj:

Check the solution explorer:

Inside the ScriptTesting.cs file, add the following lines inside the Run Method:

BeamIdChanger changer = new BeamIdChanger(scriptContext.PlanSetup);changer.ChangeBeamsIdsFromGantryAngles();MessageBox.Show(changer.Log);

Use the Ctrl + . shortcut to solve the reference to FieldIdFromGantry.

Add and Commit the changes…

We’re finally testing it:

Press Ctrl + F5 or press Run, the Eclipse Runner connects to the Eclipse DB in TBOX:

Find a plan you wish to test:

There’s the result we wanted!

Using Plugin Runner you can also Debug your code via Visual Studio (installed on TBOX):

Now that we’ve already tested in the Plugin Runner, we should test it in the Eclipse UI.

It’s all good!

Script Approval:

After your tests, you should be confident to start to use it in the clinic.

Now you as physicist should check the authorization for script usage of the users in varian service.


If everything is okay for the users privileges, you should go to .

The black approval window will pop, then you should register the new script.

Thanks for reading!

Thanks to Jonas for reviewing this post.