Releases & Scheduling

With Uniform releases, editors can edit, preview and review content ahead of time to better manage campaigns, event-driven content, product launches and more. Compositions, entries and patterns can all be added to a release, and then launched together in-bulk either manually, or automatically at a scheduled date and time in the future.

By using releases, editors will be able to;

• Build and publish content in a preview environment away from production to review multiple content edits at the same time.
• Create and schedule multiple iterations of content ahead of time, to support regularly updating content - such as a daily promotion that appears on a home page.
• Launch content in bulk across multiple pages and entities, allowing for large campaigns or broad-spanning content releases to be handled in a single place.

How does a release work?#

A release acts as a container for all the content that is created, edited, deleted or unpublished during the time in which it is active. After a release has been created, an editor can activate the release at anytime, at which point every time a piece of content is saved, a copy of that content will be created and placed in the release, instead of being managed in the “base” of the project.

What is the “base” state?#

Base is the default editing environment for content inside of Uniform, and the target state for any content which is copied into a release and launched at a later date. In this sense, “base” can be considered as the “main” or “production” state for content, and all Uniform processes such as API requests or our content delivery system will pull content from the base state by default unless otherwise requested.

Every Uniform project comes with a base state, which you will be able to see in the main navigation;

Mechanics of a release#

Initially, when you create and activate a release the project will be inheriting content entirely from base. When you open a Composition, it will be the base version of that composition which you are viewing;

The moment you make any edits to a piece of content when inside of an active release, you will be asked if you would like to copy that content into the release. Once copied, the content in the release will no longer be inheriting from the base state of the project, and any further changes in base will not propagate to the copy in the release;

When a release is launched, all content which was copied to the release will replace the content which is currently in the base state;

Releases are also able to support the creation of brand new content, the publishing of content which is only in draft or the deletion or un-publishing of currently existing content. This works in the same way as above, content that is created or deleted when a release is active will only be saved to the release and that state change will come into effect only when the release is launched. You can find out more about this later in this document.

What type of content can be inside of a release?#

Releases support all of the core content objects of Uniform;

• Compositions
• Entries
• Patterns

Note that data resources, which allow content from external sources to be connected to the entities above, are also supported by releases. This means that selections of items from external sources, configuration of data resources or brand new data resources can also be created and edited as part of a release.

Creating a release#

You can create a release in one of two ways;

From the releases dashboard#

1. Navigate to the releases dashboard and click “Add release”

2. Provide a name for the release and optionally also provide a tentative date and time for the schedule.
3. Click “Save” to create your release

From the Release Switcher#

You can also start creating a new release from anywhere within Uniform by selecting the “Add new release” option in the release switcher and following the same steps as above.

Adding content to a release#

Activating and switching between releases#

The easiest way to start adding content to a release is to activate the release in your project. When a release is active, all content which is created, edited or deleted whilst the release is active will be immediately copied into the release.

There are two ways to make a release active;

1. You can activate a pre-existing release at any time by using the release switcher, located in the main navigation.

2. Releases created through the release dashboard can also be activated by using the three dot menu "•••" located next to the release or on the release details page.

Copy content into a release#

With a release active, you will notice that there is a magenta coloured bar present when opening a composition, entry or pattern. Initially, this bar will display “inheriting” to inform you that the content has not yet been copied and is being inherited from the base state.

As you make edits to the content, you will see there is an option to “save to release” by clicking the button in the top-left corner. Clicking this button will create a copy of the composition with the changes you have made up to that point, and place that copy into the release.

After copying your content into the release, you will now see “copied” in the magenta release bar to inform you that the content is no longer being inherited from base, and is now a copy inside of the release.

Creating new content in a release#

Releases also allow editors to create new content from within a release. With a release currently active, any new composition, entry or pattern will be created exclusively within the release – instead of in the base state. When the release is later launched, this content will be made available for the first time to base.

When content is created within a release, it will not be visible when navigating a project in base. You must ensure that the release which includes the content is active for that content to appear on lists and in search.

Publishing content in a release#

Content within releases preserve their publishing lifecycle in order to ensure all content is correctly validated before launch and to allow for publishing states to be controlled through releases (for example, when un-publishing content).

As such, in order for the release to launch content directly in an already published state, it is always important to “publish to release”. This option is provided in the top-left corner of compositions, patterns and entries when a release is active;

The publish state of content within a release can be checked at any time by opening the release details page and looking for the status indicator next to each piece of content;

Launching a release#

Now that you have created a release and copied content into that release, the final step is to launch the release to send the content live. This can be done manually at any time, or you can choose to schedule the release to be launched automatically at a date and time of your choosing.

Manual launch#

First, ensure that the “Schedule” field on the release is empty and the release has been saved. Click the “Launch…” button in the top-right corner to proceed to validation;

Validation#

A validation screen will be displayed which will highlight any issues which could impact the outcome of the release. These include;

