Modifying Schema and Catalog Data

Schema Modifications

1. In the extensions/database/ext-data/src/main/resources/schema module, open the schema-customizations-changelog.xml file.

2. Add one or more change sets to schema-customizations-changelog.xml with the desired changes.

   For details on the possible database modifications you can make using change sets, see Liquibase Changeset.

3. Run the Data Population tool to update the database.

warning

Liquibase will fail if a previously processed changset is modified. Modifying changesets in development will force other developers to rebuild their database.

Once a changeset has been published to production, it must never be modified. Instead, commit additional changesets to counteract your change.

Data Modifications

When you’re working on the initial implementation of a project, the catalog data you create will usually be used for testing or for deployment to all environments.

All data should be added to the extensions/database/ext-data/src/main/resources/data/ directory. Test data should be added to the /test-data subdirectory. Data for all environments should be added to the /rel-1.0-data subdirectory.

The easiest ways to create catalog data are as follows:

• Use Commerce Manager to configure the catalog and export the changes using the Import/Export tool
• Manually create the Import/Export XML files using the data in the commerce-data module as examples

Then run the Data Population tool to update the database.

Re-running Import/Export change sets

Unlike Liquibase changes sets which only process once, Import/Export change sets process every time the Data Population tool runs in your local development environment.

For more information, see Data Population - Filtering Data

Setting Definitions

Setting definitions are a special case, in that they can be added through Import/Export (see System Configuration). However, since they are required for the platform to operate properly, it often makes more sense to add them as part of a Liquibase changeset rather than an Import/Export file.

Adding setting definitions through Liquibase changesets can be tricky, since we need to deal with multiple tables TSETTINGDEFINITION, TSETTINGMETADATA, and TSETTINGVALUE, and we need to find an unused UIDPK value for each setting.

To address this, we now support a Liquibase custom change class for creating setting definitions and setting values.

To create a new setting definition, your Liquibase changeset should invoke the liquibase.ext.elasticpath.CreateSettingDefinition custom change class with the following properties:

• path: The setting definition path.
• valueType: The value data type. Supports these values:
  • BigDecimal
  • Boolean
  • Integer
  • Collection
  • Map
  • String
  • url
  • xml
• maxOverrideValues: The maximum number of values that this setting definition can have. -1 means unlimited, 0 means no values (aside from the default), 1 means one value.
• defaultValue: The default value that this setting has if no explicit values are set.
• refreshStrategy: The strategy to use for caching the setting. application means the setting is cached on first use and never refreshed. interval:timeout={CACHE_SETTING_DEFINITION} means to cache with a time-to-live in milliseconds specified by the value in the CACHE_SETTING_DEFINITION setting definition.
• environmentSpecific: A boolean value indicating if the setting is expected to differ between stores. This usually means that the context of the value refers to the store code it applies to.

Example:

<customChange class="liquibase.ext.elasticpath.CreateSettingDefinition">
    <param name="path" value="COMMERCE/SYSTEM/ORDERCLEANUP/enable"/>
    <param name="valueType" value="Boolean"/>
    <param name="maxOverrideValues" value="1"/>
    <param name="defaultValue" value="false"/>
    <param name="description" value="This setting controls whether the order cleanup job should run."/>
    <param name="refreshStrategy" value="interval:timeout=COMMERCE/Cache/Cache_1"/>
    <param name="environmentSpecific" value="false"/>
</customChange>

To create a new setting value, your Liquibase changeset should invoke the liquibase.ext.elasticpath.CreateSettingValue custom change class with the following properties:

• path: The setting definition path.
• context: The context of the setting value. This is like the key for a map collection, and it's value depends on the use case.
• contextValue: The value of the setting.

Example:

<customChange class="liquibase.ext.elasticpath.CreateSettingValue">
    <param name="path" value="COMMERCE/SYSTEM/ORDERCLEANUP/enable"/>
    <param name="context" value="mobee"/>
    <param name="contextValue" value="true"/>
</customChange>