Search Settings Missing in a Baseline 2.1.0+ Installation

[broadleaf-devops]

If you are working with a “Base” installation of the Broadleaf Platform that does NOT include any “Demo Extensions”. For example, if the extensions component in your manifest.yml looks like this:

extensions: [
  ]

instead of something like this:

extensions:
- artifactId: broadleaf-microservices-starter-heatclinic
  groupId: com.broadleafcommerce.microservices
  version: x.x.x-GA

The expectation is for your implementation to pre-seed some data (that is specific to your implementation) similar to how the demo extensions dependencies pre-seed data into the database in support of their specific example flows. This can be done with a combination of custom liquibase scripts and existing framework scripts that are included with certain framework dependencies.

Search Settings SQL Required for Release Train 2.1.0+

Starting with release train 2.1.0, Broadleaf Search Services have added support for application-specific Search Settings. More details on these changes can be found here: Search and Indexer Services - 2.1.0 - Broadleaf Dev Central

The various Demo Extensions Jar’s make use of the migration scripts needed to support search settings based on “seed data” inserted by the sample demo JARs.

If you are running the platform for the first time WITHOUT an extension JAR, you will need to create your own changelogs to invoke these search setting migration scripts yourself (alongside any custom seed data specific to your own implementation).

Apply Search Settings via your own Liquibase Changelog

Almost all Broadleaf implementations manage their own liquibase changelogs to augment and add additional DML or DDL specific changes necessary for their implementation - so one way to “pre-seed” these search setting SQL scripts is to create your own liquibase changelog that references the framework’s Search Settings SQL migration scripts (in addition to any other pre-seeded data necessary for your specific implementation)

Below you will find some examples steps on “pre-seeding” your installation with Search Settings:

1. Create your own Tenant seed data change log file with the following contents. In this example, we’ll call it tenant.mycompany.data.changelog.xml

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-3.8.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd">

    <!--DB Specific Properties -->
    <property name="now" value="(systimestamp - INTERVAL '1' HOUR) at time zone 'UTC'"
        dbms="oracle" />
    <property name="now" value="UTC_TIMESTAMP() - interval 1 hour" dbms="mysql" />
    <property name="now" value="(now() - INTERVAL '1 HOUR') AT TIME ZONE ('UTC')"
        dbms="postgresql" />
    <property name="now" value="(now() - INTERVAL '1 HOUR') AT TIME ZONE ('UTC')"
        dbms="yugabytedb" />
    <property name="now" value="UTC_TIMESTAMP() - interval 1 hour" dbms="mariadb" />

    <!-- RECOMMENDATION -->
    <!-- TODO: create any additional change sets for inserting any "Applications" into blc_tenant_application etc... -->
    <!-- /END RECOMMENDATION -->

    <!-- Apply these Search Settings last as the migration scripts can leverage any prior inserted data and update the settings accordingly -->
    <!-- Search Groups -->
    <changeSet id="search-settings-v3" author="mycompany">
        <!-- These preconditions retroactively disable this changeset's execution on Maria and MySQL,
            where it is known to fail. This was done instead of updating the sqlFile entry's 'dbms' property
            directly to avoid a checksum violation. -->
        <preConditions onFail="MARK_RAN">
            <or>
                <dbms type="oracle" />
                <dbms type="postgresql" />
            </or>
        </preConditions>
        <sqlFile path="db/sql/tenant-search-group-migration.sql"
            dbms="mysql,mariadb,postgresql" />
        <sqlFile path="db/sql/tenant-search-group-migration-oracle.sql" dbms="oracle" />
    </changeSet>
    <!-- Search Groups Timestamp Rectification and MySQL/Maria new migration script -->
    <changeSet id="search-settings-v4" author="mycompany">
        <sqlFile path="db/sql/tenant-search-group-migration-v4-postgresql.sql"
            dbms="postgresql" />
        <sqlFile path="db/sql/tenant-search-group-migration-v4-oracle.sql" dbms="oracle" />
        <!-- This is a net new script for Maria/MySQL that addresses the original intent of 'search-settings-v3'
            with the timestamp concerns addressed. -->
        <sqlFile path="db/sql/tenant-search-group-migration-v4-mysqlmariadb.sql"
            dbms="mysql,mariadb" />
    </changeSet>
</databaseChangeLog>

2. Assuming you are using postgres as your DB, you will have a generated tenant.flex.postgresql.changelog-master.yaml “Master Changelog” file in your project. Note: If you are using a different DB, you will have something like tenant.flex.[db].changelog-master.yaml in your project. This will typically be found in the Flex Package in which the Tenant Microservice exists. In the one flex package it will be under one/src/main/resources/db/changelog. In the balanced flex package it will be under supporting/src/main/resources/db/changelog etc… You can now reference your custom changelog like this:

