Product Selector

Fusion 5.12
    Fusion 5.12

    Keep Rules Consistent Between Clusters

    This article teaches you how to keep business rules consistent between clusters. Use a PUT API call to the Query Rewrite API’s /query-rewrite/instances endpoint for bulk operations. The JSON payload sent with the PUT call must adhere to the following format:

    {
"create": [<object array>],
"update": [<object array>],
"delete": [<item array>]
}

    • create. If the rule does not exist, create it.

    • update. If the rule exists, update it to use the latest values.

    • delete. If the rule exists, delete it.

    Fusion generates a unique id value for every rule. The API operations use this value as a reference point.

    The instructions in the sections below use these example values:

    Parameter Value

    Development cluster

    Address

    https://EXAMPLE_COMPANY_PROD.b.lucidworks.cloud

    Username

    DEV_USER

    Password

    DEV_PASSWORD

    App name

    DEV_APP_NAME

    Production cluster

    Address

    https://EXAMPLE_COMPANY_PROD.b.lucidworks.cloud

    Username

    PROD_USER

    Password

    PROD_PASSWORD

    App name

    PROD_APP_NAME

    When you use the API to conduct bulk rules operations, you must publish the changes in the UI.

    1. Log into Fusion with the same user credentials that you used to make the bulk API rules operations.

    2. Navigate to Relevance > Rules to access the rules editor.

    3. Click the Publish button.

    Export rules

    In these examples, you’ll export rules from an app on a development cluster. This is useful if you have a large number of rule changes you need to port from a development cluster to a production cluster.

    All rules

    Export all rules from the development cluster by sending a GET API call to the /query-rewrite/instances endpoint:

    curl -X 'GET' \
  -u DEV_USER:DEV_PASSWORD \
  'https://EXAMPLE_COMPANY_PROD.b.lucidworks.cloud/api/apps/DEV_APP_NAME/query-rewrite/instances' \
  -H 'accept: application/json' \
  > exported-rules.json

    This outputs your rules to a new JSON file, exported-rules.json. The result resembles the following:

    [{
        "type": "pinned",
        "id": "NqYec4R7pG",
        "name": "Featured - Managed Fusion",
        "createdOn": "2021-06-21T17:28:19.800Z",
        "updatedOn": "2021-06-21T17:28:19.800Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    }, {
        "type": "pinned",
        "id": "uEvL1NBXba",
        "name": "Featured - Managed fusion",
        "createdOn": "2021-06-21T17:29:59.863Z",
        "updatedOn": "2021-06-21T17:29:59.863Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    }]

    Specific rules

    You can specify which rules you want to export by adding parameters to the API endpoint. For example, if you want to export synonym rules only, send a GET API call to /query-rewrite/instances?type=synonym. If you want to export a list of rules that are disabled, use /query-rewrite/instances?enabled=false.

    Use the same GET API call, but change the endpoint:

    curl -X 'GET' \
  -u DEV_USER:DEV_PASSWORD \
  'https://EXAMPLE_COMPANY_PROD.b.lucidworks.cloud/api/apps/DEV_APP_NAME/query-rewrite/instances?type=synonym' \
  -H 'accept: application/json' \
  > exported-rules.json

    Use create

    In this example, you’ll recreate the rules from your development cluster on your production cluster.

    1. Manually reformat the JSON so it uses the following format:

      {
"create": [<object array>]
}

      We are recreating the development cluster’s rules on the production cluster, so we can use create only. Replace [<object array>] with the contents of exported-rules.json. For example:

      {
  "create": [{
        "type": "pinned",
        "id": "NqYec4R7pG",
        "name": "Featured - Managed Fusion",
        "createdOn": "2021-06-21T17:28:19.800Z",
        "updatedOn": "2021-06-21T17:28:19.800Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    }, {
        "type": "pinned",
        "id": "uEvL1NBXba",
        "name": "Featured - Managed Fusion",
        "createdOn": "2021-06-21T17:29:59.863Z",
        "updatedOn": "2021-06-21T17:29:59.863Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    },
    ...
  ]}

    2. Save the file.

    3. Send a PUT API call to the /query-rewrite/instances endpoint to recreate the rules from the development cluster on the production cluster:

      curl -X 'PUT' \
  -u PROD_USER:PROD_PASSWORD \
  'https://EXAMPLE_COMPANY_DEV.b.lucidworks.cloud/api/apps/PROD_APP_NAME/query-rewrite/instances' \
  -H 'accept: application/octet-stream' \
  -H 'Content-Type: application/json' \
  -d @exported-rules.json
      You may have to specify the absolute path to your rules JSON file. For example, -d @/Users/johndoe/exported-rules.json.

    4. Verify that the PUT API was successful by checking the Fusion UI or fetching the rules with the API.

    Use update

    1. Manually reformat the JSON so it uses the following format:

      {
"update": [<object array>]
}

      Replace [<object array>] with the contents of exported-rules.json. For example:

      {
  "update": [{
        "type": "pinned",
        "id": "NqYec4R7pG",
        "name": "Featured - Managed",
        "createdOn": "2021-06-21T17:28:19.800Z",
        "updatedOn": "2021-06-21T17:28:19.800Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    }, {
        "type": "pinned",
        "id": "uEvL1NBXba",
        "name": "Featured - Managed Fusion",
        "createdOn": "2021-06-21T17:29:59.863Z",
        "updatedOn": "2021-06-21T17:29:59.863Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    },
    ...
  ]}

    2. Save the file.

    3. Send a PUT API call to the /query-rewrite/instances endpoint to update the production cluster with the rules from the development cluster:

      curl -X 'PUT' \
  -u PROD_USER:PROD_PASSWORD \
  'https://EXAMPLE_COMPANY_DEV.b.lucidworks.cloud/api/apps/PROD_APP_NAME/query-rewrite/instances' \
  -H 'accept: application/octet-stream' \
  -H 'Content-Type: application/json' \
  -d @exported-rules.json

    Use delete

    In some cases, you may want to delete rules in bulk. For example, if you created rules using the steps above but decide you want to undo that action.

    The delete bulk operation uses a different format than create and update. Instead of passing the entire rules JSON as an object array, you must pass the rule id values as an item array.

    1. Manually reformat the JSON so it uses the following format:

      {
"delete": [<item array>]
}

      Replace <item array> with the id values of the rules you want to delete. These values must be comma separated and wrapped in double quotes ("). For example:

      {
  "delete": ["NqYec4R7pG", "uEvL1NBXba", ... ]}

    2. Save the file.

    3. Send a PUT API call to the /query-rewrite/instances endpoint to update the production cluster with the rules from the development cluster:

      curl -X 'PUT' \
  -u PROD_USER:PROD_PASSWORD \
  'https://EXAMPLE_COMPANY_DEV.b.lucidworks.cloud/api/apps/PROD_APP_NAME/query-rewrite/instances' \
  -H 'accept: application/octet-stream' \
  -H 'Content-Type: application/json' \
  -d @exported-rules.json

    Use create with update

    You may want to determine which rules to include in the create array and which to include in the update array, but it can be difficult to determine which rules already exist. Fortunately, the operations don’t conflict:

    • create. If the rule does not exist, create it.

    • update. If the rule exists, update it to use the latest values.

    There’s no need to separate the rules. You can replace [<object array>] for create and update with the same rules JSON to create the missing rules and update the existing rules.

    1. Manually reformat the JSON so it uses the following format:

      {
"create": [<object array>],
"update": [<object array>]
}

      Replace [<object array>] with the contents of exported-rules.json. For example:

      {
  "create": [{
        "type": "pinned",
        "id": "NqYec4R7pG",
        "name": "Featured - Managed Fusion",
        "createdOn": "2021-06-21T17:28:19.800Z",
        "updatedOn": "2021-06-21T17:28:19.800Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    }
    ...
  ],
  "update": [{
        "type": "pinned",
        "id": "NqYec4R7pG",
        "name": "Featured - Managed Fusion",
        "createdOn": "2021-06-21T17:28:19.800Z",
        "updatedOn": "2021-06-21T17:28:19.800Z",
        "enabled": true,
        "matching": "keywords",
        "priority": 1,
        "search_terms": ["*:*"],
        ...
    }
    ...
  ]
}

    2. Save the file.

    3. Send a PUT API call to the /query-rewrite/instances endpoint to update the production cluster with the rules from the development cluster:

      curl -X 'PUT' \
  -u PROD_USER:PROD_PASSWORD \
  'https://EXAMPLE_COMPANY_DEV.b.lucidworks.cloud/api/apps/PROD_APP_NAME/query-rewrite/instances' \
  -H 'accept: application/octet-stream' \
  -H 'Content-Type: application/json' \
  -d @exported-rules.json