How to update customized layout templates after upgrading Online Store : CloudBlue Technical Support

1. Symptoms
2. Resolution
3. Why do you need to do it?
4. Workflow
- 4.1 Reusing files that you obtained during the utility execution in the sandbox environment
- 4.2 Checking your layout templates for possible conflicts
- 4.3 Preparing layout templates
- 4.4 Importing layout templates back to Billing
5. How to update templates manually
6. How to revert the changes
7. Additional options for experts

Symptoms

A pre-check report and a log file contain a message that you are using customizations in online store templates that should be updated to the latest version delivered with the new release of CloudBlue Commerce, and after upgrading CloudBlue Commerce to new version, you must perform some steps.

Resolution

After upgrading CloudBlue Commerce to a new version, we recommend that you run a special script called "store-templates-assistant", which will help you update all customizations in existing layout templates to the newest versions.

Why do you need to do it?

Each online store can be customized by modifying layout templates. These changes are applicable only to the Online Store version in which they are made. When a new Online Store version is released, it is possible that the layout templates on which customizations were based were changed as well. These changes might be critical: If they are missing from the customized layout templates, the online store might be inoperable.

To simplify the updating of layout templates, we created a special utility called "store-templates-assistant".

To run it, perform the following steps:

Check whether PostgreSQL installed on the Billing database node is configured to allow connections from the CloudBlue Commerce management node. Connect to the Billing database node over SSH and check the '/var/lib/pgsql/9.6/data/pg_hba.conf' file. This file must contain a line similar to the following:
host all all <MN_IP_ADDRESS> 255.255.255.255 md5
where '<MN_IP_ADDRESS>' is an IP address of the CloudBlue Commerce management node. If you cannot find such a line in the "pg_hba.conf" file, add it to the end of the file:
host all all <MN_IP_ADDRESS> 255.255.255.255 md5
Restart PostgreSQL.
Download the store-templates-assistant.tar.gz file to the CloudBlue Commerce management node.
Issue the command: tar -zxf ./store-templates-assistant.tar.gz
Issue the command: cd ./store-templates-assistant

Workflow

Retrieve a list of customized stores and layout templates with possible conflicts.
# ./store-templates-assistant --check-possible-conflicts --all --detailed
Export the customized layout templates from Billing to the file system and apply the changes from the latest Billing version to it.
# ./store-templates-assistant --prepare-templates --all
If the utility cannot apply the changes automatically, you will be prompted to apply the changes manually. Select one of the stores for editing and edit all its templates that were not updated automatically. After you finish editing the store, you can go to the step 4 and import the changed templates back to Billing.
All templates of the selected store are located at the following path:
./output/store-<StoreID> where StoreID is a unique ID of the selected store.
You can learn how to do so in the section How to update templates manually.
Start importing the changed templates of an online store back to Billing.
# ./store-templates-assistant --apply-templates --store-id=<StoreID>
Note: To simplify the process of applying manual changes to similar templates in different online stores, the utility will automatically find such customizations in other stores and will correct them.
Important: Before you start importing templates back to Billing, double-check to make sure that all templates were properly corrected and that they do not contain errors, otherwise the online store might be inoperable.
Edit the next store, and return to the step 4.

Reusing files that you obtained during the utility execution in a sandbox environment

If you upgraded CloudBlue Commerce in a sandbox environment and updated all layout templates by means of the utility, we recommend that you keep the cache of the utility. You can use this cache to update layout templates in a production environment. In this case, you will not have to manually edit the templates again: they will be updated automatically.

Steps to perform (all paths are specified relative to the path where the utility is located):

