Use the asset syncing tool to deploy template changes between two Matrix instances

This tutorial shows you how to use the asset syncing tool to deploy template changes from a Matrix development environment to a production environment.

The broad steps in this tutorial are:

  1. Set up a new site template on a development Matrix instance, and a site that applies it.

  2. Sync the template across to production so that everything is replicated.

  3. Add new functionality to the development site.

  4. Release that to the production environment, allowing you to test out the release process.

You will also gain an understanding of the limitations and constraints of using the asset sync approach so that you can better adapt your development and production release workflows to use the asset sync approach.

Before you start

For this tutorial, you will require:

  • Access to two separate Squiz Matrix servers.

    You cannot sync assets to the same server as a copy.

    1. A Matrix system administrator user account type on both servers. Your user account must be in the System management > System administrators user group.

    2. A conceptual understanding of what the asset syncing tool is, as described in the Asset syncing tool documentation.

    3. The asset syncing tool activated on both Matrix instances.

A root user can provide access to the asset syncing tool through the System configuration  Feature toggles screen section.

Import a new site to use with asset sync

This guide covers setting up Asset Sync to work with an individual template used for a single site. Because asset sync manages relationships between assets, syncing templates that are used across multiple sites is more complex and beyond the scope of this guide.

In this part of the tutorial, you will import a new site from an existing Marketplace template. Although you can use a template already in your Matrix system, it is recommended that you experiment with a new or isolated template first to learn how to use the asset sync tool without interacting with other assets already in your Matrix system.

  1. Download the Matrix 6 Bootstrap 5 Website Starter Template from the Squiz Marketplace.

  2. Follow the installation instructions on the installation tab to import the template and apply URLs to all site assets using the XML import feature (not the asset sync tool).

  3. Open the site URL and test your new template in the browser.

Sync your site to production

You will now use the asset syncing feature to sync the new template and site to the production server.

Create an outbound sync file from your development instance.

  1. Open your development Matrix server in admin mode. Make certain that you are exporting from the correct instance.

  2. Select Tools  Asset Syncing to open the asset syncing tool.

    If you do not see the asset syncing option check the Before you start section for tips on activating the feature.

  3. In the Outbound sync section, find the parent field under the Root nodes heading and click the asset target to select an asset.

  4. Select the folder of the template you just imported. It should be named “Matrix 6 Bootstrap 5 Starter Template”.

  5. In the File name field, add a prefix to the default file name so that you can easily identify the correct asset sync file later.

    • Add the prefix “first-deploy_” so that the file template looks like first-deploy_asset-sync_yyyy-mm-dd_hh:mm:ss You do not need to configure the Asset types field because you need to export all assets in the template.

  6. Select the Generate sync file button to start the export.

  7. Review the sync activity table lower down the page to see the progress of the outbound sync file.

    You will need to refresh the page to see updated progress. The export may take a few minutes.

  8. When the outbound sync is complete, find the correct file to download from the Sync activity table.

Check that you performed the asset sync, and the date listed was a few moments ago.

  1. Download the sync file beneath the Asset sync file heading.
    It should have the name first-deploy_asset-sync_yyyy-mm-dd_hh:mm:ss.

Run an inbound sync to import your template to production

  1. Open your production Matrix server in admin mode. Make certain that you are importing to the correct instance.

  2. Select Tools  Asset Syncing to open the asset syncing tool.

  3. Select Choose file and then select the sync file you downloaded in the Inbound sync section.

  4. Select Start inbound sync.

  5. Review the sync activity table lower down the page to see the progress of the inbound sync file. You will need to refresh the page to see updated progress. The export may take several minutes and will take longer than the outbound sync took to generate.

Finish setting up your site in production

When the inbound sync is complete, you will likely find your imported template under System Management  Asset Syncing Manager  Asset Syncing Temp Folder. This temp folder location is likely to occur only when importing a new set of assets.

  1. Move your asset folder from Asset Syncing Temp Folder into another part of the tree.

  2. Apply updated URLs to your site assets, repeating the step from when you first imported your template into your development server, but with URLs appropriate for the production server.

  3. Open the site URL and test your new site in the browser.

Add a component template to development

You now have a development site replicated in production, and both should be the same. You will now add a new feature to the development site. A good place to start is to create a component template and synchronize this over to your production site.

You can create a new component template from scratch, as described in the Create a component template to embed an image listing tutorial. For this tutorial you may want to consider downloading a simple component template from Squiz Marketplace so you can focus more on configuring asset syncing.

  1. Download the Call to Action component component from the Marketplace.

  2. Open your development Matrix server in admin mode.

  3. Create a folder under your Configuration folder called Component templates.

  4. Using the XML import tool, import the Call to action folder into the Component templates folder.

  5. Edit the component template asset’s Details screen.

  6. Set the Allowed root nodes field to the root node of your site folder, with the name Website.

  7. Edit your home page, and add the call to action component to your content above the main code block.

  8. Enter some text into the call to action component.

  9. Select the Pencil icon to change some of the call to action settings. For example, set a background color to blue and customize the text color.

  10. Select Save and view your page on the frontend. Your page will look similar to this example, depending on what customizations you have made.

asset sync imported site

Sync your component template to production

You now have a new component in development. You can now run an outbound and inbound sync to release the component to production.

  1. Make certain that you are signed in to the development Matrix server in admin mode.

  2. Open the Asset Syncing Tool and export the Component templates folder you created in the previous section, giving it a prefix of release-cta-component_

  3. When the outbound sync is complete, download the file. The filename should be named something similar to release-cta-component_asset-sync_yyyy-mm-dd_hh:mm:ss.

  4. Open your production Matrix server in admin mode. Make certain that you are importing to the correct instance.

  5. Start an inbound sync process using the file prefixed with release-cta-component_.

  6. When the sync is complete, confirm that the Allowed root nodes asset ID on the component’s Details screen has been correctly translated from its value in development to production.

  7. Add the component to your home page in production.

  8. Test that the component works as you expected it to work.

Caveats when applying this to your existing site

You have now tested a simple example of syncing a template between development and production. When you set syncing up for an existing site, you may have extra complexity in your implementation that is not represented in this example. In this case, you should test the implementation patterns used on your production site on test sites before you create the sync.

Consider the following points when planning out your asset syncing strategy between your development and production servers:

  • If your site uses URL-specific paint layouts, or user-defined paint layouts and designs, you will need to map URLs whenever running an inbound sync. Read more about this in the Inbound sync section of the Asset syncing tool documentation.

  • Do you plan on syncing assets with multiple parents (for example, linked under multiple pages or folders)? In that case, you should do extra planning when setting up your syncing strategy and adequately test the strategy to prevent issues with your site.

  • Syncing asset deletions can be complex if assets have multiple parent links. Ensure you understand this complexity and test deletions thoroughly prior to deploying your sync strategy to production.

  • If you want to share assets between one template and another, you should test the process end to end. For example, test that a shared components folder works when shared between multiple templates before syncing to production.

  • If you are using a single template applied to multiple sites, you will have links between the template assets and your content assets on multiple sites. Make sure you test this behavior when setting up your syncing process.

  • Matrix instances have a limited upload size (usually 50MB), limiting your inbound sync size. This file size limit may be a problem if you intend to sync very large changes or changes that include many binary files (for example, PDF files). Read the outbound sync considerations section of the asset syncing tool documentation for more information about file upload limits as they relate to asset syncing.

© 2015- Squiz Pty Ltd