Managing configuration values in OutSystems can quickly lead to a bloated and messy list of Site Properties,one for every feature toggle, API key, timeout value, and more. While functional, this approach becomes increasingly difficult to scale, navigate, and maintain,especially as projects grow and teams expand.
After running into this issue multiple times, I discovered a more efficient approach: storing structured JSON inside a single Site Property. This simple shift offers big benefits: cleaner configuration management, fewer properties to track, easier updates, and better grouping of related values.
Interestingly, there are 58+ community-submitted ideas related to improving Site Property management in OutSystems,ranging from versioning and logging to value grouping and description support. Clearly, this is a pain point many developers face.
The Problem with Site Properties Today
Here’s why the default Site Property approach starts to break down at scale:
No Organization – There's no native way to sort or group properties, making it hard to find related items.
Poor Grouping – Related values (like for a single feature) are scattered, not logically grouped.
Hard to Maintain – As more properties get added, understanding their purpose becomes harder.
No Logging – There’s no built-in history or change log for Site Property values.
Polluted Configuration Space – Single-use keys or temporary values add noise to the list. Too many for simple needs.
Why JSON?
Using JSON in a Site Property transforms the way you manage app settings. Here’s why:
Key Benefits
Fewer Site Properties – Group multiple values under one JSON property.
Logical Grouping – Keep related settings together, e.g., API configs or feature toggles.
Dynamic Parsing – Deserialize only what you need, when you need it.
Flexible & Scalable – Easily add or remove keys.
Simplified Versioning – Manage config as one JSON blob, easier to track changes.
The two most impactful benefits are:
How to Set Up JSON as a Site Property
Step 1: Create the Site Property
Create a new Site Property (e.g., EnvironmentVariables)
Set its data type to Text
Leave the default value blank (to avoid escaping characters in JSON)
Step 2: Define Your JSON Structure
You can define a structure two ways:
Manually:
Go to Data > Structures and create a new structure with attributes like Name, Value, and Description.
From JSON:
Create your JSON first in an editor, then in Service Studio:
Right-click Structures > Add Structure from JSON
Example JSON:
[
{
"Name": "SiteProp1",
"Description": "",
"Value": ""
},
{
"Name": "SiteProp2",
"Description": "",
"Value": ""
}
]
Step 3: Use It in Logic
Create a server action (e.g., GetEnvironmentVariables)
Use JSONDeserialize to convert the JSON text to a list of structures
Return the result for use throughout your app
Optionally, expose this through a Service Action if you're in a service module
Tips
Leave value blank in design time: this avoids escaping issues (like quotes)
Use strings for booleans in JSON to simplify parsing
Validate JSON before updating to avoid runtime errors
Going Further: Nested JSON for Advanced Use Cases
You can take this approach even further by using nested JSON. This enables parent-child relationships for more complex configuration scenarios.
Here’s an example from a feature I built called Quick Filtering, where saved search filters are bootstrapped from JSON:
{
"QuickFilters": [
{
"Name": "Todays Report",
"Group": "Report",
"Description": "Open Today report",
"Filters": [
{ "field": "Company", "operator": "equals", "value": "" },
{ "field": "DateFrom", "operator": "greaterThanOrEqual", "value": "Today" },
{ "field": "DateTo", "operator": "greaterThanOrEqual", "value": "Today" },
{ "field": "BankName", "operator": "equals", "value": "" }
]
}
]
}
I’ll cover this nested use case in more detail in a follow-up post.
Caveats to Consider
Before adopting this approach, here are a few important considerations:
Parsing Overhead Every time you read the JSON, you must parse it. This introduces a slight performance cost, especially if done frequently.
Manual Editing Risks Updating JSON via Service Center can be error-prone. there’s no validation or syntax highlighting, so a small typo can break parsing.
Loss of Type Safety Unlike native Site Properties, JSON values are stored as plain text and require manual type conversion, which can lead to runtime errors if not handled carefully.
Character Limit Awareness OutSystems doesn’t show how many characters you're using in the Site Property value. You’ll need to monitor this manually to avoid silent cut-offs or broken JSON.
Summary
Switching to JSON-based Site Properties gives you a powerful way to streamline your configuration logic in OutSystems. It reduces clutter, adds flexibility, and makes your app easier to maintain over time,especially in large or fast-moving projects.
If you find yourself managing dozens of Site Properties with unclear names or single-use purposes, give this approach a try.
