Webinars Revisited: A Review of ARIA APIs

Introduction

On March 23, 2020 I presented Introduction to ARIA Web Services on the MyVarian portal. In this Webinars Revisited series, we’ll use that session as our jumping-off point to explore all three ARIA API families—

• ARIA Access (SOAP & REST endpoints for core CRUD),

• ARIA Oncology Services (Operations for document management), and

• ARIA API (FHIR-compliant, VAIS-authenticated resources).

The goal here is to point out the most useful tips and starting points for developers as they get started with these APIs. This post will focus primarily on ARIA Access and ARIA Web Services, as those APIs have been around longer to develop familiarity with a detailed post on the ARIA API to come in the near future. Within this blog post, we will discover how to set up the ARIA Access and/or the ARIA Oncology Services APIs, and create a sample project that creates a new patient using ARIA Access and copies a phantom dataset to this new patient with ESAPI.

Along the way, you’ll see how to authenticate, where to point your calls, and which interface best suits your patient-demographics, document workflows, or next-gen FHIR integrations.

High Level Summary

1. ARIA Access API

• Protocol & Endpoints

  • SOAP: https://<host>:55051/Gateway/service.svc

  • REST: https://<host>:55051/Gateway/Service.svc/interop/rest/

• Authentication: Integrated Windows (Kerberos/NTLM) or Basic over HTTPS

• Payloads: XML or JSON

• Primary Use: Core CRUD on ARIA entities (Patients, Appointments, Orders, Look-ups, etc.)

• Strengths:

  • Mature, widely deployed

  • Broad coverage of administrative workflows

• Limitations:

  • SOAP endpoints being deprecated

  • Custom schemas (not standard healthcare formats)

2. ARIA Oncology Services API (Document Services)

• Protocol & Endpoints

  • SOAP WSDL: https://<host>:55051/Gateway/service.svc?singleWsdl&service=Patient.Documents

  • REST interop: https://<host>:55051/Gateway/Service.svc/interop/rest/Patient/Documents/{operation}

• Authentication: Integrated Windows or Basic over HTTPS

• Payloads: XML or JSON (with base-64 for binary content)

• Primary Use: Managing clinical documents—PDFs, CCDA, DICOM SR—and links between docs and ARIA objects

Strengths

• Rich document-specific operations (insert/update/search)

• Fine-grained link management

• Choice of SOAP or REST for your client

Limitations

• Focused exclusively on documents (you still need Access or FHIR for patients, appointments, etc.)

• Modifications of documents limited to Erroring out the document only. Cannot perform approvals or sign-off with API.

  
  

3. ARIA API (FHIR-Compliant)

• Protocol & Endpoints

  • RESTful FHIR R4: e.g. https://<host>/fhir/[Resource]

• Authentication: VAIS OAuth2 bearer tokens

• Payloads: JSON (FHIR profiles & Bundles)

• Primary Use: Interoperable data exchange using standard FHIR profiles—Patients, Practitioners, Appointments, Radiotherapy summaries (mCODE/XRTS), Financials, Audit logs, etc.

• Strengths:

  • Industry-standard FHIR profiles → easy integration with EHRs and third-party apps

  • Built-in search, paging, and batch transaction support

  • Future-proof, with growing ecosystem (SMART on FHIR, CodeX)

• Limitations:

  • Requires VAIS rollout at your site

  • Not (yet) as complete for every ARIA niche feature

Side-by-Side Comparison

Feature	ARIA Access API	ARIA Oncology Services (Docs)	ARIA API (FHIR)
Protocol	SOAP & REST	SOAP & REST	REST (FHIR R4)
Auth	IWA or Basic	IWA or Basic	OAuth2 (VAIS tokens)
Payload	XML / JSON	XML / JSON (base64 for binaries)	JSON (FHIR resources)
Core Focus	CRUD on core entities	Document import/retrieval/link	Standardized clinical & RT data
Standards Used	Proprietary schemas	Proprietary schemas	FHIR (mCODE, XRTS, SMART)
Tooling	WSDL clients / HttpClient	WSDL or direct REST clients	Swagger/OAuth2/OpenAPI
Best For…	Legacy integrations, batch workflows	Automating document-centric tasks	New apps, cross-enterprise interoperability