# This file is generated by the changelog-generation-maven-plugin.
# It is a living document. You may edit, while maintaining its
# dynamic connection to the manifest during standard maven install.
# Disable the dynamic nature by setting
# <skip-flex-changelog>true</skip-flex-changelog> in this module's pom
# properties section. Note, generally drop changelogs should appear last.
databaseChangeLog:
- changeSet:
    id: schema-tenant
    author: broadleaf-changelog-generation-plugin
    changes:
    - sql:
        sql: create schema if not exists "tenant"
- include:
    file: db/changelog/tenant.flexdemo.postgresql.changelog-master.yaml
    author: broadleaf-changelog-generation-plugin
- include:
    file: db/changelog/tenant.starter.required.data.changelog.xml
    author: broadleaf-changelog-generation-plugin
- include:
    file: db/changelog/tenant.postgresql.drop.changelog-1.4.0.xml
    author: broadleaf-changelog-generation-plugin
- include:
    file: db/changelog/tenant.mycompany.data.changelog.xml
    author: custom

3. Create your own Search seed data change log file with the following contents. In this example, we’ll call it search.mycompany.data.changelog.xml

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-3.8.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd">

    <!--DB Specific Properties -->
    <property name="now" value="(systimestamp - INTERVAL '1' HOUR) at time zone 'UTC'"
        dbms="oracle" />
    <property name="now" value="UTC_TIMESTAMP() - interval 1 hour" dbms="mysql" />
    <property name="now" value="(now() - INTERVAL '1 HOUR') AT TIME ZONE ('UTC')"
        dbms="postgresql" />
    <property name="now" value="(now() - INTERVAL '1 HOUR') AT TIME ZONE ('UTC')"
        dbms="yugabytedb" />
    <property name="now" value="UTC_TIMESTAMP() - interval 1 hour" dbms="mariadb" />

    <!-- RECOMMENDATION -->
    <!-- TODO: create any additional change sets for inserting any additional search configuration specific to your implementation here if needed  -->
    <!-- /END RECOMMENDATION -->

    <!-- Apply these Search Settings last as the migration scripts can leverage any prior inserted data and update the settings accordingly -->
    <!-- Search Settings -->
    <changeSet id="search-settings-v4" author="mycompany">
        <sqlFile path="db/sql/search-migration.sql" dbms="mysql,mariadb,postgresql" />
        <sqlFile path="db/sql/search-migration-oracle.sql" dbms="oracle" />
    </changeSet>
</databaseChangeLog>

4. Assuming you are using postgres as your DB, you will have a generated search.flex.postgresql.changelog-master.yaml “Master Changelog” file in your project. Note: If you are using a different DB, you will have something like search.flex.[db].changelog-master.yaml in your project. This will typically be found in the Flex Package in which the Search Microservice exists. In the one flex package it will be under one/src/main/resources/db/changelog. In the balanced flex package it will be under supporting/src/main/resources/db/changelog etc… You can now reference your custom changelog like this:

# This file is generated by the changelog-generation-maven-plugin.
# It is a living document. You may edit, while maintaining its
# dynamic connection to the manifest during standard maven install.
# Disable the dynamic nature by setting
# <skip-flex-changelog>true</skip-flex-changelog> in this module's pom
# properties section. Note, generally drop changelogs should appear last.
databaseChangeLog:
- changeSet:
    id: schema-search
    author: broadleaf-changelog-generation-plugin
    changes:
    - sql:
        sql: create schema if not exists "search"
- include:
    file: db/changelog/search.flexdemo.postgresql.changelog-master.yaml
    author: broadleaf-changelog-generation-plugin
- include:
    file: db/changelog/search.starter.required.data.changelog.xml
    author: broadleaf-changelog-generation-plugin
- include:
    file: db/changelog/search.postgresql.drop.changelog-2.1.0.xml
    author: broadleaf-changelog-generation-plugin
- include:
    file: db/changelog/search.mycompany.data.changelog.xml
    author: custom

As an example, a one flex package project composition may have a directory structure that looks like this:

5. make sure to rebuild your full project. For example, from the manifest directory run ./mvnw clean install -f ../

6. Now, re-run the data module to apply the custom changesets. For example, from the manifest directory run ./mvnw spring-boot:run -f ../data

7. Verify that you are able to view Search Settings in the Admin

What happens if I don’t apply the Search Settings migration scripts?

Without loading the appropriate search migration scripts, you may run into errors in the Admin when viewing search settings. For example:

Because the Product Listing Page is also driven by Search Settings, you may also notice that when adding Product and viewing them on the list grid, they may not be clickable.