ARIA API I: HL7, FHIR and the ARIA API

Interoperability in Radiation Oncology

Modern radiation oncology relies on an increasingly complex ecosystem of software and hardware systems working together to safely deliver patient care. A single treatment course may involve data flowing between imaging systems, treatment planning systems, oncology information systems, treatment delivery systems, quality assurance platforms, and hospital electronic medical records. While each of these systems serves a unique purpose, the true clinical workflow depends on their ability to communicate reliably with one another.

Historically, interoperability in radiation oncology has largely depended on standards such as DICOM and HL7 messaging. DICOM enabled the exchange of imaging and radiotherapy treatment data between systems, while HL7 provided a mechanism for communicating patient demographics, scheduling information, orders, and clinical events throughout the hospital environment. These technologies formed the backbone of connectivity in oncology departments for decades and remain critical components of clinical workflows today.

Within the V

arian ecosystem, the ARIA API represents an important step toward this modern interoperability model. Built upon contemporary web technologies and healthcare interoperability standards, the ARIA API enables developers to interact with clinical data using secure REST-based communication methods. This opens the door to a wide range of applications, including automated reporting, workflow assistance tools, integration with external systems, clinical dashboards, and advanced automation pipelines.

Fast Healthcare Interoperability Resources

FHIR is the modern interoperability standard from HL7. It was created to address the limitations in earlier standards -- most notably HL7 v2 -- by leveraging modern technologies and a simpler, more consistent data model. At its core, FHIR defines a set of modular components called "resources" that represent clinical and administrative concepts such as Patient, Appointment, Observation, or Medication. Each resource has a standard structure and a unique URL, making it easy to understand, exchange, and combine with other resources.

FHIR is organized around resources, each with a defined set of attributes. Resources can be linked to one another to represent real-world relationships (e.g., a Patient has Appointments). These resources are exchanged using standard web protocols (HTTP). FHIR is not a database or single application, but rather a standard for how data is structured and accessed. This allows different systems to share information in a predictable and consistent way.

Introducing the ARIA API

The ARIA API is a modern interoperability platform provided by Varian/Siemens Healthineers. Prior APIs included the ARIA Access and the ARIA Oncology Services API. While these APIs were heavily utilized and clinically useful, a more durable long-term strategy requires congruence between published standards (i.e. FHIR) and the API data format. Throughout this blog series, we will explore the components of the ARIA API and demonstrate clinically oriented examples of how developers may incorporate the API into their automation toolkit.

Check for the ARIA-API license in the VSP. If the ARIA-API license does not exist in the VSP License Administration, pause your exploration of the API and contact your Varian software sales representative. As of the writing of this blog post, the ARIA-API license is a $0 license, but a sales order is required to initiate the install.

One of the major advantages of the ARIA API is that it provides supported access to a wide variety of clinical and operational information throughout the oncology workflow. Rather than thinking of the API as a single monolithic interface, it is often more helpful to think of it as a collection of interconnected “resources.” In FHIR terminology, a resource represents a specific type of clinical or administrative object with a defined structure and set of relationships to other resources.

For example, a Patient resource may contain demographic information and identifiers, while Appointment resources can describe scheduling information and treatment visits. Other resources that may be of interest include DocumentReference for reading/writing and updating documents, Activities, Tasks, and Appointments for workflow management, and Treatment Plan and Course summaries.

This resource-based design allows developers to query and combine information in flexible ways. An application may retrieve a list of patients, identify upcoming appointments, locate associated treatment courses, and generate clinical dashboards or workflow tools — all through standardized API requests. Because these resources follow predictable structures, developers can build applications that are easier to maintain, expand, and integrate with external systems compared to many traditional custom integration methods.

An ARIA API tool will be installed with the install of the ARIA API. Please request your Citrix Administrator to publish this tool via Citrix to any developers utilizing the API. It is a helpful utility for testing and documentation.

As a basic introduction to the ARIA API, it may be advantageous to review the components of the API. The API is a licensed feature, meaning the clinic will require a license for ARIA API prior to its availability. As part of the administration of the ARIA API, a new tool, VAIS, the Varian Authentication and Integration Services tool is where the API clients will be configured. As part of the API configuration, developers will need to download an API key from MyVarian.com, so be sure to have the credentials ready. Lastly, client configuration will also require access to both Varian Service Portal (VSP) and Data Administration.

Requirements for the ARIA API

The best place to begin when wanting to get started with the ARIA API is to see if the ARIA API is already installed. One place to check, is if the license for the ARIA API is installed. In order to check installed licenses, log into the Varian Service Portal (VSP). From the VSP, click the Administrative Service and select License Administration. In the table for all licenses search for a license by the name of ARIA-API.