Archive the utility's cache in the sandbox environment:
cd ./lib/data
tar -zcf .hash-<target CloudBlue Commerce version>.tar.gz .hash-<target CloudBlue Commerce version>
Copy the resulting file to your local computer.
Install the utility in a production environment. You can learn how to do so in the section To run it, perform the following steps.
Make sure that you are in the directory containing the "store-templates-assistant" utility.
Go to the directory "./lib/data":
cd ./lib/data
Copy the cache archive you previously prepared to this directory and issue the command:
tar -zxf .hash-<target CloudBlue Commerce version>.tar.gz
After running this command, a new directory starting with the prefix '.hash-' in a name will appear in the directory './lib/data'.
Start preparing templates as described in Workflow > 2..
All online stores will be updated automatically.
Important: If there are customized templates in the production environment that were missing from the sandbox environment, you will need to manually edit them.
Start uploading templates back to Billing. You can learn how to do so in the section Workflow > 4.

Checking your layout templates for possible conflicts

This is a quick analysis of templates that contain customizations, which might become inoperable after upgrading Online Stores. This command only informs you about the possible issues. You can use it anytime.

Issue the command:

./store-templates-assistant --check-possible-conflicts --all - Shows a list of affected stores.

./store-templates-assistant --check-possible-conflicts --all --detailed - Shows a list of affected stores and affected templates.

This command does the following:

Exports layout templates from Billing to a local file system.
Automatically analyzes whether the exported templates are compatible with the templates shipped in the latest Billing version.
Shows a list of online stores and templates that can be potentially corrupted after upgrade to the current Billing version.

Preparing layout templates

Use this command to automatically update your layout templates to the latest versions shipped with the latest Online Store update. If any critical incompatibility issues are detected during an attempt to update templates, you will be prompted to edit such templates manually using a text editor. If there are online stores for which all templates were updated successfully, you will be prompted to import such online stores back to Billing immediately.

Issue the command: ./store-templates-assistant --prepare-templates --all

This command does not change anything in Billing. If there are stores in which all customizations were updated automatically, the utility will prompt you to import all changes to Billing. We recommend that you check the results of automatic updating before importing changes to Billing.

This command does the following:

Exports layout templates from Billing to a local file system.
Automatically analyzes whether the exported templates are compatible with the templates shipped in the latest Billing version.
Automatically makes changes to the exported templates to ensure the proper operation of the online stores.
Provides a detailed report about the operations performed by the utility and explains how to resolve any incompatibility issues with the exported templates.

Note: If you run the command --prepare-templates the second time, it will remove all templates with your changes that were previously exported from Billing. In such a case, you can lose all your changes if you proceed with running this command by responding "Yes" when prompted to confirm: "Continue anyway?"

Importing layout templates back to Billing

Issue the command: ./store-templates-assistant --apply-templates --store-id=<StoreID>

Issue the command: ./store-templates-assistant --apply-templates --all - to import all online stores.

This command automatically analyzes all exported templates, including those that you previously corrected, and imports the online stores whose templates do not contain any conflicts. For all other stores, you will be prompted to correct templates to resolve conflicts.

Before you start importing templates back to Billing, double-check to make sure that all templates were properly corrected and that they do not contain errors.

This command does the following:

Imports updated templates back to Billing.
Runs the synchronization between Billing and online stores.

How to update templates manually

