October 1, 2025
Select an option to view the article tailored to your learning style
For those who want to dive deep into the technical details
For those who want to understand the big picture
Few minutes read that gives you the high-level points
You can watch the full tutorial video below.
If you have been using Spotfire for a while, you already know how flexible it is. But there are parts of the platform that most people never touch. Document properties are one of those features.
Most users recognize the menu, but very few realize how powerful these properties can be once you start using them the right way. They are often the difference between a static dashboard and something that feels more like an interactive internal application.
This is the first part of a larger series on advanced Spotfire capabilities. Today we are starting simple with document properties. They are the foundation that makes the more advanced features possible.
Think of a document property as a variable. It is just a value you store that Spotfire can reference in many different areas.
A document property is a typed value stored inside your analysis.
You can create them under:
File → Document Properties → Properties
Assign a name, choose a type such as string, integer, real, currency, date, or boolean, give it a default value, and you are set.
Once the value exists, you can use it in:
This creates a single source of truth that your visuals and logic can reference.
Here is an example. Say you create a numeric document property called number with a default value of 10.
In a calculated column expression, you can write:
[BOE] * ${number}Your production data is now scaled by whatever value the user enters. You can duplicate a visualization, bring in the new column, and immediately see the difference.
Change 10 to 2.2 or 0.8, and the visual updates in real time.
This is useful for:
You can expose the value in a text area so users can change it without touching the calculation.
Numbers are straightforward. Strings require one extra step.
Let’s say you have a string document property called string and you write this:
[Well Name] = ${string}Spotfire returns an error that does not make much sense. Why does this happen?
Spotfire needs the property wrapped in quotes before it treats it as a literal string value.
The correct form is:
[Well Name] = "${string}"The quotes convert the value into a literal string that Spotfire can compare. This is the most common mistake people run into when working with document properties. Once you know this rule, things start clicking.
Once you have the string property working, you can create custom filters that update instantly.
For example:
[Well Name] = "${string}"This creates a column of TRUE or FALSE values depending on what the user typed into the text area.
This pattern gives you:
It is a simple pattern that opens up a lot of flexibility in your workflows.
Anywhere you can write an expression, you can reference a document property.
For example:
[Well Name] = "${string}"This lets you limit data at the visual level based on user input. It is an easy way to build dynamic views without relying on the traditional filter panel.
Other common uses include:
It keeps your interface clean and gives your users more control.
One of the most overlooked features is using document properties to control chart titles.
Say your property string is set to October 2025.
In the title field for a visual, you can write:
Monthly Report – ${string}Now your visual displays “Monthly Report – October 2025.”
Change the value in the text area, and every referenced visual updates automatically.
This is perfect for:
It adds a clean, professional touch to your dashboards.
Document properties can act as inputs to Python or R data functions. This is where things become very powerful.
You can pass in values such as:
Inside the script, you can run whatever logic you need.
This lets you:
Document properties become the bridge between user inputs and your backend logic.
Document properties can also trigger IronPython scripts whenever the value changes.
This allows you to:
It works like an event listener. Whenever the value changes, the script fires.
Even a simple “Hello World” example shows how it works. Real dashboards often use this to create app-like behavior.
Document properties update instantly, but keep these notes in mind:
Used in the right places, they perform very well. Just be mindful of where they fit in larger datasets.
Document properties are one of the most underrated features in Spotfire. They seem simple at first, but once you start using them, they unlock:
If you ever feel limited by what Spotfire allows out of the box, document properties are usually the path forward.
This is the first part of a deeper series. We will cover custom expressions, over functions, data functions, and IronPython in upcoming pieces.
If you want help designing internal Spotfire tools or leveling up your dashboards, feel free to reach out at info@aai.agency.