Skip to main content
This type of Fusion integration lets you connect self-hosted Fusion instances to Lucidworks Commerce Studio. If you want to migrate from Predictive Merchandiser to Commerce Studio, the information in this topic is used in coordination with the procedures described in Migration guide from Predictive Merchandiser to Commerce Studio. You must satisfy the prerequisites and complete all of the procedures in the order described in this topic to implement Lucidworks Commerce Studio:
  1. Create a Commerce Studio integration with Fusion
  2. Create Fusion roles required for Commerce Studio
  3. Create a Fusion security JWT realm for Commerce Studio
  4. Create the lwp service account in the JWT realm
  5. Verify Commerce Studio integration with Fusion
  6. Create a Commerce Studio instance using the UI
This topic is specific to integrating Lucidworks Platform with Fusion for the use of Commerce Studio.

​
Prerequisites

To create an integration, you must have the following prerequisites in place:
  • Admin privileges to a self-hosted Fusion environment running Fusion 5.9.8 or later.
  • A Fusion application that contains usable data.
  • Workspace Owner permissions in a Lucidworks Platform environment.
  • Privileges to access and use Lucidworks Commerce Studio in a Lucidworks platform workspace.
Network access requirements: Lucidworks Platform must be able to reach the Fusion API URL you provide. Your Fusion instance must also be able to reach the Lucidworks JWK endpoint (https://api.lucidworks.com/customers/) to retrieve JSON Web Key Sets during JWT authentication. This endpoint is hosted on a separate IP range from the Lucidworks Platform itself. To obtain the IP ranges to add to your network allowlist, or for help configuring proxy access through the Fusion API gateway, contact Lucidworks support.

​
Create a Commerce Studio integration with Fusion

Complete the following procedures to create an integration from Lucidworks Commerce Studio to Fusion.
  1. Navigate to the megamenu and click Settings > Fusion Integrations.
  2. Click Connect New Fusion.
  3. In the Name field, enter a unique name for the integration. For example, Lucidworks Demo Dev.
  4. In the API URL field, enter the URL of your Fusion instance. For example, https://FUSION_INSTANCE.com. Do not enter a path after .com.
  5. In the Environment field, select the Fusion instance environment or use the default of Development.
  6. Optional: Enter one or more descriptive Tags that differentiate multiple integrations.
    Connect New Fusion integration
  7. Do not enter values in any of the fields in the GitHub section. Values in these fields are only required to set up the Configuration Promotion tool integration with Fusion.
  8. Click Add. Lucidworks Platform sends a GET /api request to your Fusion API gateway to validate the connection. If that request cannot reach your Fusion instance, the integration will not be created. If the value in the API URL field is:
    • Not valid, the integration is not created, and it is not displayed on the Fusion Integrations screen.
    • Valid, the Instructions to Connect with Fusion screen displays:
      Connect with Fusion
  9. Copy both the JWK Set URL value and the Issuer URL value to a secure location. These values must be used to create the JWT realm and are not displayed again after you click Close.
  10. Click Close.
  11. Verify the new integration displays on the Fusion Integrations screen.
To edit the integration, hold the pointer over the integration, click the pencil icon, enter the changes, and click Save. To delete the integration, hold the pointer over the integration and click the trash can icon.

​
Create Fusion roles required for Commerce Studio

  1. Sign in to your Fusion instance as an admin and click the Fusion application to connect with Commerce Studio.
  2. Navigate to System > Access Control > Roles and click Add Role.
  3. In the Name field, enter lwp_user.
  4. In the Permissions field, enter:
    Each permission grants the following access:
    • GET,PUT,DELETE,POST,HEAD:/query/experience-manager/**: Commerce Studio query endpoints (read/write) for Commerce Studio UI and rule management.
    • GET,POST:/query/*: Query execution endpoints (read/write). POST sends query parameters in the request body and does not create or persist any configuration in Fusion.
    • POST:/query/*/preview: Rule preview endpoint (write) to view rule results without publishing them to production.
    • GET,POST,PUT:/query-pipelines/**: Query pipeline configuration (read/write) to manage pipeline stages used by Commerce Studio.
    • GET:/suggestions/**: Autocomplete and typeahead suggestions (read-only).
    • GET:/solr/*/terms: Solr term analysis (read-only) to view field values and vocabulary.
    • PUT,POST,GET:/apps/*/query-pipelines/**: Application-scoped query pipeline management (read/write) to manage app-specific pipeline operations.
    • GET:/apps/*/query-profiles/**: Query profiles (read-only) to view search configuration profiles.
    • GET,PUT:/apps/*: Fusion application settings (read/write) to view and update app metadata.
    • POST:/apps/*/query/**: Run queries (write) against a specified app’s query profile without modifying the app.
    • GET:/solr/*/admin/luke: Solr index schema inspection (read-only) used to view available fields.
    • GET:/solr/**: General Solr read access (read-only).
    Beginning with Fusion 5.9.15, all Commerce Studio integrations must have the POST:/query/*/preview and GET,POST,PUT:/query-pipelines/** permissions assigned to both the lwp_user and lwp_service_account roles in Fusion.
    This role does not require any UI permissions, so you do not have to select any values in the UI Permissions field.
  5. In the Description field, enter role information. For example, “The lwp_user account is required to access and use Commerce Studio. It is a super user account, but does not include the ability to get, modify, or delete the HEAD section of the site.”
  6. Click Save.
  7. Click Add Role.
  8. In the Name field, enter lwp_service_account.
  9. In the Permissions field, enter the following permissions. These permissions include most of the lwp_user account permissions plus the privileges to migrate Fusion Predictive Merchandiser rewrites, rules, templates and zones.
    The lwp_service_account role includes most lwp_user permissions plus the following additional permissions that are required to migrate Predictive Merchandiser to Commerce Studio:
    • GET,DELETE,PATCH,PUT,POST,HEAD:/apps/*/query-rewrite/**: Query rewrite rules (read/write) to migrate Predictive Merchandiser rewrites, rules, and zones to Commerce Studio.
    • GET,HEAD:/templating/**: Templating access (read-only) to access Predictive Merchandiser templates during migration.
    Beginning with Fusion 5.9.15, all Commerce Studio integrations must have the POST:/query/*/preview and GET,POST,PUT:/query-pipelines/** permissions assigned to both the lwp_user and lwp_service_account roles in Fusion.
    This role does not require any UI permissions, so you do not have to select any values in the UI Permissions field.
  10. In the Description field, enter role information. For example, “The lwp_service_account contains most of the lwp_user permissions as well as the privileges to migrate Fusion Predictive Merchandiser components to Lucidworks Commerce Studio.”
  11. Click Save.
The PUT,POST,GET:/apps/*/query-pipelines/** permission reflects the requirement to assign all necessary query pipeline permissions to the lwp_user and lwp_service_account roles. An additional example is for configuring a Lucidworks AI Gateway integration, where you need to assign POST:/your-account-name/.

​
Create a Fusion security JWT realm for Commerce Studio

  1. Sign in to your Fusion instance as an admin and click the application in which you created the lwp_user and lwp_service_account accounts to use with Commerce Studio.
  2. Navigate to System > Access Control > Security Realms and click Add Security Realm.
  3. In the Name field, enter a unique connection name. For example, Lucidworks Commerce Studio JWT realm.
  4. In the Type field, select jwt.
  5. Set the checkboxes in the following configuration.
    • Select the Enabled checkbox.
    • Do not select the Ephemeral Users checkbox.
    • Select the Auto-Create Users checkbox.
  6. In the Roles field, select lwp_user.
  7. In the JWT Issuer field, paste the Issuer URL value generated in the Create a Commerce Studio integration with Fusion procedure.
  8. In the JWK Set URL field, paste the JWKS URL value generated in the Create a Commerce Studio integration with Fusion procedure.
  9. In the JWK Set Timeout field, enter a timeout value in milliseconds for retrieving the JWKS.
    • This field is required.
    • Minimum value: 500 ms (set higher for known network latency).
  10. Do not enter values (default is blank) in any of the following fields:
  • Signing Key
  • Groups Key
  • Groups Mapping
  • User ID Attribute
  1. Click Save.
Self-hosted Fusion clients can also view the integration ID, Issuer URL, JWKS URL, and other integration details in Settings > Fusion Integrations when the existing integration is selected. For general information, see Lucidworks Platform integration with Fusion. Integrations for Lucidworks Search clients are created and updated by Lucidworks.

​
Create the lwp service account in the JWT realm

  1. Sign in to your Fusion instance as an admin and click the application to be connected with Commerce Studio.
  2. Navigate to System > Access Control > Users and click Add User.
  3. In the Realm field, select the JWT realm you created in the Create a Fusion security JWT realm for Commerce Studio.
  4. In the Username field, enter lwp-service-account.
  5. In the Roles field, select the lwp_service_account role.
  6. In the Timezone field, select the appropriate timezone for the user account.
  7. Click Create.

​
Verify Commerce Studio integration with Fusion

When the Fusion security JWT realm is created, complete the following steps to verify the Fusion information is displayed.
  1. Navigate to the megamenu and click Settings > Fusion Integrations.
  2. Hold the pointer over the integration and click the pencil icon.
  3. Verify the information is accurate.
    The information in the Instructions section must match the values in the Additional URLs JWKS URL and Issuer URL fields.

​
Create a Commerce Studio instance using the UI

Do not create a Commerce Studio instance using the UI if you are migrating data from Predictive Merchandiser into that Commerce Studio instance. Instead, you must create the instance using the API.
  1. In Lucidworks Platform, navigate to Commerce Studio and click Create New.
  2. In the Name field, enter a unique name for the Commerce Studio instance.
  3. In the Region field, select the geographic region for the Commerce Studio instance. This cannot be changed after the instance is created.
  4. In the Fusion to Connect field, select the Fusion integration instance that matches the Name field created in the Create a Commerce Studio integration with Fusion procedure.
  5. Optional: In the Signal Store field, select the location where the Commerce Studio signals are stored. This value is only required if you want to use Lucidworks Analytics.
  6. In the Fusion Application field, enter Lucidworks Platform application that connects to your Fusion instance.
  7. Click Next to confirm settings, and then Next to create the instance.
Data from the Fusion app is sent to Commerce Studio so you can create rules and refine the search experience. You can only connect one instance of Commerce Studio to a Fusion app. You cannot create multiple instances of Commerce Studio using the same Fusion app.

​
Troubleshooting

These errors may occur when Commerce Studio communicates with Fusion. When an error response includes a fusionErrorMessage field, use the message contents to identify the cause.
The Commerce Studio instance status in Fusion may have been removed or disabled. Manually set the status back to READY (if in preview mode) or CONNECTED (if already live).
The JWT security realm used by Commerce Studio is not configured correctly. Verify that the JWT realm is configured as described in Create a Fusion security JWT realm for Commerce Studio.If the realm configuration is correct, an expired JWT may be reaching Fusion. Contact Lucidworks support.
In some network environments, a JWT realm misconfiguration, particularly when Fusion cannot reach the JWKS endpoint, can surface as a 500 error rather than a 401 or 403. If you are investigating a 500 error and cluster health appears normal, also check the JWT realm configuration and network egress to the JWKS endpoint.
This typically indicates a problem with the Fusion instance itself. Check the details of the returned error response to determine the cause:
  • “Could not find a healthy node” — The Fusion cluster cannot reach a healthy Solr node. Contact your Fusion instance administrator or Lucidworks support.
  • “Connection reset”, “interrupted”, or “timed out” — The Fusion cluster may be overloaded or have a configuration issue causing slow responses. Contact your Fusion instance administrator.
  • JWT realm / JWKS endpoint unreachable — If Fusion cannot reach the Lucidworks JWKS endpoint, for example, due to a firewall or proxy blocking egress, it fails to retrieve JWT signing keys and may return a 500 to Commerce Studio instead of a 401 or 403. Check egress rules, proxy configuration, and the JWT realm setup even when the error is a 500. See network access requirements and the JWT realm configuration steps.