Fast Start - DML
Framework: KernDX | Total time: ~30 minutes
- What this is: a safer way to write records to Salesforce in Apex. Instead of plain
insert,update, anddelete, you build up the changes you want and run them as one transaction. - Why it matters: that single path gives you automatic error logging, parent-to-child relationships wired up for you, partial-success handling, and control over security and sharing, all without repeating boilerplate.
- Who should follow it: any developer who writes Apex that saves data.
- When to use it: any time your code creates, changes, or removes records. KernDX expects every save to go through
DML_Builder, even a single record with no related children, so every save gets the same user-mode security and consistent error logging across your codebase. - What you'll build: a service class that creates an Account with related Contacts and an Opportunity in a single atomic (all-or-nothing) transaction, with the parent-child foreign keys filled in automatically.
- Success looks like: you call your service, verify the Account and its children were created with correct relationships, and your test class has 100% coverage.
- In one line:
kern.DML_Builder.newTransaction().doInsert(newAccount).doInsert(newContact, Contact.AccountId, newAccount).execute();(parent-child foreign keys are resolved automatically).
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.
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)
See the builder work straight away. You can call DML_Builder directly from anonymous Apex, with no custom classes to create first.
Insert a Record (instead of Database.insert)
In Salesforce, open the Developer Console (the gear icon, then Developer Console), then Debug, then Open Execute Anonymous Window, and run:
Account account = new Account(Name = 'Quick Test', Phone = '555-0100');
kern.DML_Builder.TransactionResult result = kern.DML_Builder.newTransaction()
.doInsert(account)
.execute();
System.debug('Success: ' + result.isSuccess());
System.debug('Account Id: ' + account.Id);
System.debug('Inserted IDs: ' + result.getInsertedIds());You should see these lines in the log, with your record's Id in place of 001...:
Success: true
Account Id: 001...
Inserted IDs: (001...)Update a Record
In Salesforce, in the same Execute Anonymous window, run:
Account found = (Account)kern.QRY_Builder.selectFrom(Account.SObjectType)
.fields(new List<SObjectField>{ Account.Name, Account.Industry })
.condition(Account.Name).equals('Quick Test')
.getFirst();
found.Industry = 'Technology';
kern.DML_Builder.newTransaction()
.doUpdate(found)
.execute();
System.debug('Updated Industry: ' + found.Industry);You should see this line in the log:
Updated Industry: TechnologyParent-Child Insert
Insert an Account and a Contact in one transaction. The framework fills in the Contact's AccountId for you.
In Salesforce, in the same Execute Anonymous window, run:
Account newAccount = new Account(Name = 'Parent Co', Phone = '555-0100');
Contact newContact = new Contact(LastName = 'Smith', FirstName = 'Jane');
kern.DML_Builder.newTransaction()
.doInsert(newAccount)
// .doInsert(child, lookupField, parent) — framework sets child.lookupField = parent.Id after parent insert
.doInsert(newContact, Contact.AccountId, newAccount)
.execute();
System.debug('Account Id: ' + newAccount.Id);
System.debug('Contact AccountId: ' + newContact.AccountId);You should see these lines in the log, with the same Id on both:
Account Id: 001...
Contact AccountId: 001...The Contact's AccountId matches the Account's Id, set automatically by the framework.
Naming tip: Don't name a variable
contact(lowercase) in anonymous Apex when usingContact.AccountId. The variable shadows the SObject type, soContact.AccountIdresolves as a field value (Id) instead of a field token (SObjectField). UsenewContact,result, or another name. The same applies toaccountandAccount.
Something went wrong? See Common Issues, Parent-Child Insert.
When to move to Tier 2: When you need to encapsulate DML operations in a reusable service class with proper test coverage.
Tier 2: Build Your Own (~20 minutes)
No local project? You can create classes directly in the Developer Console (Gear Icon > Developer Console > File > New > Apex Class) and run tests from there too (Test > New Run). Paste the code, save, and skip the terminal commands.
Build an Account onboarding service that creates an Account with related Contacts and an Opportunity in a single atomic transaction.
Step 1: Create the Service Class
The service is one class with one method that saves the Account and its related records together. You create an empty class with one command, paste the code into it, then send it to your org.
1. In the terminal, from your project's top folder, create the empty class:
sf apex generate class --name SVC_AccountOnboarding --output-dir force-app/main/default/classesYou should see two files created in force-app/main/default/classes: SVC_AccountOnboarding.cls and its companion of the same name ending in .cls-meta.xml.
The second file tells Salesforce which API version the class uses. You never edit it, but a deploy fails without it.
2. In your editor, open this file, delete what is there, paste the code below in, and save. Paste it exactly as it is: keep the class name.
force-app/main/default/classes/SVC_AccountOnboarding.clsWhy
public? Unlike triggers and APIs, service classes are called directly by your own code, so the framework never has to look them up by name. That meanspublicis enough;globalis not required.
/**
* @description Account onboarding service. Creates an Account with related Contacts
* and an Opportunity in a single transaction.
*
* @see SVC_AccountOnboarding_TEST
*
* @author your.name@company.com
*
* @group Services
*
* @date February 2026
*/
public with sharing class SVC_AccountOnboarding
{
/**
* @description Creates an Account with related Contacts and an Opportunity.
*
* @param accountName The name for the new Account.
* @param contactLastNames Last names for the Contacts to create.
* @param opportunityName The name for the Opportunity.
*
* @return The result of the transaction.
*/
public kern.DML_Builder.TransactionResult createAccount
(
String accountName,
List<String> contactLastNames,
String opportunityName
)
{
Account newAccount = new Account(Name = accountName, Industry = 'Technology');
Opportunity newOpportunity = new Opportunity
(
Name = opportunityName,
StageName = 'Prospecting',
CloseDate = Date.today().addDays(30)
);
kern.DML_Builder dmlTransaction = kern.DML_Builder.newTransaction()
.doInsert(newAccount)
.doInsert(newOpportunity, Opportunity.AccountId, newAccount);
for(String lastName : contactLastNames)
{
Contact newContact = new Contact(LastName = lastName);
dmlTransaction.doInsert(newContact, Contact.AccountId, newAccount);
}
return dmlTransaction.execute();
}
}Naming tip: Avoid naming variables
account,contact, oropportunity(lowercase) when usingAccount.SomeField,Contact.AccountId, orOpportunity.AccountIdas SObjectField tokens. Apex is case-insensitive, so the variable shadows the SObject type and the field reference resolves as a value instead of a token. UsenewAccount,newContact, and so on.
3. In the terminal, send the class to your org:
sf project deploy start -o YourOrgAlias -m "ApexClass:SVC_AccountOnboarding"You should see Status: Succeeded, with SVC_AccountOnboarding listed as created.
Something went wrong? See Common Issues, Step 1.
Step 2: Execute
Try the service from anonymous Apex. Paste both snippets in one Execute Anonymous window, because the second depends on result from the first.
In Salesforce, open the Developer Console (the gear icon, then Developer Console), then Debug, then Open Execute Anonymous Window, and paste the first snippet:
List<String> contactLastNames = new List<String>{ 'Smith', 'Jones' };
kern.DML_Builder.TransactionResult result =
new SVC_AccountOnboarding().createAccount('Acme Corp', contactLastNames, 'Acme Deal');
System.debug('Success: ' + result.isSuccess());
System.debug('Inserted IDs: ' + result.getInsertedIds());
System.debug('Success count: ' + result.getSuccessCount());In Salesforce, in the same window and below the first snippet, paste the second, which checks the relationships in the org, then run both:
Id accountId = result.getInsertedIds()[0];
List<Contact> childContacts = kern.QRY_Builder.selectFrom(Contact.SObjectType)
.fields(new List<SObjectField>{ Contact.LastName })
.condition(Contact.AccountId).equals(accountId)
.toList();
List<Opportunity> opportunities = kern.QRY_Builder.selectFrom(Opportunity.SObjectType)
.fields(new List<SObjectField>{ Opportunity.Name })
.condition(Opportunity.AccountId).equals(accountId)
.toList();
System.debug('Contacts: ' + childContacts.size());
System.debug('Opportunities: ' + opportunities.size());You should see these lines in the log, with your own record Ids in the second line (the Account's first, then the Opportunity's, then the two Contacts'):
Success: true
Inserted IDs: (001..., 006..., 003..., 003...)
Success count: 4followed by the counts of related records:
Contacts: 2
Opportunities: 1Why it works, step by step:
DML_Builder.newTransaction(): creates a new transaction builder..doInsert(record): registers a record for insertion..doInsert(child, field, parent): registers a child with a parent relationship. Register the parent with its own.doInsert()too, before or after the child: the framework inserts parents before their children whatever order you register them in. Afterexecute(), the child's lookup field is auto-populated with the parent's ID..execute(): commits all operations atomically, parent records before their children. After each parent inserts, the framework populates its children's lookup fields. If any operation fails, all are rolled back.TransactionResult: containsisSuccess(),getInsertedIds(),getErrors(),getSuccessCount(),getFailureCount()andgetFailureMessage().getFailureMessage()gives the reason a save failed when no error reached your code. There are two such cases: a failure that.suppressExceptions()turned into a failed result, and an error that stopped a save made with.allowPartial(). In both,isSuccess()is false.- Neither case gives row results, so
getErrors()does not show the reason. When a partial save only refuses some rows,getFailureMessage()returns null: read each row's reason fromgetErrors().
Something went wrong? See Common Issues, Step 2.
Step 3: Write Tests
The test class checks the service three ways: with two Contacts, with one, and with none. You create the empty class with one command, paste the code into it, send it to your org, then run it.
1. In the terminal, from your project's top folder, create the empty test class:
sf apex generate class --name SVC_AccountOnboarding_TEST --output-dir force-app/main/default/classesYou should see two files created in force-app/main/default/classes: SVC_AccountOnboarding_TEST.cls and its companion of the same name ending in .cls-meta.xml.
2. In your editor, open this file, delete what is there, paste the code below in exactly as it is, and save:
force-app/main/default/classes/SVC_AccountOnboarding_TEST.cls/**
* @description Unit tests for SVC_AccountOnboarding.
*
* @see SVC_AccountOnboarding
*
* @author your.name@company.com
*
* @group Services
*
* @date February 2026
*/
@SuppressWarnings('PMD.ApexUnitTestClassShouldHaveRunAs')
@IsTest(isParallel=true)
private class SVC_AccountOnboarding_TEST
{
/** @description Tests that an Account is created with Contacts and an Opportunity. */
@IsTest
private static void shouldCreateAccountWithRelatedRecords()
{
List<String> contactLastNames = new List<String>{ 'Smith', 'Jones' };
kern.DML_Builder.TransactionResult result =
new SVC_AccountOnboarding().createAccount('Test Corp', contactLastNames, 'Test Deal');
Assert.isTrue(result.isSuccess(), 'Transaction should succeed');
Assert.areEqual(4, result.getSuccessCount(), 'Should insert 4 records (1 Account + 1 Opportunity + 2 Contacts)');
// Verify parent-child relationships using QRY_Builder
List<Contact> contacts = kern.QRY_Builder.selectFrom(Contact.SObjectType)
.fields(new List<SObjectField>{ Contact.LastName, Contact.AccountId })
.condition(Contact.AccountId).equals(result.getInsertedIds()[0])
.toList();
Assert.areEqual(2, contacts.size(), 'Should create two Contacts');
List<Opportunity> opportunities = kern.QRY_Builder.selectFrom(Opportunity.SObjectType)
.fields(new List<SObjectField>{ Opportunity.Name, Opportunity.AccountId })
.condition(Opportunity.AccountId).equals(result.getInsertedIds()[0])
.toList();
Assert.areEqual(1, opportunities.size(), 'Should create one Opportunity');
Assert.areEqual('Test Deal', opportunities[0].Name, 'Opportunity name should match');
}
/** @description Tests that the transaction result contains the inserted IDs. */
@IsTest
private static void shouldReturnInsertedIds()
{
kern.DML_Builder.TransactionResult result =
new SVC_AccountOnboarding().createAccount('ID Test Corp', new List<String>{ 'Doe' }, 'ID Deal');
Assert.isTrue(result.isSuccess(), 'Transaction should succeed');
List<Id> insertedIds = result.getInsertedIds();
Assert.areEqual(3, insertedIds.size(), 'Should return 3 inserted IDs');
Assert.isTrue(result.getErrors().isEmpty(), 'Should have no errors');
}
/** @description Tests that the service handles an empty contact list. */
@IsTest
private static void shouldCreateAccountWithNoContacts()
{
kern.DML_Builder.TransactionResult result =
new SVC_AccountOnboarding().createAccount('Solo Corp', new List<String>(), 'Solo Deal');
Assert.isTrue(result.isSuccess(), 'Transaction should succeed');
Assert.areEqual(2, result.getSuccessCount(), 'Should insert 2 records (1 Account + 1 Opportunity)');
List<Contact> contacts = kern.QRY_Builder.selectFrom(Contact.SObjectType)
.fields(new List<SObjectField>{ Contact.LastName })
.condition(Contact.AccountId).equals(result.getInsertedIds()[0])
.toList();
Assert.isTrue(contacts.isEmpty(), 'Should have no Contacts');
}
}3. In the terminal, send the test class to your org:
sf project deploy start -o YourOrgAlias -m "ApexClass:SVC_AccountOnboarding_TEST"You should see Status: Succeeded, with SVC_AccountOnboarding_TEST listed as created.
4. In the terminal, run the test:
sf apex run test -o YourOrgAlias -t SVC_AccountOnboarding_TEST --code-coverage --synchronous --result-format humanYou should see 3 tests passing and 100% coverage on SVC_AccountOnboarding: all three tests show Pass, the summary line Outcome reads Passed, and the coverage table shows SVC_AccountOnboarding at 100%.
About the annotations:
@IsTest(isParallel=true)enables parallel test execution (faster runs).SeeAllDatadefaults tofalse, so we omit it.@SuppressWarnings('PMD.ApexUnitTestClassShouldHaveRunAs')turns off a code-quality warning aboutSystem.runAs(), which is fine for quick starts. In production tests, consider addingSystem.runAs()to verify profile and permission set access.
Something went wrong? See Common Issues, Step 3.
Tier 3: Production Patterns (~5 minutes)
All DML Operations
DML_Builder supports every DML operation. See the DML Guide for the full API reference including upsert by external ID, undelete, and bulk patterns.
In Salesforce, run this in an Execute Anonymous window to see insert, update, and delete in a single transaction:
Account newAccount = new Account(Name = 'DML Demo Corp', Phone = '555-0100');
kern.DML_Builder.TransactionResult insertResult = kern.DML_Builder.newTransaction()
.doInsert(newAccount)
.execute();
System.debug('Insert success: ' + insertResult.isSuccess());
System.debug('Account Id: ' + newAccount.Id);
newAccount.Industry = 'Technology';
kern.DML_Builder.TransactionResult updateResult = kern.DML_Builder.newTransaction()
.doUpdate(newAccount)
.execute();
System.debug('Update success: ' + updateResult.isSuccess());
kern.DML_Builder.TransactionResult deleteResult = kern.DML_Builder.newTransaction()
.doDelete(newAccount)
.execute();
System.debug('Delete success: ' + deleteResult.isSuccess());You should see these lines in the log, with your record's Id in place of 001...:
Insert success: true
Account Id: 001...
Update success: true
Delete success: trueSomething went wrong? See Common Issues, All DML Operations.
TransactionResult
Inspect the result after execute().
In Salesforce, in an Execute Anonymous window, run:
Account validAccount = new Account(Name = 'Valid Corp', Phone = '555-0100');
Account invalidAccount = new Account(); // Name is required — will fail
kern.DML_Builder.TransactionResult result = kern.DML_Builder.newTransaction()
.doInsert(validAccount)
.doInsert(invalidAccount)
.allowPartial()
.execute();
System.debug('Overall success: ' + result.isSuccess());
System.debug('Inserted IDs: ' + result.getInsertedIds());
System.debug('Success count: ' + result.getSuccessCount());
System.debug('Failure count: ' + result.getFailureCount());
for(Database.Error error : result.getErrors())
{
System.debug('Error: ' + error.getMessage());
}You should see these lines in the log, with your record's Id in place of 001...:
Overall success: false
Inserted IDs: (001...)
Success count: 1
Failure count: 1
Error: Required fields are missing: [Name]Partial Success
By default, DML is all-or-nothing: if one record fails, all are rolled back. Chain .allowPartial() to save the valid records and log the failures instead.
In Salesforce, in an Execute Anonymous window, run:
List<Account> mixedAccounts = new List<Account>
{
new Account(Name = 'Good Account 1', Phone = '555-0100'),
new Account(),
new Account(Name = 'Good Account 2', Phone = '555-0100')
};
kern.DML_Builder.TransactionResult result = kern.DML_Builder.newTransaction()
.doInsert(mixedAccounts)
.allowPartial()
.execute();
System.debug('Succeeded: ' + result.getSuccessCount());
System.debug('Failed: ' + result.getFailureCount());
System.debug('Inserted IDs: ' + result.getInsertedIds());You should see these lines in the log, with your records' Ids in place of 001...:
Succeeded: 2
Failed: 1
Inserted IDs: (001..., 001...)Failed records are automatically logged via LOG_Builder. To see them, open App Launcher > Kern > Log Entries.
Something went wrong? See Common Issues, Partial Success.
Security, Sharing, Suppression, and Async
These are situational patterns. See the DML Guide for detailed examples.
Default access mode. By default, kern.DML_Builder.newTransaction() runs in AccessLevel.USER_MODE: it saves data with the current user's read/write permissions and record sharing enforced, rather than skipping those checks (the alternative, SYSTEM_MODE).
- In practice, CRUD (object create/read/update/delete permissions) and FLS (field-level security) are both checked against the running user, and sharing rules are honoured.
- This safe default is controlled by the
UserModeDml_Enabledfeature flag, which ships set totrue.
To change it on a single call:
| Call | What it does |
|---|---|
.withSystemMode() | Overrides the default and skips the CRUD and FLS checks. |
.withUserMode() | Makes USER_MODE explicit, even when the flag is on. |
.bypassSharing() | Affects sharing only: it does NOT turn off the CRUD and FLS enforcement that USER_MODE provides. |
With .bypassSharing():
- If the user cannot create or edit a field, the save leaves that field out without an error, and one warning in the log names it.
- If the user lacks the object permission this save needs (create, edit, delete or undelete), the save is refused.
- To save such a field, add
.withSystemMode()too.
See Security Guide: Safe by Default.
In your editor, in your own Apex, where records is the list of records you are saving:
// Explicit USER_MODE (redundant when the flag is on, belt-and-braces otherwise)
kern.DML_Builder.newTransaction().doUpdate(records).withUserMode().execute();
// Bypass CRUD/FLS (framework-owned records that must run as system)
kern.DML_Builder.newTransaction().doUpdate(records).withSystemMode().execute();
// Bypass sharing rules (still enforces CRUD/FLS when USER_MODE default is on)
kern.DML_Builder.newTransaction().doUpdate(records).bypassSharing().execute();
// Suppress exceptions (log instead of throw)
kern.DML_Builder.newTransaction().doInsert(records).suppressExceptions().execute();
// Async DML (returns void; fire-and-forget background job)
kern.DML_Builder.newTransaction().doUpdate(records).async().withBatchSize(200).execute();
// Suppress automatic error logging
kern.DML_Builder.newTransaction().doInsert(records).allowPartial().suppressLogging().execute();To keep the log but soften a refusal you expect, declare it: in partial-success mode the declared refusal is logged at WARN and everything else at ERROR.
In your editor, in your own Apex:
// A duplicate here is expected, so it lands in the log at WARN
kern.DML_Builder.newTransaction().doInsert(records).allowPartial().expectRefusal(StatusCode.DUPLICATE_VALUE).execute();Four of the choices above travel with a background job:
- the access mode (
.withUserMode()/.withSystemMode()) - partial success (
.allowPartial()) - the sharing bypass (
.bypassSharing()): if you do not call it, the background job enforces record sharing - the expected refusals you declared (
.expectRefusal())
.suppressExceptions() and .suppressLogging() do not travel: they shape the result the synchronous call hands back, and a background job has no caller waiting for one, so its failures are always logged.
Clean up
If you built this example only to try the framework, run this command when you have finished the guide. The records the Apex above inserted stay: the Quick Test, Parent Co, Acme Corp, Valid Corp, Good Account 1 and Good Account 2 Accounts, with the Contacts and the Opportunity linked to them; delete them in the app, or leave them.
In the terminal, delete the service and its test class:
sf project delete source -o YourOrgAlias -m "ApexClass:SVC_AccountOnboarding_TEST" -m "ApexClass:SVC_AccountOnboarding" --no-promptYou should see Status: Succeeded, then a Deleted Source table listing the two classes.
The command deletes 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.
Parent-Child Insert
Contact AccountId: null
The Contact was registered with .doInsert(newContact) alone, so the framework was never told which field links it to which parent. Register it with the lookup field and the parent: .doInsert(child, Contact.AccountId, parent).
Method does not exist or incorrect signature: void doInsert(Contact, Id, Account) from the type kern.DML_Builder
The code stops before it runs. A variable named contact shadows the Contact type (Apex ignores case), so Contact.AccountId reads that variable's field value, an Id, instead of the field token. Rename the variable, for example to newContact, as the naming tip above says.
Step 1: Create the Service Class
The deploy says there is nothing to deploy
The deploy stops with No source-backed components present in the package. The command ran inside another project's folder, so the CLI looked for the class there and found nothing. Open the terminal in your own project's top folder, the one that holds sfdx-project.json, and run the command again.
Step 2: Execute
Variable does not exist: result
The code stops before it runs. The second snippet ran on its own, and it uses result from the first. Paste both snippets into one Execute Anonymous window and run them together.
Step 3: Write Tests
The deploy fails
The test class's deploy fails for the same reasons as the service's; see the entries under Step 1.
All DML Operations
cannot specify Id in an insert call
Register all the operations, then execute once; for more work afterwards, start a new transaction with kern.DML_Builder.newTransaction(), as the code above does.
The cause: the code called execute() a second time on the same transaction. That runs the registered operations again, and the records it inserted the first time now have Ids, so the insert is refused with a message that starts System.DmlException: Insert failed.
Partial Success
System.DmlException: Insert failed.
Chain .allowPartial() to save the valid records and read the failures from the result, or .suppressExceptions() to log the failure instead of throwing it.
The cause: a transaction is all-or-nothing by default. One record failed, so nothing was saved and the error stopped your code. The message goes on to name the failing row and the reason, for example Required fields are missing: [Name].
If the reason is cannot specify Id in an insert call, see All DML Operations.
Clean up
No ApexClass named: SVC_AccountOnboarding found
The command shows Status: Failed and a Component Failures table with this line, and the same for SVC_AccountOnboarding_TEST. The org no longer holds the classes: the clean-up already ran, or they were deleted another way. There is nothing left to delete.
Still stuck? Tell us which step and what you saw.
What You Now Know
After completing this guide, you understand the DML builder pattern in KernDX:
| Concept | What It Does |
|---|---|
DML_Builder | One builder for all DML operations; it replaces direct insert/update/delete |
.doInsert(child, field, parent) | Auto-populates foreign keys after parent insert |
.execute() | Commits all operations atomically: parents before children |
TransactionResult | Tells you what happened after a save: isSuccess(), getInsertedIds(), getErrors(), counts |
Key patterns:
- Always use
DML_Builder, not direct DML: the framework provides automatic error logging. - One
execute()per transaction: register all operations first, then execute once. TransactionResult: always checkisSuccess()when using.allowPartial()or.suppressExceptions().- Linking each child to its parent, and
publicvisibility: see Why it works in Step 2 and "Whypublic?" in Step 1.