• Changes on base – if a piece of content has been updated on base after that entity was copied into the release this may mean that there are changes in base that could be overwritten by the copy in the release. We recommend reviewing the copy in base against the version in the release to ensure no important content will be overwritten.
• Unpublished content – Content in a release will not alter the published state of the content in base on launch unless it has been published to the release. If Uniform detects that a composition or entry has been left in a draft or modified state then it will flag these cases to be reviewed before launch.

After reviewing the validations, you can choose to launch the release immediately by clicking the “Launch now” button in the bottom-left corner of the drawer.

Scheduling a release launch#

If you would like your release to launch automatically at a later date, then you can take advantage of the release scheduling feature. In order to activate this, first you will need to add a date to the schedule field on the release as below;

Next, once all of the content for your release has been prepared, you will need to “lock” the release in order to validate the content within the release and also to prevent further updates to release content from affecting the launch of the release. To do this, click the “Lock for Launch…” button in the top-right corner. You will then be taken through the same validation step as explained in the section above;

Unlocking a release#

After you lock a release to enable automatic scheduling, the release will enter a read-only mode to ensure the validity of the release is not affected by further edits before the schedule is reached. If you would like to make further edits to the content in a release, to add new content into a release, or to change/cancel the schedule of a release, then the release must first be unlocked.

This can be done by simply clicking the three dot "•••" menu in the top-right hand corner, and selecting the “Unlock release” option.

Be aware that an unlocked release will not be automatically launched unless the release it locked again after any edits or modifications have been made.

Technical configuration#

Previewing release content#

If you are using visual canvas to preview content in Uniform, then compositions and entries inside of a release will be automatically preview-able without any additional configuration, so long as the release has been activated.

If you would like to preview release content outside of the Uniform platform, perhaps to share content with stakeholders for review or to preview a website in a separate tab, then you can direct Uniform to select compositions and entries from a particular release by passing the release ID to the CanvasClient or ContentClient constructor, as below;

Webhooks and triggering rebuilds#

When using the releases feature, it is important to review the services which are subscribed to webhooks from Uniform so as to best ensure that these services are triggered at the most appropriate moments. The events which trigger certain webhooks can be seen in the illustration below;

Rebuilding websites after a release#

In order to prevent unnecessary rebuilds of a production website when using the releases feature, we recommend following these tips;

• Ensure that release scoped events from content objects are not triggering rebuilds.
  • These events are denoted by the .release part in the event name - such as entry.release or compositon.release .
• Take note of the trigger property in non-release scoped content events.
  • When content is launched and moved into the “base” of the project, Uniform will emit individual events for content objects such as compositions and entries. This can cause a lot of events to appear in quick succession. These events can be filtered out by looking for the presence of the trigger property in the webhook payload, which should include information about the type of trigger (release) and the ID of the release.
• Leverage the release.launched event for rebuilds after releases.
  • The release.launched webhook fires after all of the contents of a release have been moved into the base, and the launch process has ended. As such, we recommend using this webhook to initiate site rebuilds.
  • For partial rebuilding of websites, you can also use the release ID from this event to make a call to the release contents API, which will provide details around the entities that were launched as part of the release.

To learn more about the webhook events available and the expected payloads, check out our webhook catalog.

Roles & permissions#

Four new permissions have been added to support the releases feature. These are;

• Releases Create – Controls the ability for users to be able to create a new release.
• Releases Update –  Controls the ability for users to be able to edit release details, such as the name or the tentative schedule date.
• Releases Delete – Controls the ability for a user to delete a release.
• Releases Launch – Controls the ability for a user to launch a release. This includes the ability to lock a release with a schedule, for launch at a later date.

Adding and removing content for a release involves the creation and deletion of content records that are scoped to the release. As such, permissions for this action is controlled by the permission within the Compositions/Entries/Assets permission category.

Limitations#

The releases feature has the following limitations;

• Supported entities – Releases are designed to help users preview, modify and launch content, and as such the entities that can be copied into a release are limited to;
  • Compositions (and patterns)
  • Entries
• 250 content items/release – a single release can hold a maximum of 250 content items (compositions, entries or patterns). This limitation ensures that releases can be launched in a time effective manner.
• 1000 open releases/project – there is a soft-limit of 1000 open releases per projects. An open release, for the purpose of this limit, is a release that is neither deleted, or already launched.
  • For customers that are not subscribed to an enterprise plan, this limit is reduced to 1 open release/project.
• Parallel release schedules not supported – no two releases can be scheduled to launch at the exact same time in the future for a given project. Schedules must be staggered by a minimum of 1 minute.
• Processing time for releases – the launch process for releases is an asynchronous process handled by Uniform’s servers. The processing time for this process is dependent on multiple factors, such as the amount of content in the release. As such, Uniform can not guarantee that scheduled content will be available at the exact time of a scheduled launch. To know when a scheduled release has finished processing, we recommend taking advantage of our webhooks.
  • Note; Most releases should not take longer than 60 seconds to launch.
• CLI Support – releases are not supported for the Uniform sync commands via the CLI. These commands are used to serialize projects for import & export purposes, which can cause issues for ephemeral entities such as releases that can be scheduled and launched.
  • Note; releases are supported fully by the Uniform API