Checkdigit
See Checkdigit for more information about this algorithm framework.
Creating a checkdigit algorithm via API
1. Retrieve the frameworkId for the Checkdigit Framework. This information can be retrieved using the following endpoint:
algorithm GET /algorithm/frameworks
The framework information should look similar to the following:
{
"frameworkId": 8,
"frameworkName": "Checkdigit",
"frameworkType": "STRING",
"description": "This algorithm calculates the check digit of the input value and returns it as a string.",
"plugin": {
"pluginId": 7,
"pluginName": "dlpx-core",
"pluginAuthor": "Delphix Engineering",
"pluginType": "EXTENDED_ALGORITHM" }
}
2. Create a Checkdigit algorithm via the following endpoint:
algorithm POST /algorithms
The schema for the algorithm is described in the following endpoint:
algorithm GET /algorithm/frameworks/id/{frameworkId}
And looks similar to the following:
{
"frameworkId": 8,
"frameworkName": "Checkdigit",
"frameworkType": "STRING",
"description": "This algorithm calculates the check digit of the input value and returns it as a string.",
"plugin": {
"pluginId": 7,
"pluginName": "dlpx-core",
"pluginAuthor": "Delphix Engineering",
"pluginType": "EXTENDED_ALGORITHM"
},
"extensionSchema": {
"id": "urn:jsonschema:algorithm:plugin:checkdigit:Checkdigit",
"properties": {
"numericAlgorithm": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the digits of the input value prior to checkdigit(s) calculation.",
"properties": {
"name": {
"type": "string",
"required": true,
"description": "The algorithm instance name, starting with \":\" for instances provided by this plugin"
},
"algorithmMetadata": {
"type": "object",
"id": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference:AlgorithmReferenceMetadata",
"description": "Metadata values passed to the chained algorithm. Can be used to control how automatic type conversions are performed.",
"properties": {
"dateFormat": {
"type": "string",
"description": "The expected date format of a date value being masked."
},
"maxLength": {
"type": "integer",
"description": "The maximum size of the value being masked."
},
"stringMaxLengthEncoded": {
"type": "boolean",
"description": "Boolean value indicating whether the value maxLength represents the maximum Java String length in characters (false), or a byte length limit."
},
"stringCharsetName": {
"type": "string",
"description": "The name of the Charset used to encode string values."
}
}
}
}
},
"fallbackAlgorithm": {
"type": "object",
"$ref": "urn:jsonschema:com:delphix:masking:api:plugin:referenceType:AlgorithmInstanceReference",
"description": "The algorithm used to mask the input data if it does not appear in the expected format."
},
"preserveRegex": {
"type": "string",
"description": "Ranges of characters to preserve expressed as regex. The preserved characters will be copied to the output without modification. Important: The preserved characters will not be used in the checkdigit calculation."
},
"weightList": {
"type": "array",
"required": true,
"description": "The list of weights to be used in the checkdigit calculation.",
"items": {
"type": "integer"
}
},
"modulusNumber": {
"type": "integer",
"required": true,
"description": "The modulus number to be used in the checkdigit calculation."
},
"checkDigitIndex": {
"type": "integer",
"required": true,
"description": "The position in the input string to insert the checkdigit, starting with zero for the first digit position. Negative values count backwards from the end of the string, i.e. a value of -2 will be the second to last digit and -1 would be the last. This can account for a variable amount of digits. Non-numeric characters are not counted, only digits apply to the index. If the index is out of bounds the fallback algorithm will mask the input."
},
"calculateChecksumRightToLeft": {
"type": "boolean",
"required": true,
"description": "The direction that the checksum calculation iterates through the input numbers. IBM Mod 11 and Luhn calculate right to left. Verhoeff, Damm and IBAN Mod97-10 calculates left to right."
},
"numDigitsForCheckdigitCalculation": {
"type": "integer",
"required": true,
"description": "The number of digits to use for the checkdigit calculation. If the number of digits used to calculate the checkdigit is less than this, it will be masked using the fallback algorithm. The original checkdigit and and preserved characters are not counted in this number."
},
"swapModulusForZeroRemainder": {
"type": "boolean",
"description": "Some identifiers avoid a first character of zero and have the checknumber in the first position. In this specific case the zero is swapped for the checknumber. Only applicable to identifiers with this specific requirement and a single digit modulus."
}
}
}
The following JSON formatted input can be used to create a new instance of the framework. Customize it to your specification.
{
"algorithmName": "Example Checkdigit Algorithm",
"algorithmType": "COMPONENT",
"description": "This is the Example Checkdigit Algorithm configuration",
"frameworkId": 8,
"pluginId": 7,
"algorithmExtension": {
"weightList": [
1,
2 ],
"modulusNumber": 9,
"preserveRegex": "",
"checkDigitIndex": 0,
"numericAlgorithm": {
"name": "dlpx-core:CM Digits"
},
"fallbackAlgorithm": {
"name": "dlpx-core:CM Alpha-Numeric"
},
"swapModulusForZeroRemainder": true,
"calculateChecksumRightToLeft": true,
"numDigitsForCheckdigitCalculation": 12
},
"isConfigInvalid": false
}
Checkdigit algorithm extension
The following are configurations for the framework used to create unique instances.
weightList
Array of integers
Defines the weights iterated through by the modulus algorithm when calculating the some from which to derive a checkdigit. For example, IBM MOD11 uses [2, 3, 4, 5, 6, 7]
modulusNumber
Integer
An integer describing the modulus for the algorithm. The built in instances using the framework are based on MOD11 and MOD9.
preserveRegex
String regex expression
Characters to remain unchanged in the input. Used for additional non-calculation digits and alpha numeric characters. For example, this: [0-9]$ will preserve a digit in the last position.
checkDigitIndex
Integer
Where in the input the checkdigit is found, represented with an index starting at zero for the first character. Negative indexes wrap, so an index of -1 will indicate the last character in the input, an index of -2 would be the second to last and so forth. Only digits are considered in the index placement.
numericAlgorithm
AlgorithmInstanceReference
The algorithm used to mask the digits used in the checkdigit calculation. It is only applied to digits, not including the initial checkdigit and any preserved characters. It is configurable but defaults to an instance of CM Digits.
fallbackAlgorithm
AlgorithmInstanceReference
Sometimes things don’t go as planned. The fallback algorithm is used to mask data that does not conform to the expected input structure. It is applied when:
-
The configured index is out of bounds for the input value
-
The number of digits available for calculating the checkdigit is smaller than expected
It is configurable but defaults to an instance of CM Alpha Numeric.
swapModulusForZeroRemainder
Boolean
When the checkdigit value would be zero, substitute the modulus value. This is specifically used for the MOD9 calculation, in the case of a leading checkdigit that is not allowed to be zero. Specifically implemented to support Japanese Corporate Number format.
calculateModulusRightToLeft
Boolean
Some checkdigit algorithms iterate through digits right to left (IBM MOD11, MOD9) when multiplying by weights, others from left to right (MOD97, LUHN). This indicates that configuration.
numDigitsForCheckdigitCalculation
Integer
Ensures the correct amount of digits are used to calculate the new checkdigit in the masked output. An incorrect amount of digits in the input value will trigger use of the fallback algorithm.