Getting Started with the ARIA APIs

When getting started with the ARIA Access and ARIA Web Services API, it may be useful to understand the following core steps of API use and access.

1. Where are the APIs installed and what is the API definition?

2. How to install and access API keys?

3. Initial Access to the API.

Accessing the Web Service Gateway

The legacy ARIA Web Service APIs can be found in the following location: https://<hostname>:55051/Gateway/Service.svc. If you're unfamiliar with the hostname or unsure how to find it, I generally like to access through the Varian Service Portal (VSP). The VSP should open at the correct hostname and port. Then simply change the URL location to end in Gateway/Service.svc.

The URL location direct you to the Gateway Service (no relation). This location reveals the basics of how to set up a test client as well as sharing how to build a C# client to handle the Resources provided by the API. The splash screen at this location should look as follows once reaching the site:

Clicking on either of the 2 links from this web service will share the definitions of the objects available from these APIs. Looking at an example of these class definitions, you can see one of the more useful objects available from the resource, the PatientAppointments.

Note: You may notice that these links listed in this site end in wsdl which stands for Web Service Definition Language.

Prior to using the APIs, an API key will need to be installed for authentication to the Gateway. These API keys are installed on the Varian Shared Framework server, and can be checked from the Varian Service Portal. After navigating to the Varian Service Portal and logging in, and navigating to Security--> API Keys. If you already have the API keys, then great! You're ready to get started with using ARIA Web Services.

Note: If an API key has already been installed, you will need to know the key value which isn't visible from this page. When API keys get installed in this server, the value of the key is available in a file written to the same drive as Varian's log files. This path my look something like: D:\VMSOS\Config2\WSF\Site.APIKeys.

Installing an API Key

API Keys for ARIA Access and ARIA Web Services (as well as ARIA API) can be installed from myVarian.com. Click on My Account and click on API Keys. Here the requester information and the API key type can be selected. Two API types available under ARIA are especially useful for developers:

• ARIA ONCOLOGY SERVICES: This API allows communication with patient documents.

• ARIA Access: This API allows access to patient information, appointments, prescriptions, diagnoses and more.

The Display API Key tab will show the API key for download once successful. This API key can be installed by copying the contents of the API key file (all of the content in the file) into the Varian Service Portal Page shown in the previous section.

Practice Using API

There are many use-cases for the ARIA Access and ARIA ONCOLOGY SERVICES APIs. In this example, the CreatePatientRequest will be explored. There are many needs to create a patient outside of clinical workflow. One such reason could be to generate a test patient for treatment planning practice. The rationale here for using this request to generate a QA patient and then use ESAPI to copy the phantom from another patient. For simplicity, and because we want to utilize ESAPI within this application, a Stand-Alone executable will be created from the Eclipse Script Wizard.

There are a couple of files needed to get started ARIA web services:

• Gateway.cs: Contains all definitions from the ARIA APIs.

• AriaService.cs: Contains Code to access Gateway and perform requests.

Note: To utilize these classes in your project, a few new libraries will need to be added. System.Net.Http will need to be used to set up an HttpClient for communication and the Gateway.cs file will need System.ServiceModel and System.Runtime.Serialization.

The extension of these files will need to be changed to .cs in order to include them in the ESAPI script.

Gateway.txt

Download TXT • 837KB

AriaService.txt

Download TXT • 3KB

Two methods within the ARIAService.cs file are worth examination:

The first method CreatePatient inputs the new patient last name, first name, and MRN, along with the API Key. The Last Name and MRN are required parameters to generating a patient with ARIA Access. The primary purpose of this method is to construct a JSON string with the request to create a new patient. The CreatePatientRequest method comes from the Gateway.cs file highlighting the utility of such a class in helping developers understand the format and properties of objects accessible to the API.

