See Commerce Studio versus Predictive Merchandiser for a feature comparison.
Prepare for the migration
Complete these client tasks before Lucidworks begins the migration.Prepare Predictive Merchandiser for migration
Prepare Predictive Merchandiser for migration
Determine which rules and rewrites will be migrated
- Unpublished rules or rewrites have never been published.
- Staged rules or rewrites have been published at least once, but then were changed and those changes are not yet published. It also includes rules and rewrites that were deleted, but the deletion has not yet been published.
Unpublished rules
If you want unpublished rules migrated, then inform Lucidworks to setexcludeUnpublishedRules to false during the migration (this is the default). If you do not want unpublished rules to be migrated, tell Lucidworks to set excludeUnpublishedRules to true.Unpublished rewrites
If you want unpublished rewrites migrated, then inform Lucidworks to setexcludeUnpublishedRewrites to false during the migration (this is the default). If you do not want unpublished rules to be migrated, tell Lucidworks to set excludeUnpublishedRewrites to true.Staged rules and rewrites
Staged rules and rewrites are skipped in the migration, so you must publish or revert all staged changes to rules and rewrites.You can only view staged changes in Predictive Merchandiser that belong to your user.To check for staged changes that belong to other users in your organization, do the following:- Copy the
precheck.shscript below to check for staged (unpublished) rules and rewrites:
-
Run the script, replacing the placeholder values with your values.
Placeholder definitions
Placeholder definitions
| Placeholder | Description |
|---|---|
FUSION_USERNAME | Your Fusion username. |
FUSION_PASSWORD | The password for your Fusion user. |
FUSION_BASE_URL | The URL of your Fusion instance including https://. For example, https://FUSION_HOST.com. |
FUSION_APP_ID | The application ID of the Fusion app that contains your Predictive Merchandiser. This is the value of the id field, and may or may not match the name of the Fusion app. To obtain the ID, sign in to your Fusion instance. For example, FUSION_INSTANCE.com. Then also open a different browser window and enter https://FUSION_INSTANCE.com/api/apps. The id and name display for each valid Fusion app. The value in the id field is the value that needs to be used in this field. |
If you receive an error stating
bash: ./precheck.sh: Permission denied: 1. Make the script
executable: chmod +x precheck.sh. 2. Run the script again.-
Check the output to see if any issues were detected. If there are no issues, the output returns
All pre-checks passed. No issues found.Continue to retrieve list of objects in Predictive Merchandiser. If there are issues, the output returns a list of issues like the following: -
Review
precheck_results.jsonand inspect each reported rule. If you created the rules, sign into Predictive Merchandiser and publish or revert the staged changes. If the unpublished rules were created by a different user, you cannot publish or revert the rules in the Predictive Merchandiser UI. There are a few options for resolving unpublished rules owned by another user:- After you complete the pre-migration tasks, tell Lucidworks to proceed with the migration. These rules are skipped and you can re-create them in Commerce Studio.
- Use the Fusion Query Rewrite and Custom Rule APIs to manually publish or revert the unpublished rules.
- Use the Fusion Query Rewrite and Custom Rule APIs, or Solr, to manually change the edit session ID of the content in Solr to your current user. Then, manually fix the content in the Predictive Merchandiser UI.
- Have the user that owns the content in Predictive Merchandiser sign in and either publish or revert the changes.
- After resolving issues, re-run the script. If there are no issues, continue to retrieve list of objects in Predictive Merchandiser.
You can run the precheck.sh script at any time, even after a migration if desired. It makes no
changes to contents and works even if Commerce Studio is enabled.
Retrieve lists of objects in Predictive Merchandiser
Retrieve lists of objects in Predictive Merchandiser
After preparing Predictive Merchandiser for migration, Lucidworks recommends that you export lists of rules, rewrites, templates, and zones from your Predictive Merchandiser instance to compare against Commerce Studio later. This will help serve as a reference when performing your post-migration validation checks.
-
Export a list of your rules and rewrites:
- Create an inventory of your rules, noting how many of each type and tag appear in the list.
-
Export a list of your zones:
-
Export a list of your templates:
Notify Lucidworks the migration can be executed
Notify Lucidworks the migration can be executed
Notify Lucidworks to begin the migration, but keep in mind that once the migration begins, you will no longer be able to access Predictive Merchandiser.Lucidworks will set up the Commerce Studio integration and instance, and migrate your data from Predictive Merchandiser to Commerce Studio.
Do not proceed with subsequent procedures until Lucidworks confirms the migration is successful.
Post-migration tasks
Complete these client tasks when Lucidworks notifies you the migration is complete.Validate migration data
Validate migration data
Lucidworks will run the validation checks in this section, but you must also validate that all Predictive Merchandiser objects appear in Commerce Studio.Because you can no longer access Predictive Merchandiser, you must consult the exported JSON you generated in Retrieve lists of objects in Predictive Merchandiser for validation checks.
- Sign in to Lucidworks Platform as a workspace owner and navigate to Commerce Studio.
- Navigate to Rules, then compare your rule count in Commerce Studio against the JSON you exported from Predictive Merchandiser.
- Navigate to Rewrite, then validate that your query rewrites in Commerce Studio match the exported JSON.
- Navigate to Pages, then validate your templates have become pages in Commerce Studio, and that the count matches the exported JSON.
- Open each page, then validate your Predictive Merchandiser zones have become sections in Commerce Studio, and they are associated with the correct page.
- Navigate to the Editor and check that rules and rewrites are applied as expected. Some rules and rewrites only fire under specific conditions:
- For rules that fire under specific templates, change your page to match the required template.
- For rules that fire only when specific tags are applied, verify the tags are displayed on the Rules page for the rule.
- Perform additional rules and rewrites validations as needed, using the exported rules JSON as a reference. For example, check that the direction of synonym rewrites matches the expected direction.
Revert back to Predictive Merchandiser
If you want to revert back to using Predictive Merchandiser, inform Lucidworks. Then Lucidworks must delete the Commerce Studio instance. If the Commerce Studio instance is deleted, changes you made to Commerce Studio after the initial migration from Predictive Merchandiser are not populated back into Predictive Merchandiser. When the Commerce Studio instance is deleted, the system should automatically revert the Fusion app back to Predictive Merchandiser. This restores access to Predictive Merchandiser and routes live traffic back to its rules and rewrites, if traffic had previously been switched to Commerce Studio.Frequently asked questions
Can I revert back to Predictive Merchandiser after switching to Commerce Studio? Yes. However, any changes made in Commerce Studio after switching will not be reverted back into Predictive Merchandiser. Does switching to Commerce Studio immediately affect live web traffic? No. After a successful migration, web traffic continues to use rules and rewrites from Predictive Merchandiser. What happens if I forget to publish changes in Predictive Merchandiser before migrating? If you fail to publish pending rules and rewrites before starting the migration, the migration may fail or result in incomplete or inaccurate data. All changes must be published before proceeding.Troubleshooting
This section provides troubleshooting steps for resolving issues with the Commerce Studio Editor when integrated with Fusion. Use this guidance to debug unexpected behavior that may be caused by Fusion query pipeline or query profile configuration. This content is intended for users with experience in Fusion and search engineering.Symptoms
You may be experiencing a configuration issue if you observe any of the following:- No results or facets returned in the Editor
- Error messages when performing searches
- Rules not firing or not appearing after creation
- Rewrites not triggering or not affecting live traffic
- Mismatch between facets and results list
- “Targeted documents” column in the rules table is empty or incorrect
- No field value suggestions when configuring rule conditions
- Missing stage data in the Ranking Factors UI
General troubleshooting steps
- Open your browser’s developer tools and go to the Network tab.
- Retry the failing action.
- Look for requests with a non-200 status or check
renderendpoint responses forerrorMessagefields. - Use the
fusionRequestUrlto replicate the request in Fusion Query Workbench.
- Verify that the query pipeline behaves as expected in Fusion Query Workbench.
- Confirm there are no errors.
- Verify expected results are returned.
- In the JSON view, check for
fusion.applicable_rulesorfusion.taggervalues.
- Confirm that rules and rewrites are saved to the correct Solr collections.
- In Solr Admin, check
APP_NAME_query_rewrite_staging_emandAPP_NAME_query_rewrite_em. - Use the rule ID to query and confirm the entry exists.
- In Solr Admin, check
- Ensure the staging collection has only one replica.
- If multiple replicas exist, set
shards.preference=replica.leaderin the Apply Rules and Text Tagger stage parameters.
- If multiple replicas exist, set
- Verify that the pipeline supports the
flparameter.- Do not overwrite
fl. Add required fields only when needed. - Do not use
fl=*.
- Do not overwrite
Required pipeline configuration
Your Fusion query pipeline must include the following stages in this order:- Text Tagger stage with a blank value in the Tagger Collection field
- Apply Rules stage with a blank value in the Collection field
- Solr Query stage
- Modify Response with Rules stage
- Response Diagnostics stage
- Use the
edismaxquery parser (defType=edismax) - Preserve the following query parameters:
tags,lw.rules.simulate,lw.app.emStatus,context,lw.tagger.debug,lw.rules.debug,lw.em.staging - Preserve required response fields:
response.docs,response.numFound,fusion.tagger,fusion.applicable_rules,fusion.applicable_stages,response.facet_counts,responseHeader.params
Feature-specific checks
Targeted document lookup
- The Fusion app and query profile must have the same name.
- The query profile must support
q=**:**and standardfqparameters. - Avoid using grouping, collapse/expand, or custom logic that may interfere with standard filter behavior.
Field value suggestions
- The Solr collection must match the Fusion app name.
- The collection must support the
/termsrequest handler with standard parameters. - Suggestions will fail if
/termsis missing or misconfigured.
Rewrites and rules interaction
- If the Text Tagger stage appears before the Apply Rules stage, rewrites apply first.
- If the Apply Rules stage appears before the Text Tagger stage, only the original terms are used for rule evaluation.
- Rules must target the rewritten query term, not the original term.
Grouping via collapse/expand
-
The query pipeline must set an
fqwith the collapse field specified, indicating what field identifies members of a group. For example, setfq={!collapse field=product_id_s}whenexpand=trueis passed as a query param. -
Set the following query parameters:
-
Relevant response fields include the following:
Query Workbench debugging tips
- Use the correct query profile and associated pipeline.
-
Set the following query parameters:
-
Use View As: JSON to verify
fusion.applicable_rulesand the final query string. -
Use custom JavaScript stages to inspect
ctxor log intermediate values.
Known configuration issues
- Hardcoded
tagsin pipelines may prevent rules from matching if users forget to apply corresponding tags in the Editor. - Query pipelines that use grouping may break document targeting. Only collapse/expand-based grouping is supported. Grouping via Solr
groupparams or blockjoin query parser is not supported. - If a boost stage and a rule both adjust relevancy, only one may take effect, depending on rule priority and creation date.