API calls for managing classifiers

Classifier instances define logic used by the ASDD profiler to identify sensitive information. Refer to Discovering your sensitive data for an overview of classifiers and related concepts. Each classifier instance is based on a classifier framework that implements the recognition logic. An overview of the available frameworks is available under the classifier concept section. More information about managing classifiers can be found in the Managing classifiers article.

Creating or modifying profile sets can also be done via the API and requires only two API calls See ASDD profile set import and export for usage instructions.

In order to manage classifiers using the API client, you should have some familiarity with REST APIs and JSON data encoding. Access the API Client, as described in the Masking API client section, and authenticate by pressing the Authorize button at the upper right part of the screen. Locate the API paths related to classifiers:

Each of these API path's purposes are as expected based on the operation; GET to view the configuration of existing classifiers, PUT to modify the configuration of an existing classifier, POST to create a new classifier, and DELETE to delete a classifier.

Retrieving classifier framework configurations

The classifiers/frameworks paths allow retrieval of information about the available classifier frameworks. In particular, making a request to these endpoints with include_schema=true will return open API style descriptions of the schema for the classifier frameworks. It is also necessary to use this API to map classifier framework type names, such as 'PATH' or 'REGEX', to the numeric frameworkId when creating classifier instances.

When creating a new classifier, it can be helpful to first perform a GET operation that retrieves the configuration of an existing classifier instance, using the intended framework as a starting point.

Example: Creating a new PATH classifier

In this example, a database contains some columns named snack_pref1, snack_pref2, etc. The columns contain sensitive user data that should be masked, thus, a good regex for recognizing these columns would be snack_pref[0-9]+. A SNACK_PREF domain has been created with an appropriate algorithm for this type of data. To match the column name to profile, the type of classifier needed is PATH.

First, perform a GET operation on the classifiers/frameworks path. In the output below, the respective frameworkId of the PATH classifier is 3.

CODE

{
  "_pageInfo": {
    "numberOnPage": 4,
    "total": 4
  },
  "responseList": [
    {
      "frameworkId": 1,
      "frameworkName": "REGEX",
      "description": "The regex framework can be used to specify one or more regular expressions to match the data in a field."
    },
    {
      "frameworkId": 2,
      "frameworkName": "LIST",
      "description": "The list framework can be used to specify one or more value lists to match the data in a field."
    },
    {
      "frameworkId": 3,
      "frameworkName": "PATH",
      "description": "The path framework can be used to specify exact values or regular expressions to match the name of a field."
    },
    {
      "frameworkId": 4,
      "frameworkName": "TYPE",
      "description": "The type framework can be used to specify valid types and type lengths for fields to rule out invalid data types and lengths during classification."
    }
  ]
}

After determining that classifier 1 has frameworkId=3, perform the GET operation on classifiers/1:

CODE

{
  "classifierId": 1,
  "classifierName": "Account Number - Path",
  "frameworkId": 3,
  "domainName": "ACCOUNT_NO",
  "createdBy": "System",
  "builtIn": true,
  "classifierConfiguration": {
    "paths": [
      {
        "matchType": "REGEX",
        "fieldValue": "(?i)(?>(account|accnt|acct)_?-? ?(number|num|nbr|no|user))$",
        "parentValue": "",
        "caseSensitive": false,
        "matchStrength": 0.67,
        "allowPartialMatch": true
      }
    ],
    "rejectStrength": 0
  }
}

To exemplify, this configuration is edited, replacing several configuration values to create a new classifier:

CODE

{
  "classifierName": "Snack Preference - Path",
  "frameworkId": 3,
  "domainName": "SNACK_PREF",
  "classifierConfiguration": {
    "paths": [
      {
        "matchType": "REGEX",
        "fieldValue": "snack_pref[0-9]+",
        "parentValue": "",
        "caseSensitive": false,
        "matchStrength": 0.67,
        "allowPartialMatch": false
      }
    ],
    "rejectStrength": 0
  }
}

This body can then be used with a POST operation to the classifiers path to create the new classifier. The API response will include the newly assigned classifierId.

LIST type classifiers

Note that LIST type classifiers require one or more input files to define the value lists for recognition. These files must first be uploaded by doing a POST to the fileUpload API endpoint. The resulting fileReferenceId values may then be used for fields of type FILE in the classifier configuration when creating the classifier.

Downloading files associated with classifiers

Using the classifiers/{classifierId}/export-files endpoint, files associated with classifiers can be downloaded by specifying the classifierId. This endpoint will return an async task similar to the following:

CODE

{
  "asyncTaskId": 2,
  "operation": "EXPORT_CLASSIFIER_FILES",
  "reference": "EXPORT_CLASSIFIER_FILES-Y2xhc3NpZmllcl80NV92YWx1ZV9saXN0cy56aXA=",
  "status": "RUNNING",
  "startTime": "2023-03-21T18:45:59.390+00:00",
  "cancellable": false
}

You can check the status of this task by using the

asyncTask/{asyncTaskId} endpoint.

CODE

{
  "asyncTaskId": 2,
  "operation": "EXPORT_CLASSIFIER_FILES",
  "reference": "EXPORT_CLASSIFIER_FILES-Y2xhc3NpZmllcl80NV92YWx1ZV9saXN0cy56aXA=",
  "status": "SUCCEEDED",
  "startTime": "2023-03-21T18:45:59.390+00:00",
  "endTime": "2023-03-21T18:45:59.520+00:00",
  "cancellable": false
}

Once this task has succeeded, the fileDownload/{fileDownloadId} endpoint can be used to download the files where fileDownloadId is the reference provided in the classifiers/{classifierId}/export-files API response. The files are returned in a .zip that contains all files associated with the specified classifier.

Searching and Filtering Classifiers

The classifiers/search endpoint allows for searching and filtering of classifiers. More information on syntax can be found at API calls for searching and filtering.