Creating a Virtual Staging Environment

• Video: Setting up a Virtual Staging Environment
• Example: Creating a VSE for a product launch
• Content Selection Rules
• The Virtual Environment URL
• Video: Consuming Assets in Virtual Staging

Creating and managing a Virtual Staging Environment (VSE) is an administration task and it's done by a trusted user with access to the Account settings app. The administrator creates the VSE, specifies where the content comes from and who has access to the environment. The Account app will then generate a URL that is used to access assets in this environment.

Watch the video below for a step by step guide to setting up a VSE. The sections below explain how to set up an environment in more detail, including content selection rules and how to use the domain generated for you create a VSE to consume assets.

Video: Setting up a Virtual Staging Environment

Example: Creating a VSE for a product launch

In this example we're going to create a Virtual Staging Environment to be used to manage content for a product launch. The launch team will be working on their project in parallel with other teams who might be updating content on live site or working on other projects. The project contains commercially sensitive images, so they want to restrict access to the content before it is live.

When the Account app is launched it allows you to view and edit any existing VSEs as well as to add new ones. We'll create a new VSE for the launch team and name it "Launch environment".

To create a new environment, launch the Account Settings app and choose "Add another virtual environment". You can then give the new environment a name and specify the rules it uses to retrieve and control access to assets.

Content selection rules

An Amplience VSE works differently to traditional virtual staging environments that require users to push content to a specific location. With an Amplience virtual environment, assets are "pulled" from specified locations, either asset stores within the Digital Asset Management (DAM) system, or from the endpoint used for published assets. When a virtual environment is created, a set of rules specify where the assets should be retrieved from.

In the "Add new rule" section choose the "Asset store" radio button and click in the area below labelled "Select an asset store". The list of asset stores available to you within the Digital Asset Management system will be shown.

For the "Launch environment" we specify that assets should be retrieved from the asset store named "Launch assets". If an asset is not found in "Launch assets", then the "Assets" asset store will be searched. Note that these assets are retrieved directly from the asset store in the Digital Asset Management (DAM) system, they do not have to be published.

To add these rules, choose "Launch assets" from the asset store list and click the "Add Rule" button. Then add the other asset stores you want to include in the order in which they should be searched.

The image below shows the rules we have added. For each asset store that is specified, it is also possible to add the metadata schemas that are supported. To choose which metadata schemas should be included, select the popup menu to the right of the asset store name and select the schemas you want to include.

If a metadata schema is not included in the list, then this metadata cannot be retrieved from the asset in the VSE. In this example, we want to be able to access the exif and image metadata for assets in this virtual environment, but you might also have a custom schema that you want to include.

Specifying only those metadata schemas that you want to include is a security feature, since we only want to make data available that you want to be. 

In many cases you will want to include the published version of an asset if it cannot be retrieved from one of the specified asset stores. This will often be the case if you are updating a site and not all the assets will be updated. To add an endpoint, click the "Endpoint" radio control, enter the endpoint name and click the "Add Rule" button.

In this example we publish assets to an end point called "customerstore".

Given a staging URL for an asset, the asset will first be looked for in the "Launch assets" store, followed by "Assets" and finally the endpoint used for published assets. 

The rules for the Launch environment, including the endpoint rule is displayed in the Account app as follows.

Before the virtual environment can be created you need to specify a "white list". This is used to control access to this particular virtual staging environment. White lists are discussed on the security page. For now let's assume a white list has already been created called "Launch team". With all the rules filled in and the white list specified, the virtual environment can now be created.

The Virtual Environment URL

When you click Save to generate a virtual environment it will generate a domain name, consisting of a random number and the staging domain, for example:

sq0cpchgtxt01p4urw5d945ni.staging.bigcontent.io

This URL is then used to access assets within this virtual environment.

For example, if your live content is published at the endpoint "customerstore", then the URL for accessing an asset called "launchimage" in the "Launch environment" virtual environment would be:

http://sq0cpchgtxt01p4urw5d945ni.staging.bigcontent.io/v1/media/i/customerstore/launchimage

Given this asset URL, the staging service will do the following

• Check that the requesting IP address is included in the white list for the virtual environment at 

  sq0cpchgtxt01p4urw5d945ni

• Try loading the asset from the  "Launch assets" asset store
• If it's not found, try retrieving the asset from the "Assets" asset store
• If it's still not found then it will try to load the asset from the "customerstore" endpoint. This will be the published asset

You can use this URL to access services such as Dynamic Imaging as normal, to create a thumbnail from the image, for example. See the video below for an example of consuming assets in a virtual staging environment is shown below.

Video: Consuming Assets in Virtual Staging

Workflow Using a Virtual Staging Environment

• Video: Workflow using Virtual Staging
• Asset Lifecycle
• Examples
  • Preparing assets for the next season
  • Previewing a Hot Fix before production
  • Supporting multiple parallel projects

Virtual staging environments are designed to support a wide range of different workflows and business rules. 

Watch the video below to see how Virtual Staging can fit in with your workflow. More examples of how your workflow can be enhanced are explained in more detail below.

Video: Using Virtual Staging to enhance your workflow

