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, Retail Digital 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",
      ...
    ]
...