If the ARIA-API license does not exist in the VSP License Administration, pause your exploration of the API and contact your Varian software sales representative. As of the writing of this blog post, the ARIA-API license is a $0 license, but a sales order is required to initiate the install. Once the API is installed, there are some other applications that will be installed as well.

An ARIA API tool will be installed with the install of the ARIA API. Please request your Citrix Administrator to publish this tool via Citrix to any developers utilizing the API. It is a helpful utility for testing and documentation. The next installment in this blog series will focus almost entirely on this tool.

Configuration of an API Client

The first steps to configuration of an API client will take the administration team to MyVarian.com. From MyVarian, navigate to the user account page in the upper right hand corner. From there, a link to Product Services will allow for the expansion of the API Key Management tool. Important to this tool is to select VAIS and ARIA API into the API Key Details section. Once this request is made, an API key can be downloaded from the website. Keep this key for the next section.

Prior to using the ARIA API, a client must be configured. The client configuration is performed in the VAIS Administration tool. It's possible that a clinical physicist may not have administrative access to this tool, and therefore an IT administrator or Varian service engineer may be required to assist in this configuration. It all depends on your institutions approach to systems administration.

The first step to configuration of the client is to select which type of client to be created. For most requirements, a Headless Application would be a suitable choice. During the configuration of this API client, you must name your Client. Then, a client secret must be configured. The client secret has some rules that must be followed in order to successfully create the client.

• Must be at least 20 characters.

• Must be no more than 4000 characters.

• Only the following characters are allowed:

  • Letters: a-z, A-Z

  • Digits: 0-9

  • Special characters: * ! % # _ / @ -

• No spaces, tabs, or other symbols (including periods ".").

• Must include at least one:

  • Uppercase letter

  • Lowercase letter

  • Digit

  • One of the allowed special characters.

After the settings of the client have been input, the ARIA API key from MyVarian can be imported into the wizard. Once all settings have been input and the API key imported, the Client should be successfully configured. The VAIS Administration tool will then show a Client ID which will come in important later so make sure to store that ID.

Once the ARIA API Client has been successfully configured, the API client must be configured to perform actions in the clinical system. This includes registering the client in the VSP under Security --> Clients. Finally, the client must also be made a user in Data Administration and be associated with the proper departments to perform tasks within these departments.

Testing the API

In this blog post, we will cover just enough of the ARIA API tool to utilize the tester for testing access and configuration of the ARIA API. In the API Tester, the upper right portion allows developers to request an API key. The requirements for the API key include the Client ID (provided from the VAIS Administration tool post-client creation), the Client Secret, and the Scope.

One note about the scope: The Scopes are accessible from the ARIA API key that was downloaded from MyVarian. From the MyVarian key, these scopes are comma delimited, but within this tool (and in the code) the commas should be replaced with a space " ". Once all requirements are input into the VAIS token, clicking Generate Token will create a bearer token for use in the tester.

One simple API test is to attempt to access a patient given the patient MRN. On the left side of the API, all profiles are accessible. Select the Patient profile. The MRN of the patient is noted as an identifier in the patient profile. Select Identifier from the search parameters and place the patient MRN in the Code section. The System Section is more of a scope or namespace (in this instance the patient MRN lives inside the ARIAID1 System, but its not required to remember this for testing).

If the patient details are loaded in a long JSON file format, congratulations, you have successfully configured and tested the ARIA API.

Conclusion

Modern interoperability standards are rapidly changing the way clinical systems communicate within radiation oncology. Technologies such as HL7 FHIR and REST-based APIs are creating new opportunities for developers, physicists, and clinical teams to build scalable, maintainable, and supported automation solutions around clinical data.

The ARIA API represents an important step in this evolution within the Varian ecosystem. While the initial configuration process may appear complex at first, understanding the core architecture of VAIS, API clients, authentication, and FHIR resources provides the foundation necessary to begin developing meaningful clinical applications. Even simple access to standardized patient, scheduling, and workflow data can open the door to powerful tools for reporting, workflow management, quality assurance, and operational analytics.

In this first installment, we introduced the foundational concepts behind interoperability, reviewed the role of FHIR within modern healthcare systems, explored the architecture of the ARIA API, and demonstrated the basic process of configuring and testing an API client.

In the next article in this series, we will take a deeper look at the ARIA API Tool itself, explore available resources and profiles in greater detail, and begin navigating the API more efficiently using practical examples and workflows relevant to clinical developers.