Asset Lifecycle

In the example of the "Launch environment" introduced on the Creating a Virtual Environment page , the lifecycle of assets would typically be as follows:

• The assets for the launch project are uploaded to the "Launch assets" asset store in Content Hub. Only authorised users would be able to access this store. 
• These assets would then be reviewed from a web browser, mobile app or ecommerce integration with access to the assets managed by the virtual staging environment. To make it easy for users, you might want to provide a UI to switch between the staging environment and production. The base domain of the staging URL, for example, zllu2w1z3lx51q8lxlzgzj5gr.staging.bigcontent.io would be used instead of the base URL of the production domain i1.adis.ws. The rest of the URL for an asset will be the same. 
  This is also explained in the workflow video included above, with separate development, staging and production environments that can you switch between simply by changing the base domain in the URL.
• When requesting an asset with a staging URL, the staging service will check that the requesting IP address is specified in the white list set up for this environment. See the security section for more details. 

When everything has been reviewed and approved, the content will be published to production. This might involve running a script to automatically publish everything in the "Launch assets" store, or only those assets updated between certain dates, depending on what business rules you want to implement. The published assets would then be accessed using the production URL.

Note: It is currently not possible to prevent users from publishing from a specific asset store.

Examples

Here are just some of the ways in which Virtual Staging Environments can adapt to and improve your existing workflow.

Preparing assets for the next season

In this example, one team is working on maintaining content on the live site while another is preparing content for the next season. The assets for the next season are uploaded to an asset store in Content Hub named "SpringCollection". A new virtual staging environment is created with rules that specify that assets should first be loaded from the "SpringCollection" store and if this is not found then the asset should be loaded from the live production assets. The team work on the new collection assets within the staging environment and when the work is complete and reviewed, the assets in the "SpringCollection" can then be published to production. The cycle will then continue with the next season's assets.

If an update was required to an asset on the production website, then this could be uploaded to the asset store used for production and then published, but requesting the same asset from within the next season's virtual environment would still return the asset from the "SpringCollection".

Previewing a "hot fix" before production

In some cases you might want to preview changes made to a production site before it goes live. One way of doing this would be to create a staging environment with a rule that pulls assets from the asset store used for production assets. In this example, the production assets are stored in the asset store named "Assets". 

The updated assets will be uploaded to this store as normal but not published. The staging service pulls the content directly from the asset store, allowing you to review it before it is published to the live site.

Supporting multiple parallel projects

If you have multiple teams working on parallel projects then it's possible to create a staging environment for each team, each with its own rules and its own asset stores. These teams would then be able to work independently of each other and not interfere with any other team's workflow.

In the example illustrated below, the content team want to be able to preview content before it goes live, while the QA team wants to work in a separate environment to the content team and not interfere with the content team's work. The QA team can create their own VSE, with content rules that specify that assets should first be looked for in the QA Team asset store, then the asset store being worked on by the content team and finally the live production assets. The content team creates their own VSE that just includes that asset store that they are working with and the production assets. 

You can create several staging environments and work with them in parallel, providing the flexibility to support many possible business processes.

Using Content Authoring with a Virtual Staging Environment

• Introduction
• Video: Working with unpublished content
• Examples
  • Creating content for a new product launch
    • Creating the VSE
    • Creating and consuming the content
  • Previewing a "hot fix"

Content created in the Content Authoring app can be consumed within a VSE, allowing you to preview content before it is published and to create content using both new and published assets. 

Using a VSE is straightforward and will require minimal changes to your existing code. To use a VSE you'd typically do the following:

• Upload your new and updated assets to an asset store. In the example below we have called this "Launch_assets".
• Create the new content in the Content Authoring app including new assets or a mixture of new and published assets.
• Create a VSE and specify content delivery rules to include the asset store containing your new assets, in this example "Launch Assets". Include any other asset stores that you want assets to be retrieved from. If you want to include published assets, then add the endpoint that assets are published to. For more information about rules, see Creating a Virtual Staging Environment.
• The asset store containing your content should also be included in the VSE's rule list. See the Creating the VSE section below for more details.
• Consume the content within the VSE by changing the domain in the content delivery URL to the domain of the VSE. This URL is used to send an AJAX GET request to the Delivery API to retrieve the content in JSON format. When the JSON is returned, the defaultHost for images and video will be set to the domain of the VSE, so no other code changes will be required in order to display the content.

Note: Image assets do not have to be published, but video must be published before it can be used within a VSE.

Video: Working with unpublished content

In this video we explain how to set up a VSE to consume unpublished content, walking you through an example using JSFiddle.

Examples

Creating content for a new product launch

Creating the VSE

To demonstrate how to consume content from a VSE, we'll use the example of a team preparing content for the launch of a new range of furniture. We want to be able to preview the content before it goes live and include a mixture of new and published assets. As discussed in Creating a VSE, when a VSE is set up you specify a set of content selection rules that includes the asset stores from which the VSE should retrieve its assets. In this case we're going to store the assets for the new range in the asset store called "Launch_assets" and include the asset store used for our production assets and the endpoint for our live site.

