Skip to content

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 Contact you insert with Description = "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__mdt at a field and the sensitive value is redacted on before insert / before update, before it is ever stored.

Namespaces in code samples: kern. on a class and kern__ 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, replace kern/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 setupTier 1: See It Work
Check that masking is switched onConfirm masking is on
Mask a field on my own objectTier 2: Mask a Field on Your Own Object
Find out why a field is not maskedThe three gates
Make the configuration by hand instead of exportingStep 3.1: The two records by hand
Choose what happens when a rule failsFailure actions
Test masking in an Apex testTesting your masking
Remove the example from my orgClean up
Fix an error from a stepCommon Issues
Know what masking does not doWhat 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 YourOrgAlias where 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:

apex
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.)

text
{"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 are ApiIssue__c, AsyncChainExecution__c and the LogEntryEvent__e log 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:

apex
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:

  1. The MaskingFramework_Enabled feature flag is on (it is, by default).
  2. At least one of the object's kern__TriggerSetting__mdt records has kern__ApplyMasking__c checked.
  3. 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:

shell
sf apex generate trigger --name ContactTrigger --sobject Contact --event "before insert" --output-dir force-app/main/default/triggers

You 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:

text
force-app/main/default/triggers/ContactTrigger.trigger
apex
trigger ContactTrigger on Contact (before insert, before update)
{
	new kern.TRG_Dispatcher().run();
}

3. In the terminal, send the trigger to your org:

shell
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:

FieldAPI nameValue
LabelMasterLabelContact
Trigger Setting NameDeveloperNameContact
SObject Typekern__SObjectType__cContact
Apply Maskingkern__ApplyMasking__cchecked
Bypass Executionkern__BypassExecution__cunchecked

2. In the terminal, pull the record into your project:

shell
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"):

  1. Pick your object: Contact. The Advisor lists its fields and flags the ones that look sensitive.
  2. Assign a rule: on the Description field, choose a rule such as Mask US Social Security Numbers from the dropdown.
  3. 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:

shell
sf project deploy start --metadata-dir metadata -o YourOrgAlias

You 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:

FieldAPI nameValue
LabelMasterLabelSSN / Contact
Masking Target NameDeveloperNameMask_Contact_Ssn
Rulekern__Rule__cMask US Social Security Numbers (the packaged kern__MaskSsn)
SObject Typekern__SObjectType__cContact
Activekern__IsActive__cchecked
Fieldkern__Field__cleft blank
Caller Classkern__CallerClass__cleft blank

2. In the terminal, pull the record into your project:

shell
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 MaskSsn rule. The target points at a rule that must be active, and MaskSsn ships 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 MaskSsn record), 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:

apex
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:

text
Internal note — SSN XXX-XX-XXXX

The 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.)

ModeWhat it matches
RegexA regular expression; matched substrings are replaced (the MaskSsn rule above is a Regex rule).
CreditCardA regex plus a Luhn (mod-10) check, so a 16-digit order number survives.
JsonKeyTreats the value as JSON and redacts the value under each matching key, recursing nested objects.
ExactMatchA 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:

ActionBehaviour
LogAndContinueLogs 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.
WriteFailureMarkerSaves [MASKING_FAILURE] in place of the value it failed on, and keeps masking every other value. The default for a rule you create.
BlockDmlThrows 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:

apex
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:

  • Contact was 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_Ssn out of the first command and delete that target in Setup instead (its name starts with Mask_Contact_).
  • The commands do not delete the Masking Demo contact from Step 4 and the Masking Demo API call record from Tier 1 (delete them in the app, or leave them).
  • The MaskSsn rule'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:

shell
sf project delete source -o YourOrgAlias -m "ApexTrigger:ContactTrigger" -m "CustomMetadata:kern__MaskingTarget.Mask_Contact_Ssn" --no-prompt

You should see Status: Succeeded, then a Deleted Source table listing the trigger and the masking target.

2. In the terminal, delete the trigger setting:

shell
sf project delete source -o YourOrgAlias -m "CustomMetadata:kern__TriggerSetting.Contact" --no-prompt

You 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 ​

ConceptWhat it does
kern.UTIL_FeatureFlag.isEnabled('MaskingFramework_Enabled')The supported, global way to check whether masking is switched on
before insert / before update masking passRedacts text-shaped fields on the record before it is written
kern__MaskingRule__mdtA reusable redaction recipe: pattern, replacement, mode, failure action
kern__MaskingTarget__mdtWires a rule to an object (and optionally a field and caller)
kern__TriggerSetting__mdt.kern__ApplyMasking__cThe per-object switch that opts an object into masking
Data Masking AdvisorNo-code review and a deployable export; never writes to your org
kern.TST_MockThe global way to inject a mock masking target in a test

Key patterns:

  • Mask your own object with a kern__MaskingTarget__mdt plus kern__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 BlockDml for values that must never persist unmasked.

Next Steps ​