public static string CreatePatient(string lastName, string firstName, string MRN, string apiKey)
{
    // Create new patient providing required details.
    var createPatientRequest = new CreatePatientRequest()
    {
        LastName = new services.varian.com.AriaWebConnect.Common.String { Value = lastName },
        FirstName = new services.varian.com.AriaWebConnect.Common.String { Value = firstName },
        PatientId1 = new services.varian.com.AriaWebConnect.Common.String { Value = MRN }
    };
    //construct json request. 
    var request_base = "{\"__type\":\"";
    var request_createPatient = $"{request_base}CreatePatientRequest:http://services.varian.com/AriaWebConnect/Link\",{JsonConvert.SerializeObject(createPatientRequest).TrimStart('{')}}}";
    string response_createPatient= SendData(request_createPatient, true, apiKey);
    return response_createPatient;
}

The CreatePatient method calls the SendData method. This method is more generic and can be used with practically any ARIA Access or ARIA Oncology Services request. This method generates a new HttpClient from the System.Net.Http namespace and constructs a request using the ApiKey. The method then sends the request to the gateway service and waits for the response to return.

public static string SendData(string request, bool bIsJson, string apiKey)
{
    var sMediaTYpe = bIsJson ? "application/json" :
    "application/xml";
    var sResponse = System.String.Empty;
    // Create a new HttpClient with default credentials and pre-authentication.
    using (var c = new HttpClient(new
    HttpClientHandler()
    { UseDefaultCredentials = true, PreAuthenticate = true }))
    {
        if (c.DefaultRequestHeaders.Contains("ApiKey"))
        {
            c.DefaultRequestHeaders.Remove("ApiKey");
        }
        c.DefaultRequestHeaders.Add("ApiKey", apiKey);
        //in App.Config, change this to the Resource ID for your REST Service.
        var gatewayURL = $"https://{HostName}:{Port}/Gateway/service.svc/interop/rest/Process";
        var task =
        c.PostAsync(gatewayURL,
        new StringContent(request, Encoding.UTF8,
        sMediaTYpe));
        Task.WaitAll(task);
        var responseTask =
        task.Result.Content.ReadAsStringAsync();
        Task.WaitAll(responseTask);
        sResponse = responseTask.Result;
    }
    return sResponse;
}

The Execute method of the script has 2 custom method calls.

// TODO: Add your code here.
CreateNewPatient();
if (!String.IsNullOrEmpty(_mrn))
{
    CopyPatientImage(app);
    app.SaveModifications();
}

The CreateNewPatient method sets the initial parameters of the ARIA Access gateway service and port number. Then the console will request the last name, first name, and MRN for the user and request the patient be created. If the patient is created successfully, store the MRN to use with the next custom method that will copy the structure set of another patient.

private static void CreateNewPatient()
{
    //set up ARIA Service
    AriaService.SetInitial();
    //create a new patient. 
    Console.WriteLine("Please enter patient Last Name:");
    string lastName = Console.ReadLine();
    Console.WriteLine("Please enter patient First Name:");
    string firstName = Console.ReadLine();
    Console.WriteLine("Please enter patient MRN:");
    string mrn = Console.ReadLine();
    string output = AriaService.CreatePatient(lastName, firstName, mrn, "API-Key-Here");
    if (output.Contains("Success"))
    {
        _mrn = mrn;
    }
    Console.WriteLine(output);
}

The CopyPatientImage method opens the patient that was just created by ARIA Access. Then, it takes the PH_QA_001 patient, where my phantom image is stored, and uses the CopyImageFromOtherPatient method from ESAPI.

private static void CopyPatientImage(Application app)
{
    Patient patient = app.OpenPatientById(_mrn);
    if (patient != null)
    {
		patient.BeginModifications();
        // Copy the plan from PH_QA_001 to the new patient.
        Console.WriteLine("Copying image from PH_QA_001");
        StructureSet structureSet = patient.CopyImageFromOtherPatient("PH_QA_001", "PHANTOM", "PHANTOM");
        if (structureSet != null)
        {
            Console.WriteLine("Image copied successfully.");
        }
        else
        {
            Console.WriteLine("Failed to copy image.");
        }
    }
}

Running this app, you may see the output after the user puts in the requested information. Notice the response from the API is in JSON format, but clearly states "Success". This passes the MRN to the method that copies the image from the current QA phantom image.

The code for this ARIA request has been uploaded to the Gateway-Scripts Github.