The VSE is set up in the Account app as shown below, with the automatically generated domain highlighted. In this example we want to give priority to unpublished content, so the asset store used for content is included as the first rule in the list. Including the content asset store before the endpoint used for published content will ensure that if there are two versions of content, one published and one unpublished, the unpublished one will be retrieved first.

The domain generated for the VSE is 

i3j8vuf7orqs1m913qwu779wm.staging.bigcontent.io

We will include this domain in the Delivery URL that we will use to retrieve content.

Creating and consuming the content

We'll use a simple banner, similar to the one created in the Content Authoring Developer Tutorial. The banner  is displayed using a combination of JavaScript, HTML, CSS and a handlebars template, but the approach will be similar whatever templating technology you are using.

The banner contains a green chair image loaded from the  "Launch_assets" store, together with a title, headline and strapline. Once the content is added, it can be  previewed from the Content Library by selecting the library card and opening the content in JSFiddle.

In JSFiddle, Some JavaScript code will be automatically generated, including the Content Delivery URL with the Content ID. If you 'Run' the JSFiddle code, a message will be displayed explaining the content has not been published, since by default the URL will reference the production environment with the sub domain c1.adis.ws. To preview the content within the VSE, just replace c1.adis.ws with the domain created for the VSE.

The content delivery API will then be as shown below.

When an AJAX Get request is sent to the Delivery API, the JSON content is returned. The inlineContent method of the CMS SDK is then called to flatten the content into a tree structure. For the banner the JSON will then look something like:

Notice that the defaultHost is set to the VSE domain. 

To access the greenarmchair asset you would use the following URL:

https://i3j8vuf7orqs1m913qwu779wm.staging.bigcontent.io/v1/media/i/ampevalmaster/springcollectionchair

All assets would be accessed using the same URL structure, whether unpublished assets stored in one of the asset stores, or published assets from the live site.

Once the VSE domain has been added to the query, and the required CSS and handlebars code has been added, the content can be previewed in JSFiddle. The green armchair is retrieved from the "Launch Assets" store and the content is shown in the preview window.

Consuming content from your website or mobile app would follow the same process, just including the VSE domain in the content query sent to the Delivery API. 

You may even choose to have multiple VSEs and provide a user interface to let your users switch between them.

Previewing a "hot fix"

A VSE could also be used to preview a "hot fix" to production content before it's made live. For example, perhaps instead of a green armchair we actually wanted to include a pink one. We could just upload an updated version of the springcollectionchair to the "Launch Assets" store and preview the content from within the VSE. Because the rules set up when we created our VSE specify that the "Launch Assets" store should be searched first, when we view the content with the VSE the pink armchair will be displayed. Once we are sure that everything looks fine, the asset can be moved to the asset store used for production assets and then published.

This example is explained in more detail below:

• The springcollection.jpg asset (the green armchair) is moved to the "Assets" asset store and published. The banner is published so that it can be viewed in the production environment. The production version of the banner will display the green armchair.
• A new version of the springcollection.jpg asset (the pink armchair) is uploaded to the "Launch Assets" store and included in an updated and unpublished version of the banner content. 

• To preview the updated content before it is published, view the content within the VSE. As shown below, assets are retrieved from the "Launch_assets" store first, so the content will include the pink armchair. 
• The updated content and spring collection.jpg asset can then be published and viewed in the live site.

Security

• The White List
  • Video: Setting up a white list
  • Example
• Other Security Features

The White List

When a virtual environment is created you need to specify a white list. The white list is used to restrict access to the environment to the set of IP addresses specified by an administrator. The video below provides an overview of setting up and using a white list.

Video: Setting up a white list

Example

In the example below, we are creating a white list called "Launch team" and adding the IP address for the London office team, this might be an IP address that is specific to the set of team members involved in the project and accessed via a VPN, for example. We've also included the IP address for the ecommerce server used for the project. Any request to access an asset in "Launch environment" that originates from an IP address not included in the white list will be ignored.

IP addresses are specified using CIDR notation and in this case we are specifying that the exact IP address must be matched. For security reasons, by default you can only include specific IP addresses rather than a range of addresses.

Other security features

The white list is the primary way of restricting access to a virtual staging environment, but there are a number of other security measures that protect your content from unauthorised access.

• Only an administrator has permission to create a virtual staging environment and grant read only access to the specified resources restricted by IP address. The administrator can edit the details of the environment, including the asset stores that can be accessed and the white list, or delete the environment, at any time. 
• When a virtual environment is created, we create a server side token and use this to store the security credentials that the administrator has defined for this environment. When an asset is requested using a staging URL, if the IP address making the request is on the whitelist, the staging service will look up the credentials on your behalf and load the asset based on the rules defined.
• Asset stores have permissions attached to them, so that only specified users can view and upload content to them. In our example, access to the "launchassets" asset store would be restricted to authorised users within the launch team.
• Only certain range of IP addresses can be specified by default, so the administrator cannot accidentally allow access and make assets public.
• By providing access to users via a VPN, that requires a user name and password or key based authentication, you can add a further layer of security to that provided by access control via a trusted IP address.