Manage site references when deploying OSF assets
In an OSF application that supports multiple sites, the JSON files for
certain assets such as layouts include a sites
property that specifies the
URLs of the sites that the assets are associated with.
For example, in a layout used on two sites, the sites
setting in
the development environment might look similar to this:
...
"sites": [
"dev.example.com/electronics",
"dev.example.com/housewares"
]
...
However, in the test and production environments, the site URLs are typically
different from the URLs in the development environment; for example, the URL for the
electronics site might be test.example.com/electronics
in the test
environment and prod.example.com/electronics
in the production
environment. This means that when the asset is deployed from one environment to another,
the sites
setting will not be correct in the target environment,
resulting in a warning like this:
[cli] warn: Site with url or cross environment id 'dev.example.com/electronics'
specified in 'home-electronics.json' does not exist on environment.
You then need to modify the asset JSON files on the deployment target to reflect the URLs in the target environment.
To prevent this issue from occurring, Commerce defines a
crossEnvironmentId
property for site objects. The value of this
property can be used in asset site definitions to identify the site in all three
environments (development, test, and production), eliminating the need to update the
references after deployments.
For example, you could set the crossEnvironmentId
property on the site
object for the electronics site like this:
PUT /ccadmin/v1/sites/{siteId} HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en
{
"properties":
{
"crossEnvironmentId": "example-electronics-site"
}
}
After you set a crossEnvironmentId
value for a site, publish your
changes so they take effect. The next time you download assets to your workspace, the
JSON files will reflect the site’s crossEnvironmentId
value instead of
the site URL. An asset’s site definition will look similar to this:
...
"sites": [
"example-electronics-site",
...
]
...