Managing Algorithm Usage¶
Overview¶
The Masking Engine provides API endpoints to view and modify the usage of algorithms globally. These operations span all usage of an algorithm, including: database column and file format assignments across all environments, usage in domains, and references from other algorithms.
Viewing Algorithm Usage¶
The following API endpoint retrieves all usage of the algorithm specified in the request path:
algorithm GET algorithm/{algorithmName}/usage
This endpoint supports the following option in the query parameters:
- includeAssignmentDetail (optional, default=false)
boolean
Enabling this option causes the API response to include a list of human-readable assignment detail objects, one for each individual usage of the algorithm in inventory. This can result in a very large response if the algorithm is heavily used. Algorithm usage in file formats will be reported once for each application of the file format to a file in inventory.
Updating Algorithm Usage¶
The following API endpoint updates all usage of the algorithm specified in the request path to use the new algorithm name supplied as a query parameter:
algorithm PUT algorithm/{algorithmName}/usage
This endpoint supports the following option in the query:
-
replacementAlgorithmName (required, no default)
String
The name of the algorithm that should replace the existing algorithm in all usage across the entire Masking Engine. -
ignoreIncompatibleTypes (optional, default=false)
boolean
Setting this option to true will allow some algorithm replacements that would normally fail due to incompatible types to succeed. This may result in job failures if type conversions don't exist to convert the underlying data type to the type expected by the new algorithm.
The response body from the PUT request details all usage that was updated by the operation.
WARNING
Globally updating algorithm usage can produce many inventory changes across multiple environments, and is not easily reversible when the replacement algorithm is already in use on the engine.
Delphix recommends performing the following steps before any update to algorithm usage via this API endpoint:
-
Perform the GET usage operation (described above) for both the existing and replacement algorithms. Carefully review the results and save them for future reference.
-
Export the engine's global settings and all affected environments prior to changing algorithm usage.
WARNING
Algorithm compatibility checking of usage changes may still allow some replacements that could result in job failures using the new algorithm. Careful consideration should be given to whether the new algorithm can handle the data types and inputs for all usage of the algorithm being replaced.
Examples¶
Getting usage for an algorithm with one column assignment:
REQUEST
curl -X GET --header 'Accept: application/json' --header 'Authorization: d46db68d-59f1-41e0-a128-c01bc920da30'
'http://masking-engine.example.com/masking/api/v5.1.10/algorithms/alg_6EBH8EGK/usage?includeAssignmentDetail=false'
RESPONSE
{
"algorithmName": "alg_6EBH8EGK",
"columnMetadataIds": [
11
],
"fileFieldMetadataIds": [],
"mainframeDatasetFieldMetadataIds": [],
"domainNames": [
"domain_6GXKQP60"
],
"algorithmReferences": []
}
The same request with additional detail requested:
REQUEST
curl -X GET --header 'Accept: application/json' --header 'Authorization: d46db68d-59f1-41e0-a128-c01bc920da30'
'http://masking-engine.example.com/masking/api/v5.1.10/algorithms/alg_6EBH8EGK/usage?includeAssignmentDetail=true'
RESPONSE
{
"algorithmName": "alg_6EBH8EGK",
"columnMetadataIds": [
11
],
"fileFieldMetadataIds": [],
"mainframeDatasetFieldMetadataIds": [],
"domainNames": [
"domain_6GXKQP60"
],
"algorithmReferences": [],
"assignmentDetails": [
{
"assignmentType": "DATABASE_COLUMN",
"environmentName": "env_ZBQ0XKO9",
"databaseRulesetName": "rule_POQRBZ44",
"databaseTableName": "profile",
"databaseColumnName": "last_name"
}
]
}
Updating all usage of algorithm named alg_6EBH8EGK
to alg_82U5GUZB
:
REQUEST
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json'
--header 'Authorization: d46db68d-59f1-41e0-a128-c01bc920da30'
'http://masking-engine.example.com/masking/api/v5.1.10/algorithms/alg_6EBH8EGK/usage?replacementAlgorithmName=alg_82U5GUZB&ignoreIncompatibleTypes=false'
RESPONSE
{
"columnMetadataIds": [
11
],
"fileFieldMetadataIds": [],
"mainframeDatasetFieldMetadataIds": [],
"domainNames": [
"domain_6GXKQP60"
],
"algorithmReferences": [],
"assignmentDetails": []
}