Go to the directory that contains the patched layout templates:
# cd ./output
# cd ./store-<StoreID> - where StoreID is the unique ID of the online store that you want to edit.
Note: You can learn the path to the directory with online store templates in the utility's output. Locate the following lines:
```
   The location of the patched layout templates:
   /usr/local/pem/share/online-store-templates/output/store-1
```
For all customized templates that were not updated by the utility automatically, special files with the extensions.tpl.yours and .tpl.latest-release will be created:
- .tpl.yours - Your layout templates that were exported from Billing before updating.
- .tpl.latest-release - The original templates delivered with the latest release by CloudBlue without your customizations.
Note: These files are created for technical reasons. They will not be imported to Billing.
Important: Do not delete or modify these files. They are needed for the proper operation of the utility.
Locate the templates with the .tpl extension that contain conflicts and try resolving them. A file conflict occurs when two or more developers have changed the same few lines of a file. To resolve conflicts, you can use any text editor to manually edit the conflicting lines.
- .tpl - Updated templates delivered with the latest release by CloudBlue that contain your customizations. We recommend that you verify the contents of such templates before importing them back to Billing.
Note: All files with the .tpl extension will be imported back to Billing. For this reason, we recommend that you verify the contents of all templates (including those automatically updated by the utility) before importing them back to Billing.
The conflicting area of a file contains two blocks divided by the markers <<<<<<<, =======, >>>>>>>. The upper block contains the changes delivered in the latest release, and the lower block contains the changes you made to this template, before upgrade.
Example:
```
 <<<<<<<
 the changes delivered in the latest release
 =======
 the changes you made to this template, before upgrade
 >>>>>>>
```
You should decide how the code should look like, make the necessary changes, and save the file. As a result, a file with the resolved conflicts should not contain any conflict markers such as <<<<<<<, =======, >>>>>>>.

If you think that your layout templates that were exported from Billing before updating must remain unchanged in Online Store (such as when your templates contain many customizations and, for this reason, contain many conflicting blocks), you can issue the following command:

cp ./output/store-<StoreID>/<template_name>.tpl.yours ./output/store-<StoreID>/<template_name>.tpl

The template file prepared for uploading to Billing will be replaced with your file.

After resolving all merging conflicts, you can rewrite the existing layout templates in Billing using this command:
./store-templates-assistant --apply-templates --store-id=<StoreID>
Important: Before you start importing templates back to Billing, double-check to make sure that all templates were properly corrected and that they do not contain errors, otherwise the online store might be inoperable.

How to revert the changes

If you imported a store to Billing and encountered errors in the operation of the online store, you can revert changes in layout templates by going to: Billing > Online Store > Layout Templates. Select the templates that you want to revert. You can find all the layout templates that were imported by the store-templates-assistant utility by searching for this description:

Automatically updated to the version ....

Additional command-line options for experts

Additional options necessary for connecting to the billing database

Symptom:

The utility shows the message in the console: The utility could not connect to the billing database because it could not determine the database name, username, or password..

By default, the utility tries to automatically determine all the necessary data to establish a connection to the database, but in some cases, you need to specify such parameters manually, for example, when the database name, user name, or password were changed for security reasons.

The "store-templates-assistant" utility supports additional options for specifying the parameters for connection to the billing database. Add the correct hostname, database name, username, or password using the following options to the command line:

[--bm-db-host=]

Default: Automatically retrieved from the billing application node.

[--bm-db-name=]

Default: pba

[--bm-db-user=]

Default: pba

[--bm-db-password=]

Default: Automatically retrieved from the billing application node.

Examples

# ./store-templates-assistant --prepare-templates --all --bm-db-name=pba_db_name

# ./store-templates-assistant --prepare-templates --all --bm-db-host=127.0.0.1 --bm-db-name=pba_db_name --bm-db-user=pba_db_user --bm-db-password=your_password

Additional options necessary for preparing templates for future releases

Goal:

You can prepare templates before upgrading to a new version. This can help reduce service downtime during upgrade.

If you decide to prepare templates for a new version of CloudBlue Commerce, but you still have the old version of CloudBlue Commerce installed, you can use this additional parameter:

[--target-version=]

Specify the version of Оdin Automation for which templates will be prepared.

Important:

Do not execute the command `--apply-templates`.  If the utility prompts you to automatically import templates into Billing while you are running the` --prepare-templates` command, select the answer `No`.

Example

# ./store-templates-assistant --prepare-templates --all --target-version=7.2.0

After upgrading CloudBlue Commerce to the latest version, you can import the templates that were prepared before the upgrade. To do this, you need to go to the directory with the utility from which you ran the '--prepare-template' command before upgrade and issue the command:

# ./store-templates-assistant --apply-templates --all

Internal content

Link to an internal article