Tips for Using the ARIA APIs

1. While the Gateway.cs file is indispensable and helpful at showing what classes are available and what parameters each request will return or require in a request, it is not perfect. You may need to override some parameters or create custom classes. One such example is the CustomInsertDocumentsParameter class in LDClark's PDtoARIA Github repository. The primary issue is that the Gateway.cs does not have the DateOfService or DateEntered parameters in the correct format and the class here overrides that behavior by generating a custom class object to serialize into JSON.

2. Generating class objects to serialize into JSON can sometimes be challenging. You must format the namespace as a URL location (its even case sensitive). Domenic Dicostanzo from OSU has posted an ARIA Access repository to Github. This is worth taking a look into to simplify all your requests into strongly-coded C# objects.

3. u/point314 has some excellent pointers to getting started with the brand-new ARIA API to the Medical Physics subreddit. Gateway Scripts looks forward to sharing more about the ARIA API as the API becomes more available to clinicians and developers alike.

I've been able to move this project along nicely with the help of some folks inside Varian. My general steps are below.

1. If you're seriously thinking about doing this stuff, make sure you do it in test before you do it in production! If you don't have an Aria test environment, I'd reconsider doing any of this. Personal opinion. Do you have to repeat steps 2-4 below in both test and production.

2. To start, it helps to have access to the VAIS server. By default, the VAIS server will only have one admin account...whoever installed the VAIS application in the first place (likely a Varian "service account" or the Varian installer's personal account). Have Varian make your account an admin account on the VAIS server.

3. It seems Varian will need to upload the API key to the VAIS server for you. I was never able to make this work myself. There is OK documentation on this process on the server where the API is installed at <hostname>:55370/document/clientcreation.html, but that documentation makes it seem like you could create a headless client yourself. I don't think you can...Varian will have to do this for you. Just ask that Varian creates a headless client for you with a specific name and "secret" (i.e., password), and they can do so. Then you go get the Client ID and the secret and record them for later use.

4. After creating this client, you will need to give the client rights to do what you want to accomplish. Think of this like any other user in VSP. Varian provided me with a PDF with a few slides on how specifically to set up this client in VSP and your DataAdmin environment. Configure this client (user) as the type of User you'd like to mimic for its rights profile (like Therapist, Physicist, etc.).

5. Now I was able to successfully get a Bearer Token (roughly described at <hostname>:55370/document/vaistokengen.html) and use that token to do cool stuff.

6. The new API comes with a nice "API Tester" page on the server. For me, that was at <hostname>:55371/tester/home?encoding=null&pretty=false. You can get a token created on this page using your client ID and secret, and then test various calls. Figure it out from here.

What have I been able to do with this so far? Well, after upgrading to Aria v18, we noticed that our UserHome task pads in particular were really slow and prone to crashing. Varian has told us that this may be due, at least in part, to excessive numbers of old tasks that are routinely queried to update the Overdue counter. Even with the Overdue config setting in General Settings adjusted, our task pads were still really slow. Varian told us that the only fix for this was to go back and cancel all old, open tasks...manually. With 20 years of department Aria history, this is basically impossible to do manually, but Varian would provide no tools for batch processing. I have now written code to pull out all open tasks for the last 20 years, record their properties into a .csv file, and then update the status of those tasks to cancelled. Took a few days of coding and testing, but hopefully this will speed up our task pads once I run it in production.

Conclusion

Navigating the ARIA API landscape can feel daunting at first, but as we’ve seen, each interface serves a clear purpose:

• ARIA Access ideal for maintaining or extending legacy integrations.

• ARIA Oncology Services (DOCUMENTS) provides rich, document‐centric operations.

• ARIA API (FHIR-compliant) is the strategic next step for new development and cross-enterprise interoperability.

  
  

Whichever path you choose, remember to begin in a test environment, secure your credentials (IWA, API keys, or VAIS tokens), and consult the Varian documentation and community-contributed samples to accelerate your progress. In upcoming posts, we’ll take a deep dive into the new FHIR-based ARIA API—complete with code snippets, best practices, and real-world use cases—so stay tuned. Until then, happy scripting, and may your integrations streamline workflows and empower your clinical teams!