top of page

Upgrade Your Scripts from ESAPI 13.6 to 15.5

As clinics upgrade to ARIA 15.5, scripts written using ESAPI 13.6 must be upgraded to use ESAPI 15.5. ESAPI 15.5 is mostly backwards-compatible with ESAPI 13.6, but there are some important differences.

Note: There are many new features in ESAPI 15.5 (for example, writable scripting), but in this post I discuss upgrading your current ESAPI 13.6 script to work under ESAPI 15.5.

The assemblies you need to reference are the same (VMS.TPS.Common.Model.API and VMS.TPS.Common.Model.Types). However, their directory location has changed. In my ESAPI 15.5 installation, the directory containing the assemblies is

C:\Program Files (x86)\Varian\RTM\15.5\esapi\API

Code-wise, I've listed below the changes you need to make to your current script in order to upgrade it from ESAPI 13.6 to ESAPI 15.5:

  • You no longer need to create the Application object with a user ID and password because ESAPI 15.5 uses your Windows credentials to log in to Eclipse:

// ESAPI 13.6
var app = Application.CreateApplication(userId, password);

// ESAPI 15.5
var app = Application.CreateApplication();
  • The HistoryDateTime and HistoryUserName properties of the User class were removed. If you used this information, you will need to obtain them from the ARIA database directly.

  • Proton plans are now represented by the class IonPlanSetup. They used to be represented by ExternalPlanSetup, but this class is now exclusively used for photon plans. This means that the property ExternalPlanSetups in the Course class and the properties ExternalPlansInScope and ExternalPlanSetup in the ScriptContext class return photon plans only.

  • The property TotalPrescribedDose in PlanSetup has been removed. It has been replaced by TotalDose:

// ESAPI 13.6

// ESAPI 15.5
  • The property UniqueFractionation in PlanSetup has been removed. This property had the type Fractionation, a class that has been removed. Its properties are now in PlanSetup:

// ESAPI 13.6

// ESAPI 15.5
// No equivalent for Fractionation.CreationDateTime
  • You can now access the StructureSet of a PlanningItem directly. The PlanningItem class is the base class of PlanSetup and PlanSum. Even though these two classes had a StructureSet property, PlanningItem did not. In the following code, plan is of type PlanningItem:

// ESAPI 13.6
if (plan is PlanSetup)
    return ((PlanSetup)plan).StructureSet;
else if (plan is PlanSum)
    return ((PlanSum)plan).StructureSet;
    throw new InvalidOperationException("Unknown plan type");

// ESAPI 15.5

Unfortunately, ESAPI 15.5 doesn't provide a similar property for the Course, which both PlanSetup and PlanSum have. If you're trying to get the Course of a PlanningItem, you need to do something like the code above to get it.

  • The ExternalBeam property of the Beam class has been removed. It has been replaced by TreatmentUnit:

// ESAPI 13.6

// ESAPI 15.5
  • Several properties of the BrachyFieldReferencePoint class have been moved to a separate ReferencePoint class:

// ESAPI 13.6

// ESAPI 15.5

Some of the above differences are documented in the Eclipse Scripting API Reference Guide (accessible at Others I obtained by examining the API directly.

In some cases, you may want to work with both ESAPI 13.6 and ESAPI 15.5 in the same solution. I explain how to do this in the post Use Build Configurations to Manage Multiple Versions of ESAPI.

Related Posts

See All

ESAPI Essentials 1.1 and 2.0

A few months ago, I introduced ESAPI Essentials—a toolkit for working with ESAPI (available via NuGet). I've recently added one major feature: asynchronous access to ESAPI for binary plugin scripts. Y

Announcement: ESAPI Subreddit

A few months ago, Matt Schmidt started the ESAPI subreddit. It's another useful resource for finding and discussing ESAPI-related topics. According to the description, This community is to post and di

Dump All Patient Data from ESAPI

If, for whatever reason, you need to dump out all of the data for a patient from ESAPI, there's a quick and dirty way to do it. Well, there are probably several ways to do it, but here's one I've foun


bottom of page