Asset syncing tool

This feature is currently available as a beta feature. Access to this feature is controlled through the System configuration  Beta feature configuration screen.

Asset syncing lets system administrators deploy changes to a set of assets repeatedly between Matrix systems. This method of synchronizing assets is best suited for creating template and component changes on a development environment and releasing these changes to a production site in a batch.

How does asset syncing differ from import/export?

Asset syncing works differently from the Tools features Import assets from XML and Export assets to XML.

With the Import and Export tools, you can only upload an exported set of changes once. This single-export method can be helpful when you need to import a large section of your site to another Matrix instance before you begin developing areas of the site between instances.

Asset syncing takes a different approach to asset import and export by letting you repeatedly update changes for a section of your site based on a set of filtering options you set when you export the asset structure. This repeatable sync method lets you build and test a design or template on one Matrix instance and then use the asset syncing feature to move the assets to another instance.

Considerations when creating an outbound sync file

Asset syncing is ideal for synchronizing templates and designs between Matrix systems. It is generally not suitable for synchronizing content between systems, such as:

  • Large content migrations

  • High-volume asset syncs

  • Many binary files such as images or PDFs.

The import file size is limited to 50 MB on Matrix SaaS systems. You can increase this limit on dedicated Matrix systems by adjusting the upload file size in your global settings. The larger the import file, the longer the import process takes. Take these considerations into account when planning your syncing deployments.

If you find that your asset syncing file size exceeds the file size limits, you can try breaking up the export into multiple sync files. This method also has the advantage of making the import process faster, which will help you iterate and test changes between your systems more efficiently.

The asset syncing interface

You access the asset syncing feature from Tools  Asset syncing in the Matrix toolbar.

The asset syncing interface has three main sections:

Inbound sync

This section lets you import a set of assets exported using the Outbound sync feature.

Outbound sync

This section lets you export an XML archive file containing a set of assets.

Sync activity

This section shows you the last 20 inbound and outbound sync activities made by all users across the system.

Inbound sync

The inbound sync feature lets you import an entire section of the asset tree from another Matrix instance and then keep this section synchronized with all future changes.

Inbound sync screen section

To provide the most reliable import experience, the outbound, and inbound Matrix instances must both be running the same software version.

Import a new asset tree structure using inbound sync

When you import assets for the first time into the destination system, the imported structure is placed into a temp folder so you can verify the import was successful.

Once you have verified the import was successful, move the assets from this temporary location to the desired location in the asset tree.

  1. Click Choose file to select the Outbound sync XML file you exported from the target system.

  2. Click Upload to begin the synchronization process.

  3. Refresh the screen to show the status during the import process.

  4. Open the System Management  Asset Syncing Manager  Asset Syncing Temp Folder.

  5. Review the imported files and check that the import contains all the assets.

  6. Once you are satisfied with the imported assets, move the imported asset tree structure to the required location in the asset tree.

Update an existing asset tree structure using inbound sync

After you have created a matching set of assets in both Matrix systems, any changes you make in the source system can then be applied to the destination system using subsequent inbound sync actions. Once the changes are complete and you have generated an updated asset sync file from the source system, you are now ready to perform an inbound sync on the destination system.

  1. Click Choose file to select the asset sync file you exported from the target system.

  2. Click Upload to begin the synchronization process.

  3. Refresh the screen to show the status during the import process.

  4. Open the System Management  Asset Syncing Manager  Asset Syncing Temp Folder for any new orphaned assets added by the latest inbound sync process.

  5. Move any new orphaned assets into the correct position in the asset tree structure.

If an asset sync file doesn’t include all the dependencies required by the selected assets, the inbound sync may look like it completes successfully, but the logs will indicate any relevant errors about the missing assets.

Outbound sync

The outbound sync feature generates an asset sync file which is a packaged set of assets. The selected assets are chosen based on the root node and asset types you select.

Asset syncing outbound sync section with default values pictured

Once generated, you can then download the asset sync file, which you can then use to perform an Inbound sync and have these assets replicated or updated on your destination system.

Root nodes

The root nodes section lets you select which section of the asset tree you want to include in your Asset sync file. You can choose whether to include a single top-level asset tree structure or a selection of multiple asset tree sections.

How to sync a complete asset tree structure

  1. Choose the top-level asset tree folder containing your template, component, or site.

  2. Click the Include and Children checkboxes.

  3. Click Generate sync file.

  4. Refresh the screen to show an updated progress status.

Large outbound sync files may take a long time to generate.

How to sync an asset tree structure with some parts excluded

Sometimes you may want to sync an asset tree structure that excludes a specific part of the structure.

  1. Choose the top-level asset tree folder containing your template, component, or site.

  2. Select the Include checkbox against the top-level asset tree folder.

  3. Choose the child asset structure that you want to exclude from the import.

  4. Leave the Include checkbox cleared against the child asset structure.

  5. Click Generate sync file.

  6. Refresh the screen to show an updated progress status.

Large outbound sync files may take a long time to generate.

How to sync multiple asset tree structures

Sometimes you may want to sync multiple trees of assets in one outbound sync. For example, you might want multiple content templates that share dependencies between templates.

If you decide, for example, to include multiple content templates that reference each other, the references between the templates will be maintained.

The outbound sync file is assembled based on the listed order of each inclusion or exclusion condition.
  1. Add each top-level asset tree structure you want to include in the outbound sync file as a separate root node parent.

    1. For the first entry, select from the following options:

      • Click Include and Children if you want all assets beneath the selected node to be added to the outbound sync file.

      • Click Include if you only want the top-level asset to be added to the outbound sync file.

      • Click Childrenif you only want that asset’s children to be included.

    2. Continue adding entries, being careful not to contradict the previous entries.

  2. Optionally select any asset types you want to filter on, based on the filtering guidelines in the Asset types section.

  3. Click Generate sync file.

Asset types

The asset types selector lets you choose which user-creatable asset types to include in the outbound sync file.

The following asset types are not available as conditions in an outbound sync file:

Dependent and shadow assets

These assets need an associated parent asset and can not be synchronized independently.

Assets that may contain sensitive data

These assets include the following types:

  • User account type assets

  • Form submission asset

  • Order asset

  • Ecommerce order asset.

Filtering options

The Asset type filtering options let you choose how asset types and their children types are handled in an outbound sync file.

Inherit Include Result

✔️

✔️

Include all assets of that type along with its children asset types.

✔️

Exclude exporting all assets of that type and its children types.

✔️

Include all assets of that type, but do not export any children asset types.

Exclude this specific asset type.

Inbound sync errors can occur if you include a set of assets but exclude their dependencies (such as linked designs or metadata schemas).

Sync activity

This section shows you the last 20 inbound and outbound sync activities made by all users across the system. As more sync activities run, older entries are removed from the sync activity table. You can also stop a running asset sync process from this section.

You can only run one inbound or outbound sync process at a time. Each sync process must complete before you can start another.
Sync activity screen with screen regions described using callouts below
  1. Displays the sync type and its status. This section also displays the percentage complete for currently running sync tasks and an indicator for whether the task was completed or stopped.

  2. You can cancel a stalled or running sync task using the Stop this sync button.

    If you stop an inbound sync process before it completes, changes made are not rolled back.
  3. The Matrix user that performed the asset synchronization.

  4. The asset sync file for the outbound or inbound sync task.

  5. The log file indicates any errors encountered during asset sync file generation or inbound sync tasks. If you see an error count next to the log entry, review the log and take action to remedy these if appropriate.

© 2015- Squiz Pty Ltd