Fast Start - Data Masking
Framework: KernDX | Total time: ~20 minutes
- What this is: A way to redact card numbers, secrets, and personal data on a record before it is ever saved, using configuration records instead of Apex code.
- Why it matters: Sensitive values that slip into a free-text note or an integration payload are a compliance and breach risk; here the readable value never reaches the database.
- Who should follow it: developers and admins protecting regulated data, and tech leads who want data-protection rules that are version-controlled and reviewable.
- When to use it: any time a field could capture data you don't want stored in the clear.
- What you'll build: You will watch the framework redact a card number and a secret with zero setup, then configure masking on a field of your own object and verify the value is redacted before it is saved.
- Success looks like: A
Contactyou insert withDescription="Note — SSN 123-45-6789"reads back as"Note — SSN XXX-XX-XXXX". The sensitive value never reached the database. - In one line: masking is configuration, not code. Wire a
kern__MaskingTarget__mdtat a field and the sensitive value is redacted onbefore insert/before update, before it is ever stored.
Namespaces in code samples:
kern.on a class andkern__on an object, field, or metadata type mark the managed package's namespace. On the managed package, framework references need those prefixes even where a sample omits them; repackaged under your own namespace, replacekern/kern__with your prefix; on an unmanaged deploy, drop them. See How to read the code samples.
Quick Navigation
| I need to... | Go to... |
|---|---|
| See masking work with no setup | Tier 1: See It Work |
| Check that masking is switched on | Confirm masking is on |
| Mask a field on my own object | Tier 2: Mask a Field on Your Own Object |
| Find out why a field is not masked | The three gates |
| Make the configuration by hand instead of exporting | Step 3.1: The two records by hand |
| Choose what happens when a rule fails | Failure actions |
| Test masking in an Apex test | Testing your masking |
| Remove the example from my org | Clean up |
| Fix an error from a step | Common Issues |
| Know what masking does not do | What Masking Is Not |
Before you start
- Open your terminal in your project's top folder, the one that holds
sfdx-project.json. On Windows that terminal is Command Prompt. - Run the four-line check on Set Up Your Computer once: it proves your terminal, the CLI, your login and the KernDX package, and answers what goes wrong. Done that today? Carry on.
- Work in a sandbox or a scratch org, never production.
- Every command below writes
YourOrgAliaswhere your org's alias goes: the name you gave it when you logged in.
Tier 1: See It Work (~2 minutes)
You can see masking work before you configure anything. KernDX already has it switched on for its own objects, among them the API-audit object ApiCall__c, so the redaction happens with no setup from you.
Watch a record get redacted on save
In Salesforce, open the Developer Console (the gear icon, then Developer Console), then Debug, then Open Execute Anonymous Window, and run:
kern__ApiCall__c call = new kern__ApiCall__c();
call.kern__ServiceName__c = 'Masking Demo';
call.kern__Direction__c = 'Inbound';
call.kern__Status__c = 'Completed';
call.kern__Request__c = '{"card":"4111111111111111","password":"hunter2"}';
insert call;
kern__ApiCall__c stored = [SELECT kern__Request__c FROM kern__ApiCall__c WHERE Id = :call.Id];
System.debug(stored.kern__Request__c);You should see this line in the log: the stored value, already redacted. (The framework re-serialises the JSON, so the keys come back in a different order. Only the redacted values matter.)
{"password":"***SECRET***","card":"[CARD_REDACTED]"}The card number was caught by the MaskPaymentCard rule (a Luhn-checked match). The secret under the password key was caught by the MaskSecretKeys rule. Both fired on the before insert pass, so the readable values never reached the database.
Why
ApiCall__c? It is one of the four framework objects that ship with masking already configured (the others areApiIssue__c,AsyncChainExecution__cand theLogEntryEvent__elog event), and the easiest one to save and read back here. Your own objects are not masked until you configure them, which is Tier 2.
Confirm masking is on
You can check the master switch from anywhere: your own Apex, anonymous Apex, or a test.
In Salesforce, in the same Execute Anonymous window, run:
Boolean maskingOn = kern.UTIL_FeatureFlag.isEnabled('MaskingFramework_Enabled'); // true by default
System.debug('Masking enabled: ' + maskingOn);You should see Masking enabled: true in the log.
MaskingFramework_Enabled is the framework's kill-switch: a master off-switch you can flip in an incident without a deployment. It defaults on. Turn it off only for a deliberate, temporary diagnostic against raw data in a sandbox.
Something went wrong? See Common Issues, Tier 1.
When to move to Tier 2: When you want this same redaction on a field of your own object.
Tier 2: Mask a Field on Your Own Object (~12 minutes)
Masking your own data is configuration, not Apex: you do not write a masking class. You declare where a rule applies, deploy that metadata, and the framework does the rest. To make it concrete, we'll redact Social Security Numbers that end up in a Contact.Description note.
The three gates
Masking fires for a record only when all three of these conditions hold, and the operation is before insert or before update:
- The
MaskingFramework_Enabledfeature flag is on (it is, by default). - At least one of the object's
kern__TriggerSetting__mdtrecords haskern__ApplyMasking__cchecked. - At least one active masking target resolves a field on that object.
Step 1: Put the object on the trigger framework
Masking runs as a step inside the KernDX trigger dispatcher, so the object has to route through it, and the object's trigger setting switches masking on (Gate 2). If you already use KernDX trigger actions on this object, the trigger is already wired: skip to Step 1.2.
Step 1.1: Add the trigger
Add a one-line trigger file that hands control to the framework (see Fast Start - Trigger Actions for the full pattern). You create it with one command, replace what the command wrote, then send it to your org.
1. In the terminal, from your project's top folder, create the trigger:
sf apex generate trigger --name ContactTrigger --sobject Contact --event "before insert" --output-dir force-app/main/default/triggersYou should see two files created in force-app/main/default/triggers: ContactTrigger.trigger and its companion of the same name ending in .trigger-meta.xml.
2. In your editor, open this file, delete what is there (the command writes an empty trigger), paste the code below in, and save:
force-app/main/default/triggers/ContactTrigger.triggertrigger ContactTrigger on Contact (before insert, before update)
{
new kern.TRG_Dispatcher().run();
}3. In the terminal, send the trigger to your org:
sf project deploy start -o YourOrgAlias -m "ApexTrigger:ContactTrigger"You should see Status: Succeeded, with ContactTrigger listed as created.
Something went wrong? See Common Issues, Step 1.
Step 1.2: Create the trigger setting
The trigger setting with Apply Masking checked is Gate 2. The Advisor's export in Step 2 does not include this record, so make it whichever path you take.
If you skipped Step 1.1 because the object is already on the trigger framework, it already has a trigger setting: do not create a second one. Open that existing record instead, confirm Apply Masking is checked (it is by default), and pull it with the command below, putting its Trigger Setting Name in place of Contact.
1. In Salesforce, open Setup, then Custom Metadata Types, then Trigger Setting, then Manage Trigger Settings, then New, and save a record with these values:
| Field | API name | Value |
|---|---|---|
| Label | MasterLabel | Contact |
| Trigger Setting Name | DeveloperName | Contact |
| SObject Type | kern__SObjectType__c | Contact |
| Apply Masking | kern__ApplyMasking__c | checked |
| Bypass Execution | kern__BypassExecution__c | unchecked |
2. In the terminal, pull the record into your project:
sf project retrieve start -o YourOrgAlias -m "CustomMetadata:kern__TriggerSetting.Contact"You should see one file created under force-app/main/default/customMetadata, named after the record.
Something went wrong? See Common Issues, Step 1.
Step 2: Assign a rule and export the configuration
The fastest path, and the one least likely to introduce mistakes, is the Data Masking Advisor.
In Salesforce, open it from the App Launcher (search "Data Masking Advisor"):
- Pick your object:
Contact. The Advisor lists its fields and flags the ones that look sensitive. - Assign a rule: on the
Descriptionfield, choose a rule such as Mask US Social Security Numbers from the dropdown. - Export: click Export. The Advisor bundles what Gate 3 needs: the masking target wiring the rule to
Contact.Description, and a file that activates the rule if it is a dormant template. It does not include the Trigger Setting (Gate 2): that is the record you made in Step 1.2.
The Advisor never writes to your org. Instead it generates correctly-namespaced metadata that you deploy. Prefer it over hand-authoring, because getting the kern__ prefixes and field references right by hand is fiddly. (Step 3.1 shows the masking target it bundles, made by hand instead.)
Step 3: Deploy
In the terminal, from the unzipped export folder, run the line the Advisor shows you:
sf project deploy start --metadata-dir metadata -o YourOrgAliasYou should see the deploy succeed and list the masking records from the export.
Something went wrong? See Common Issues, Step 3.
Step 3.1: The two records by hand
If you would rather make the configuration yourself instead of deploying the export, the by-hand path needs two records:
- the Trigger Setting you made in Step 1.2, which turns masking on for the object (Gate 2);
- the masking target the Advisor would otherwise bundle, which wires a rule to the field (Gate 3).
Make the masking target now: a kern__MaskingTarget__mdt record wiring the SSN rule to Contact. Because the type is the packaged kern__MaskingTarget__mdt, its field names carry the kern__ prefix and the packaged rule is referenced as kern__MaskSsn.
1. In Salesforce, open Setup, then Custom Metadata Types, then Masking Target, then Manage Masking Targets, then New, and save a record with these values:
| Field | API name | Value |
|---|---|---|
| Label | MasterLabel | SSN / Contact |
| Masking Target Name | DeveloperName | Mask_Contact_Ssn |
| Rule | kern__Rule__c | Mask US Social Security Numbers (the packaged kern__MaskSsn) |
| SObject Type | kern__SObjectType__c | Contact |
| Active | kern__IsActive__c | checked |
| Field | kern__Field__c | left blank |
| Caller Class | kern__CallerClass__c | left blank |
2. In the terminal, pull the record into your project:
sf project retrieve start -o YourOrgAlias -m "CustomMetadata:kern__MaskingTarget.Mask_Contact_Ssn"You should see one file created under force-app/main/default/customMetadata, named after the record.
A blank kern__Field__c is an object-wide wildcard: the SSN rule scans every text field on Contact (Text, Text Area, Long Text Area, Rich Text Area, URL, Email, Phone and Encrypted Text), whoever saves the record, so the note's SSN is caught wherever it lands in ordinary text.
- A unique field or an external id is never touched by a wildcard, because rewriting a key breaks it.
- Neither is a formula, roll-up summary or auto-number field, because the platform works out those values and there is nothing to rewrite.
- If you do want a rule on a key field, name that field explicitly in
kern__Field__c: an explicit target is treated as your deliberate choice and is honoured. - To narrow the target to a single field, let the Advisor build the field reference for you, because getting the namespaced field path right by hand is the fiddly part the export removes.
Activating the packaged
MaskSsnrule. The target points at a rule that must be active, andMaskSsnships as a dormant template. Active (kern__IsActive__c) is a field your org controls on a packaged rule, so a deploy that carries only the Active value activates it: that is what the Data Masking Advisor export's activation file does.By hand, open Setup, then Custom Metadata Types, then Masking Rule, then Manage Masking Rules, then Mask US Social Security Numbers (the
MaskSsnrecord), then Edit; check Active and save.
Something went wrong? See Common Issues, Step 3.
Step 4: Verify the redaction
Insert a Contact whose note carries an SSN, then read it back.
In Salesforce, open the Developer Console's Execute Anonymous window, as in Tier 1, and run:
Contact c = new Contact(LastName = 'Masking Demo', Description = 'Internal note — SSN 123-45-6789');
insert c;
c = [SELECT Description FROM Contact WHERE Id = :c.Id];
System.debug(c.Description);You should see this line in the log, the stored Description:
Internal note — SSN XXX-XX-XXXXThe SSN was redacted on the before insert pass. The readable value never reached the database, and every downstream trigger and the saved row see only the masked text.
Something went wrong? See Common Issues, Step 4.
Tier 3: Production Patterns (~6 minutes)
Rule modes
A masking rule (kern__MaskingRule__mdt) matches in one of four modes. KernDX ships 18 rules: 3 active, and 15 dormant ones you activate by ticking the rule's Active box and wiring a target to them. (One dormant rule is the original kern__MaskCreditCard, which kern__MaskPaymentCard replaces. It ships switched off with its four targets; switch all five on or off together.)
| Mode | What it matches |
|---|---|
Regex | A regular expression; matched substrings are replaced (the MaskSsn rule above is a Regex rule). |
CreditCard | A regex plus a Luhn (mod-10) check, so a 16-digit order number survives. |
JsonKey | Treats the value as JSON and redacts the value under each matching key, recursing nested objects. |
ExactMatch | A literal substring (no regex metacharacters). No shipped rule uses this mode; it is there for custom rules. |
Failure actions
Each rule's failure action decides what happens if it errors while masking a value:
| Action | Behaviour |
|---|---|
LogAndContinue | Logs a warning and keeps the original value. The rule is skipped for the rest of the transaction, so later values it covers stay unmasked too. |
WriteFailureMarker | Saves [MASKING_FAILURE] in place of the value it failed on, and keeps masking every other value. The default for a rule you create. |
BlockDml | Throws kern.UTIL_Exceptions.MaskingBlockedException, so the record save fails. On the framework's own log entries and call files, it drops what it could not mask. |
The Data Masking Advisor
Beyond assigning rules, the Advisor is a standing review console:
- Scan custom objects for likely-sensitive fields that have no masking, on demand, a few objects at a time.
- Export a regulated-field inventory: a CSV or JSON census of fields that hold (or likely hold) regulated data, each marked whether it is masked today, with an optional Sensitive fields only filter.
- Read the two Health Check cards. Masking configuration flags targets pointing at an inactive or missing rule, and Masking coverage (custom objects) shows where masking is absent. Both deep-link back into the Advisor.
It is a point-in-time review tool, not continuous monitoring: it analyses when you open it or press a button.
Testing your masking
In an @IsTest class you cannot deploy a kern__MaskingTarget__mdt (there is no Metadata API in tests), but you can inject one as a mock. kern.TST_Mock is the supported, global way to do this.
In your editor, in a test class:
kern.TST_Mock.register(
kern__MaskingTarget__mdt.SObjectType,
new List<kern__MaskingTarget__mdt>{ /* your mock target + rule */ }
);This lets a test run a rule against a framework object that already ships with a trigger and a Trigger Setting with Apply Masking ticked, such as ApiCall__c. Insert the record and the mocked target fires.
It does not unlock your own object. A mock target satisfies one gate, but the masking pass also needs the object to have a real trigger and a Trigger Setting, and neither can be conjured in a test.
So for masking on your own object the trustworthy proof is the deploy-and-verify of Step 4 against a sandbox. Treat that as the gate before you promote the configuration.
Clean up
If you built this example only to try the framework, run these two commands when you have finished the guide. Before you run them:
Contactwas already on the trigger framework before this guide: leave its trigger out of the first command and skip the second, so you keep its trigger and trigger setting.- You deployed the Advisor's export instead of making the masking target in Step 3.1: the export named the target itself. Leave
Mask_Contact_Ssnout of the first command and delete that target in Setup instead (its name starts withMask_Contact_). - The commands do not delete the
Masking Democontact from Step 4 and theMasking DemoAPI call record from Tier 1 (delete them in the app, or leave them). - The
MaskSsnrule's Active box is not cleared by the commands: clear it in Setup if you activated the rule only for this guide.
1. In the terminal, delete the trigger and the masking target:
sf project delete source -o YourOrgAlias -m "ApexTrigger:ContactTrigger" -m "CustomMetadata:kern__MaskingTarget.Mask_Contact_Ssn" --no-promptYou should see Status: Succeeded, then a Deleted Source table listing the trigger and the masking target.
2. In the terminal, delete the trigger setting:
sf project delete source -o YourOrgAlias -m "CustomMetadata:kern__TriggerSetting.Contact" --no-promptYou should see Status: Succeeded, then a Deleted Source table listing the trigger setting.
The commands delete the files from your project too.
Something went wrong? See Common Issues.
Common Issues
Trouble with your computer rather than this guide (sf is not recognised, scripts are disabled, you are not logged in, the wrong folder)? Those are answered once, in Set Up Your Computer.
Tier 1: See It Work
A card-shaped number is not redacted
It failed the Luhn check, or was shorter than the rule's kern__MinInputLength__c. Confirm it is a real card number: MaskPaymentCard deliberately skips digit runs that fail the Luhn check and inputs with fewer than 13 characters.
Step 1: Put the object on the trigger framework
The trigger's deploy fails
The trigger's deploy fails for the same reasons as a class's deploy in the Trigger Actions guide: the command ran outside your project's top folder, or the org does not have KernDX installed. See its Common Issues, Step 1.
The pull creates no file
The record's name in Setup does not match the name in the command. The command asks for Contact; check the Trigger Setting Name on the record, fix it, and pull again.
Step 3: Deploy
The export's deploy fails
Run the command from the unzipped export folder, the one that holds the metadata folder: the command names that folder, so it finds nothing from anywhere else. If the deploy reports a component failure instead, its table names the record that failed and why. You can also make the records by hand, as Step 3.1 shows.
The Masking Target form will not save
The form needs Rule and SObject Type before it saves. Fill in every value in the Step 3.1 table, then save again.
The Masking Target pull creates no file
The record's name in Setup does not match the name in the command. The command asks for Mask_Contact_Ssn; check the Masking Target Name on the record, fix it, and pull again.
Step 4: Verify the redaction
The Description comes back unmasked
One of the three gates is not met. Check them in order:
- The object has no KernDX trigger, or its trigger setting does not have Apply Masking (
kern__ApplyMasking__c) checked. Add the one-line trigger and the trigger setting as in Step 1. - The target is active but its rule is inactive or missing. Activate the rule (Active,
kern__MaskingRule__mdt.kern__IsActive__c, as the note in Step 3.1 shows), or check the Masking configuration Health Check card. - Masking is switched off: run the Tier 1 check, which should show
Masking enabled: true.
Existing rows still show raw values
Masking is write-time, not retroactive. Re-save the records (a one-off batch) so they pass back through the masking pass.
Tier 3: Production Patterns
Variable does not exist: MaskingTarget__mdt
Your Apex names the packaged type without its namespace prefix. Use the kern__ prefix on the type, its fields, and any packaged rule reference.
A BlockDml rule stops an insert
The rule could not redact a value and is set to block the save. This is by design: fix the data or change the rule's failure action, and catch kern.UTIL_Exceptions.MaskingBlockedException.
Still stuck? Tell us which step and what you saw.
What Masking Is Not
Knowing the boundaries keeps you from using masking where a different control belongs:
- It is write-time, not retroactive. Masking redacts records as they are inserted or updated. It does not scan or rewrite rows already stored. To clean up existing data, re-save it through a one-off batch.
- It is one-way. The redacted value overwrites the original; there is no key and no decrypt path. Use Shield Platform Encryption when you need the value back.
- It is not access control. A masked field is still visible to anyone with field-level security to read it. Masking changes the stored value, not who can see it. Use Field-Level Security and sharing for that.
- It covers text-shaped fields only: Text, Text Area, Long Text Area, Rich Text Area, URL, Email, Phone, and Encrypted Text. Numbers, dates, checkboxes, picklists, and lookups cannot be masked.
What You Now Know
| Concept | What it does |
|---|---|
kern.UTIL_FeatureFlag.isEnabled('MaskingFramework_Enabled') | The supported, global way to check whether masking is switched on |
before insert / before update masking pass | Redacts text-shaped fields on the record before it is written |
kern__MaskingRule__mdt | A reusable redaction recipe: pattern, replacement, mode, failure action |
kern__MaskingTarget__mdt | Wires a rule to an object (and optionally a field and caller) |
kern__TriggerSetting__mdt.kern__ApplyMasking__c | The per-object switch that opts an object into masking |
| Data Masking Advisor | No-code review and a deployable export; never writes to your org |
kern.TST_Mock | The global way to inject a mock masking target in a test |
Key patterns:
- Mask your own object with a
kern__MaskingTarget__mdtpluskern__ApplyMasking__c: configuration, not Apex. - Use the Data Masking Advisor to review coverage and export correctly-namespaced metadata.
- Verify masking by deploying to a sandbox and reading the stored value back. The masking pass needs a real trigger, so a sandbox is the trustworthy proof.
- Choose the failure action deliberately: use
BlockDmlfor values that must never persist unmasked.