When managing multiple sites, you sometimes need to store values that are unique to each site — for example, a third-party API key, a tracking ID, or a locale identifier.

You have two options for storing site-specific data in dotCMS:

• Add a field to the Host Content Type — appropriate when a value is common to all (or most) sites and you want it managed as part of the site's content record.
• Use site variables — appropriate when a value is unique to a small number of sites, differs significantly across sites, or should be managed separately from the site content record.

This document covers site variables.

---

Adding a Site Variable#

---

1. Go to Settings → Sites.
2. Right-click the site you want to add a variable to and select Edit Site Variables.
3. In the Site Variables dialog, click Add New Site Variable.
4. Fill in the properties and click Save.
5. Flush the server cache. Site variables are intentionally not saved with the site itself, so a cache flush may be required before the variable is accessible from Velocity code.

Variable Properties#

---

Accessing Site Variables in Velocity#

---

Site variables are available via the built-in $host_variable Velocity object. Access individual variables as properties of that object:

$host_variable.{key}

For example, if you created a site variable with the key local_site_id, access it as:

$host_variable.local_site_id

Loading Site Context in Workflow Sub-Actions#

In certain contexts — such as a Velocity Script workflow sub-action — the site context may not be loaded automatically, which means $host_variable will be undefined. To explicitly load the site context, add the following line above any use of $host_variable, replacing [SITE_ID] with either the site identifier or the site key:

#parse("LIVE/[SITE_ID].site")

This applies equally when accessing site variables via the Scripting API.

Handling Unset Variables#

The $host_variable object is only created if at least one site variable has been defined on the site. If there is any chance the object or a specific variable may be undefined, use one of the following approaches:

Use Velocity's silent notation to suppress output if the variable is unset:

$!{host_variable.local_site_id}

Or check for the variable's existence explicitly before using it:

#if( $UtilMethods.isSet( $host_variable.local_site_id ) )
    #set( $localId = $host_variable.local_site_id )
#else
    #set( $localId = "defaultId" )
#end