Skip to content

Using an Algorithm Framework

When a plugin algorithm supports configuration, it is possible to create new instances of the algorithm on the Delphix Masking Engine by specifying the desired configuration. This is done using the engine's Masking Web API. Configurable algorithms may also be tested using the maskApp and maskScript utilities, by providing the desired configuration in an input file or at the command line.

Creating New Algorithm Instances Using the maskApp SDK Utility

When the maskApp utility's mask command is invoked and a configurable algorithm is selected, the option will be presented to create a new algorithm instance. This is done by choosing "::Create New Instance::". The algorithm's configuration schema is displayed, and then a valid JSON input must be provided to create the new instances. Rather than entering the literal JSON, the '@' symbol may be used to load the JSON from a file (@file-path).

What follows is an example of loading the Sample Algorithm plugin, creating a new instance of the StringRedaction framework and masking test values with the new algorithm instance.

$ maskApp
... Startup Messages ...
MASKING-APP:> mask -j algorithm/build/libs/algorithm.jar
/Users/jleser/ws/algorithm-sdk/algorithm/build/libs/algorithm.jar
Loaded plugin Delphix Sample version 1.0.0 dea904c (API version: 1.0.0) from [/Users/jleser/ws/algorithm-sdk/algorithm/build/libs/algorithm.jar]
16:44:47.743 [main] INFO  global - Loaded plugin Delphix Sample: Plugin {'embeddedName': 'Delphix Sample', 'version': '1.0.0 dea904c', 'author': 'Delphix', 'apiVersion': '1.0.0'}
Framework: 
* [0] Byte Array Redaction 
  [1] Date Redaction
  [2] Number Redaction
  [3] Numeric Mapping
  [4] Randomized Masking
  [5] RedactionFile
  [6] StringHashedLookup
  [7] StringRedaction
Select an algorithm framework: 7
Instance: 
* [0] Delphix Sample:Redaction X 
  [1] Delphix Sample:Redaction Y
  [2] Delphix Sample:Redaction Z
  [3] ::Create New Instance::
Select an instance of algorithm framework: StringRedaction: 3
The JSON schema of the selected framework is:
{
  "type" : "object",
  "id" : "urn:jsonschema:sample:masking:algorithm:redaction:StringRedaction",
  "properties" : {
    "redactionCharacter" : {
      "type" : "string",
      "required" : true
    }
  }
}
Enter config(Prefix with '@' for file location)(Blank for no config): { "redactionCharacter" : "+" }
Enter instance name: RedactPlus
Algorithm Configuration: {"redactionCharacter":"+"}
Selected algorithm: sample.masking.algorithm.redaction.StringRedaction(StringRedaction) instance: RedactPlus, data type: STRING
Input value to be masked('null' for null, 'doneMasking' to finish): Test
Masked value: ++++
Input value to be masked('null' for null, 'doneMasking' to finish): One
Masked value: +++
Input value to be masked('null' for null, 'doneMasking' to finish): TwoThree
Masked value: ++++++++

Creating New Algorithm Instances on the Delphix Masking Engine

New instances of plugin frameworks may be created using the Delphix Masking Engine's Web API's algorithm endpoint. This is similar to creating any other algorithm using the algorithm API endpoint and may be performed using the API client. Unlike when an algorithm is created using older, built-in frameworks like Secure Lookup:

  • The value for algorithmType in the JSON request is always "COMPONENT". This is now the default value, so this field may be omitted.
  • A value for the field frameworkId must be included - this is the integer ID of the framework as provided in the plugin description retrievable using the GET operation on the plugin endpoint, or GET on the algorithm/frameworks endpoint.
  • The algorithmExtension field's contents are used directly as the JSON configuration for the algorithm instance. Unlike other algorithm types, this field does not have a fixed schema for COMPONENT type algorithms. The required schema may be retrieved using the procedure described below.

This example API request, POSTed to the algorithm endpoint, creates a new instance of the StringRedaction algorithm (described above), named "RedactStar" using '*' as the redaction character. In this case, the sample algorithm plugin JAR has already been uploaded, and the StringRedaction framework has id 19:

{
  "algorithmName": "RedactStar",
  "algorithmType": "COMPONENT",
  "description": "Redact with the star character",
  "frameworkId" : 19,
  "algorithmExtension" : {
    "redactionCharacter": "*"
  }
}

Discovering the algorithmExtension API Field Schema

The Masking Web API algorithm/framework endpoint has the ability to show the JSON Schema for each algorithm framework implemented using the extensibility mechanism. By default, the schema is not included, but by setting include_schema true, the schema may be retrieved. Here is the GET API result, including schema, for the StringRedaction framework used above:

{
  "frameworkId": 19,
  "frameworkName": "StringRedaction",
  "frameworkType": "STRING",
  "plugin": {
    "pluginId": 47,
    "pluginName": "algorithm"
  },
  "extensionSchema": {
    "id": "urn:jsonschema:sample:masking:algorithm:redaction:StringRedaction",
    "properties": {
      "redactionCharacter": {
        "type": "string",
        "required": true
      }
    }
  }
}

This schema is generated automatically using the annotated public fields in the framework class.