This series has covered decomposing tables and connections, data functions, and data wrangling. This week, it moves to decomposing document properties. I have intentionally broken document properties out separately because there are so many different places they can be used. If you are just tuning in, here are links to the previous posts in the series.
As usual, each post in the series will be broken down into four sections.
- Quick and Dirty (Q&D)
- The Extended Version
- Room for Improvement
Understanding Document Properties
Now, the most important questions to ask and answer about doc properties are these:
- Which types of doc properties are being used?
- Are all of the doc properties used?
- Are any parts of the project broken because document properties were deleted?
Before we get started on answering these questions, I want to lay out a few critical pieces of information on doc properties.
- Types of doc properties in Spotfire
- Locations where doc properties can appear
- Syntax used to reference doc properties
Types of Document Properties
There are 7 types of doc properties available in Spotfire. I have included an example of each.
- Input field
- Input field multiple lines
- Drop down
- List box
- List box multi-select
Locations Where Document Properties Appear
Doc properties can be engaged in the following areas within a DXP.
- Text Areas
- Data Functions
- Visualization Properties
Now, a good place to develop an understanding of doc properties is the Edit menu > Document Properties > Properties tab.
This dialog will show all doc properties in the DXP, including default properties created by the application (MaxMissingTimeParts, FiscalYearOffset). This list will tell you exactly how many doc properties exist in the DXP. Use it as a checklist while walking thru the project. Unfortunately, this dialog fails to detail the type of doc property or where it is used. This is also where you will delete unused document properties if necessary.
Doc Property Syntax
Expressions reference doc properties in 2 ways. You will see different syntax depending on how the document property is being used or the type of value in the doc. In the screenshot below, I inserted the same doc property as a value and again as text to demonstrate the difference.
Quick and Dirty
The Q&D section will focus on text areas, data functions, and scripts because it’s very easy to click thru a project and see document properties engaged in these areas.
Now, for the Extended Version. It is much more time consuming (although not difficult) to find doc properties used in calculations and visualization properties. For calculations, go to the Edit > Column Properties > General tab. Scroll toward the bottom of the list (calculations are appended below imported columns) and keep an eye out for the document property syntax. There really isn’t a better way to do this. In theory, you could delete one document property at a time and look for ‘False’ in the IsValid Column Property, but that seems like overkill. Perform this task one table, one column at a time.
Next, doc properties can run deep in visualization properties. Anywhere you can right-click and either Set from Property or write a Custom Expression, doc properties can be used.
This includes most submenus in the properties dialog. Pay particular attention to data limiting (in the Data menu), Colors, Lines & Curves, and Show/Hide Items.
I will admit that finding all possible references to document properties can be extremely time-consuming. If in doubt, leave the doc property in and/or save versions of the project as you go.
The screenshots below came from a PPT documentation I assembled for a large project with a LOT of document properties. The text areas, data functions, IronPython scripts, visualization properties, and calculations all contained doc properties. Documenting usage became necessary to gain a comprehensive understanding.
Room for Improvement
Lastly, here are a few questions to ask and answer that will improve the project.
- Would renaming document properties make their purpose easier to understand?
- Can you delete unused doc properties?
- Would adding document properties improve the flexibility of the project?
Unfortunately, Spotfire does not allow you to rename document properties. To rename them, you must essentially create a new document property. I only “rename” document properties when completely rebuilding a project. I recommend removing unused document properties. If you delete, do a quick walk-thru of the project after each removal to ensure nothing has broken. Lastly, you might be able to improve the flexibility of a project by adding document properties. For example, if visualizations have show/hide rules or color rules that are currently hardcoded, you could replace the hard coding with a document property reference to make them more dynamic.
Wow, that was a long post. Now, you can see why I chose to break doc properties out on their own rather than including with another post. I hope you now have a much more comprehensive understanding of where document properties can be used in a DXP. They are one of the standout features of the application. If anyone from TIBCO is reading this, it would be great to have functionality within the application to track down usage of document properties.
Content created with Spotfire 7.12.
Guest Spotfire blogger residing in Whitefish, MT. Working for SM Energy’s Advanced Analytics and Emerging Technology team!