Migrating data protection rules

Last updated: Jul 25, 2024

Use API calls to export and import data protection rules within a Cloud Pak for Data as a Service cluster or between different clusters.

You can export and import data protection rules with APIs to export data protection rules from any system and import the rules into the same or different system. Links are maintained to glossary artifacts, catalogs, assets, and users. This task is also handy for backing up and restoring your data protection rules on the same or different system.

Prerequisites

Required permission
Before you begin
Limitations

Migrating data protection rules by using API

Export
Import

Prerequisites

Required permission

To complete this task, you must be an administrator of the project (namespace) where you deployed the IBM Knowledge Catalog service.

Before you begin

All artifacts, users, user groups, user roles, and assets that are used in rules must be imported correctly to the target system before the exported rules are imported.
To avoid any errors and changes to the enforcement behavior, you must verify that the Manage rule settings between the source and target systems are configured the same.
Before you import a rule, verify whether you have custom predicates in the exported rules. If so, you must create these custom predicates in the target system before you can import.

Limitations

The unmasked original data can persist in temporary storage for the following scenarios:

A cache of data to display in the Example data section when a data protection rule is created or edit.
A masked copy of the data in Cloud Object Storage for rapid recall of the masked data.
A profile data might not store the entire data but store an aggregation of the data, which can include values that are found in the data.

Migrating data protection rules by using API

Export

To export from one installation to another, set external_export to true by running the following API:

curl -k -X GET -H 'Content-Type: application/json' -H "Authorization:Bearer $token" '$url/v3/enforcement/rules/export?external_export=true'

An exported_file.json file is generated that can be used for import.

Import

Before you import between different installations, generate a report of all rules that succeed or fail in matching names to IDs in the target system. By running the following API that sets the commit parameter to false:

curl -k -X POST -H 'Content-Type: application/octet-stream' -H "Authorization:Bearer $token" '$url/v3/enforcement/rules/import?external_import=true&commit=false' -d "@./exported_file.json"

Before you commit the rules, use the following report to identify any rules that fails to match IDs in the target system. When you run the import with external_import set to true, no rules are created and committed when the commit parameter is set to false:

{
  "failedList": [
    {
      "name": "export name4",
      "index": 4,
      "ruleGuidInRequest": "abcd123e-123b-1ab2-a123-ab123456c7d1",
      "reason": "WDPPS9040E: Import rules failed to match export component ids: [id=123a4b56-1a23-1234-a1bc-12a3b45cd6ef_123a4b56-1a23-1a23-1a23-12ab345cd67e]"
    }
  ],
  "matchedList": [
    {
      "name": "export name1",
      "index": 1,
      "ruleGuidInRequest": "12abc456-1234-12a3-a1bc-a1abc2345abc"
    },
    {
      "name": "export name2",
      "index": 2,
      "ruleGuidInRequest": "123456a7-1abc-1a2b-a1bc-ab1cd234ef56"
    },
    {
      "name": "export name3",
      "index": 3,
      "ruleGuidInRequest": "a123bcd4-a1b2-1234-1234-a1234567b123"
    }
  ]
}

Run the following API to set the commit parameter to true, such that all or none of the rules can be committed. If one of the rules fails, the whole import fails:

curl -k -X POST -H 'Content-Type: application/octet-stream' -H "Authorization:Bearer $token" '$url/v3/enforcement/rules/import?external_import=true&commit=true' -d "@./exported_file.json"

A sample response when importing the export package (exported_file.json file) is successful:

SUCCEEDED
{
  "importedList": [
    {
      "name": "export name1",
      "index": 1,
      "guid": "a1b2cd3e-4567-8f90-gh12-345i6jklm78n",
      "ruleGuidInRequest": "12abc345-6789-01d2-e3fg-h4ijk5678lmn"
    },
    {
      "name": "export name2",
      "index": 2,
      "guid": "12a234b5-c678-90d1-ef2g-34567h8i9012",
      "ruleGuidInRequest": "123456a7-8bcd-9e0f-g1hi-jk2lm345no67"
    },
    {
      "name": "export name3",
      "index": 3,
      "guid": "1a234b5c-d6e7-89f0-1234-5g6hi7j8901k",
      "ruleGuidInRequest": "aa123bcd4-e5f6-7890-1234-g5678901h234"
    },
    {
      "name": "export name4",
      "index": 4,
      "guid": "12a345bc-6789-0d12-3ef4-g5h6ijk789lm",
      "ruleGuidInRequest": "abcd123e-456f-7gh8-i901-jk234567l8m9"
    }
  ]
}

A sample response of when importing the export package (exported_file.json file) fails:

FAILED
{
  "trace": "a1bc2d3e4fg5h6ijklmn7o9pq",
  "errors": [
    {
      "code": "WDPPS9043E",
      "message": "WDPPS9043E: Import rules failed: {\"failedList\":[{\"name\":\"export name4\",\"index\":4,\"ruleGuidInRequest\":\"abcd123e-123b-1ab2-a123-ab123456c7d1\",\"reason\":\"WDPPS9040E: Import rules failed to match export component ids: [id=123a4b56-7c89-0123-d4ef-56g7h89ij0kl_123m4n56-7o89-0p12-3q45-67rs890tu12v]\"}]}"
    }
  ]
}

Parent topic: Managing IBM Knowledge Catalog