Experience Versions

Experience Versions are frozen snapshots of a portion of your application experience resources that can be published to an experience domain or slug.

Viewing Experience Versions

“Versions” can be found under the “Experience” section of your application’s sub-navigation.

Experience Versions List

There will always be at least one version in the list: your “develop” version, which is the only editable experience version. All other versions in the list are frozen and cannot be directly edited.

The list of experience versions also indicates which domains and slugs (if any) are pointed at each version.

Viewing Version Contents

To view the resources within an experience version, simply click the name of the version in the list. This will take you to an interface where the views, workflows, and endpoints that make up selected version are displayed in a tree view.

Experience Version Details

You may also view different experience versions, and how a given resource changes across versions, by selecting the dropdown menu alongside your version name in the application’s breadcrumbs.

Experience Versions Breadcrumbs

If you are viewing a version other than the “develop” version, none of the resources will be editable, nor can you create any new resources. You will need to copy the version to “develop” if you wish to make any edits.

Copy to Develop

Creating an Experience Version

While viewing the “develop” experience version, you can create a new experience version by clicking the “Create Version” button at the top of the page.

Create Experience Version Button

This action will take you to a configuration page with the following options:

  • Version Name – a required field which must be unique within your application. The name can be any string, though many Losant users follow the semantic versioning specification for their version names.
  • Description – an optional field where you can put any information about the new version, such as significant changes or bug fixes.
  • Domains and Slugs – a list of domains or slugs to choose from that should point to the new version. This is also optional and can be changed at a later date within the domain / slug edit pages. Any changes made here will take effect immediately upon version creation.
  • CORS Requests – options to choose whether the new version will be accessible from any origin, to restrict access to specific origins, or not to handle CORS requests. You can configure OPTIONS routes from the Endpoint Configuration page.
  • Version Globals – optional key/value pairs that are available in all experience workflow initial payloads, as well as the default render context for all experience views, within this new version. You can read more about them here.

Create Experience Version

When ready, click the “Create Version” button. The experience views, workflows, and endpoints within your “develop” version will be frozen as part of your new experience version. The “develop” version will remain unchanged and you can continue to edit its resources as before.

Version Globals

Experience Version Globals

The concept of application globals can be applied at the experience version level. These are key/value pairs that store information for an experience version to use. They can be used across multiple experience version resources such as workflows, pages, layouts, and components. For example, you may want to store a hexadecimal color value for use with headings across all of your experience resources. This is a good way to share that color information.

Upon creating a new experience version, the globals are inherited from the “develop” experience version. You may add new globals in addition to those globals or remove them.

Experience globals override existing application globals with the same name when used in an experience workflow. However, experience globals can be overridden by experience workflow globals.

Version Settings

To edit the settings of an experience version, click the “Version Settings” option from the dropdown menu located at the top of your page. This will take you to the configuration page that is similar to the create experience version configuration page.

Version Settings

If you are editing the “develop” version, you will not be able to change the version name but everything else can be edited. However, if you are editing a version other than “develop”, you are only allowed to delete it.

Editing Non-Develop Version

Pointing Domains at Versions

You can associate a domain or slug to your experience version. Doing so will allow your users to view your experience at that specific domain or slug. From the dropdown menu at the top of the page, select the “Assign Domains” option.

Assign Domains

From the lists of domains and slugs, select the item you wish to edit, and on the next screen, choose the version you wish to use from the dropdown menu. The change takes effect immediately on save.

Experience Domain Change Version

You may also clear the version from the domain without assigning a new one; doing so means all requests to the domain will fail until a version is reassigned to it.

Editing Experience Versions

The resources within an experience version cannot be directly edited; the views, workflows and endpoints are frozen as part of the version. However, much like with workflow versions, you can copy one of your published versions to your “develop” version and make edits there.

To do so, click the “Copy to develop” link next to the chosen version within the versions list.

Copy Version to Develop Button

This will bring up a modal asking you to confirm the change, as doing so will completely overwrite your existing “develop” version. You will also have the option of automatically saving the current “develop” version as a new version so the resources are not lost forever. The new version will be given the name “develop-backup-{CURRENT_DATETIME}“.

Copy Version to Develop Modal

At this point, the resources within the version can be modified or deleted, and new resources can be added. When you are finished making changes, you can save “develop” as a new version and, optionally, point one or more of your domains to the new version.

Benefits

It is possible to build out a full application experience without using the experience versioning feature, but we strongly recommend doing so for the following reasons:

  • Creating versions allows for updating an experience after initial publication without disrupting your end users, as you can make changes within the “develop” version (which can be pointed at a staging domain) and only publish the changes to your production domain once the edits are complete.
  • Experience versioning makes it much easier to host two or more disparate end user experiences that are backed by the same Losant application data, as different domains can be pointed at different published versions.
  • Creating experience versions provides a means for revision history as the entire experience can be saved as a new version at any time. You may then look back at any past version or even copy the resources to the “develop” version for further editing.

Versioned Resources

The following resources are frozen as part of an experience version:

These resources will continue to exist within the application version even if their counterparts are deleted within the “develop” version.

Unversioned Resources

Special care should be taken regarding the following resources when building out an experience version:

  • Experience users exist outside of the versioning architecture, as do experience groups - specifically, which users are a member of a group.
  • Application global variables which can be referenced in experience workflows, are unaffected by experience versions. Changing an application global value will affect any experience workflow referencing the value.
  • Workflow storage spans across all workflow versions, including across experience workflow versions.
  • Application workflows that employ Endpoint Trigger and Endpoint Reply Nodes are not versioned as part of the experience. We recommend migrating any application workflows whose sole purpose is to handle endpoint requests to a new experience workflow so they get versioned along with the rest of the experience.

Deleting Experience Versions

Experience versions other than “develop” can be deleted one of many ways:

  • While viewing the configuration page for the version other than “develop”, you can delete the version by clicking on the “Delete Version” button located at the bottom of the configuration page shown here.
  • While viewing the version list, you can delete the version by clicking on the “Trash Can” icon located at the end of each row.

Delete Experience Version Button

  • While viewing “Delete Resources” tab under Application Info, you may choose the experience resources to delete.

Bulk Delete Experience Versions

Once an experience version is deleted, any requests made to a domain that was pointed to that version will fail until that domain is pointed to a different experience version.

Was this page helpful?


Still looking for help? You can also search the Losant Forums or submit your question there.