For about fifteen years, Apex that shared an Account, Case or Opportunity had one option for RowCause: Manual. Salesforce deletes Manual shares when the record owner changes, so every reassignment removed access your code had granted. Winter '27 lets you define custom row causes (Apex sharing reasons) on standard objects, and it adds an org setting, Keep Manual Shares When Transferring Records, aimed at a related but different problem. This post covers defining the reason, moving AccountShare and CaseShare code onto it, cleaning up the old rows, and deciding where the setting belongs.
If share objects are new to you, read the Apex managed sharing guide first.
Why Manual shares vanished on owner change
The Apex Developer Guide's "Understanding Sharing" page long stated that Apex sharing reasons and Apex managed sharing recalculation were available for custom objects only. On a standard object, a share row inserted from Apex got RowCause = 'Manual' by default, the same value a user creates with the Sharing button. When ownership changes, the platform removes Manual rows (and only Manual rows) on the assumption that the old owner granted them. The "Sharing a Record Using Apex" page now lists Apex managed sharing recalculation as supported on standard objects as well.
The old-owner assumption breaks for integration code. A service that gives a key account team Edit access on an Account loses that access the moment a territory realignment moves the Account. Most teams ended up with an after-update trigger that spots an OwnerId change and rebuilds the shares, a nightly batch that recalculates everything from a source of truth and accepts up to a day of missing access, or nothing at all, in which case access disappears until someone raises a ticket. On a large Data Loader transfer, a re-share trigger can hit the CPU limit and roll back the whole batch, and the usual response is to disable the trigger, which leaves the team without access until the nightly job runs.
The IdeaExchange request "Allow Custom RowCause values for Standard Objects (Ie AccountShare)" sat open for years before Winter '27 shipped it.
Define a custom row cause on a standard object
Salesforce said Metadata API support for custom row causes on standard objects would reach all orgs by the end of October 2026. You define them with the same SharingReason type you already use on custom objects. The "Sharing a Record Using Apex" page now says that on standard objects you create sharing reasons with the Metadata API or Tooling API; the point-and-click UI still covers custom objects only, in Salesforce Classic. Salesforce said Setup management would follow in November, but whether it is live in a given org is not yet confirmed. Keep the definition in source control either way.
Here is a reason for a key account team on Account, in source format:
<?xml version="1.0" encoding="UTF-8"?>
<!-- force-app/main/default/objects/Account/sharingReasons/Key_Account_Team__c.sharingReason-meta.xml -->
<SharingReason xmlns="http://soap.sforce.com/2006/04/metadata">
<label>Key Account Team</label>
</SharingReason>
The manifest member is Object.ReasonName__c. This manifest also deploys a Case reason used later in the post:
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>Account.Key_Account_Team__c</members>
<members>Case.Escalation_Engineer__c</members>
<name>SharingReason</name>
</types>
<version>68.0</version>
</Package>
Use 68.0 (Winter '27) or later; older API versions may not accept SharingReason members on standard objects.
sf project deploy start --manifest manifest/package.xml --target-org staging
Migrate share code and clean up legacy Manual rows
Point new shares at the row cause
The code change is small: set RowCause to the reason's API name. On custom objects you would normally reference Schema.Obj__Share.RowCause.Reason__c. I have not confirmed that Schema.AccountShare.RowCause.Key_Account_Team__c compiles for standard objects, so this example uses a string constant.
public without sharing class KeyAccountSharing {
public static final String ROW_CAUSE = 'Key_Account_Team__c';
// Returns "accountId:userId" keys for every share that was written successfully.
public static Set<String> grant(List<Key_Account_Member__c> members) {
List<AccountShare> shares = new List<AccountShare>();
for (Key_Account_Member__c m : members) {
shares.add(new AccountShare(
AccountId = m.Account__c,
UserOrGroupId = m.User__c,
AccountAccessLevel = 'Edit',
OpportunityAccessLevel = 'Read',
CaseAccessLevel = 'Read',
RowCause = ROW_CAUSE
));
}
Set<String> granted = new Set<String>();
Database.SaveResult[] results = Database.insert(shares, false);
for (Integer i = 0; i < results.size(); i++) {
if (results[i].isSuccess()) {
granted.add(shares[i].AccountId + ':' + shares[i].UserOrGroupId);
} else {
System.debug(LoggingLevel.ERROR, 'Share failed for ' + shares[i].AccountId
+ ': ' + results[i].getErrors()[0].getMessage());
}
}
return granted;
}
}
AccountShare requires AccountAccessLevel, OpportunityAccessLevel and CaseAccessLevel. Add ContactAccessLevel only when the Contact org-wide default is not Controlled by Parent. CaseShare needs CaseId, UserOrGroupId, CaseAccessLevel, and here RowCause = 'Escalation_Engineer__c'.
Revoking gets safer too. Your delete query can filter on your own reason, so it can no longer remove a share that a person created:
SELECT Id FROM AccountShare
WHERE AccountId IN :accountIds
AND UserOrGroupId IN :userIds
AND RowCause = 'Key_Account_Team__c'
Flow can assign a custom row cause as well, so a record-triggered flow that creates CaseShare rows should set the reason in its Create Records element. Salesforce's own advice is to switch any code, Flow or integration that creates shares on standard objects to a custom row cause. If your code shares to roles or public groups, the same reason applies; that pattern is covered in sharing to roles and groups with async recalculation.
Move the rows you already have
Every share your code wrote before this release is still Manual. RowCause can't be updated on an existing share (the Apex Developer Guide says 'This field can't be updated'), and Salesforce's announcement describes no automatic conversion, so you migrate those rows yourself. RowCause cannot tell you which Manual rows came from code and which came from people, so you need your own source of truth. Here that is the Key_Account_Member__c junction, narrowed by LastModifiedById for the integration user that ran the old code.
Insert the new rows first and delete the old ones second, so nobody loses access partway through. Delete a Manual row only if its replacement was written successfully.
public without sharing class MigrateKeyAccountShares implements Database.Batchable<SObject> {
private final Id integrationUserId;
public MigrateKeyAccountShares(Id integrationUserId) {
this.integrationUserId = integrationUserId;
}
public Database.QueryLocator start(Database.BatchableContext bc) {
return Database.getQueryLocator(
[SELECT Account__c, User__c FROM Key_Account_Member__c WHERE Active__c = true]
);
}
public void execute(Database.BatchableContext bc, List<Key_Account_Member__c> scope) {
Set<Id> accountIds = new Set<Id>();
Set<Id> userIds = new Set<Id>();
for (Key_Account_Member__c m : scope) {
accountIds.add(m.Account__c);
userIds.add(m.User__c);
}
Set<String> granted = KeyAccountSharing.grant(scope);
List<AccountShare> legacy = new List<AccountShare>();
for (AccountShare s : [
SELECT Id, AccountId, UserOrGroupId FROM AccountShare
WHERE RowCause = 'Manual'
AND AccountId IN :accountIds
AND UserOrGroupId IN :userIds
AND LastModifiedById = :integrationUserId
]) {
if (granted.contains(s.AccountId + ':' + s.UserOrGroupId)) {
legacy.add(s);
}
}
delete legacy;
}
public void finish(Database.BatchableContext bc) {}
}
Run it with a modest scope, for example Database.executeBatch(new MigrateKeyAccountShares(integrationUserId), 200);, and repeat the pattern against CaseShare for the escalation reason.
Custom row cause or Keep Manual Shares
Winter '27 also adds Keep Manual Shares When Transferring Records in Sharing Settings. With it on, the org keeps manual shares when ownership changes, including the Manual rows your old code wrote. The setting fixes the symptom with one checkbox, but it changes behaviour for every manual share in the org.
Some business processes depend on a transfer removing access, such as a case moving between regions or an Account handed over from a departing rep. Salesforce's architect guidance for the setting says the same thing: before enabling it, confirm which processes rely on ownership changes to remove access, document the exceptions, and check that retained shares fit your least-privilege strategy. It also says to revisit Apex, Flow, batch and scheduled jobs that recreate shares after transfers. A custom row cause leaves people's manual shares exactly as they are, and the reason name tells an admin why each user has access.
| Custom row cause | Keep Manual Shares setting | |
|---|---|---|
| Scope | Shares written with that reason only | Every manual share in the org |
| Survives owner change | Yes | Yes, for manual shares |
| Changes how users' manual shares behave | No | Yes |
| Can be revoked separately from human shares | Yes, filter on RowCause |
No, both are Manual |
| Effort | Metadata, code change, migration batch | One checkbox plus a policy review |
| Visible reason for access | Named reason per share | Shows only as Manual |
My recommendation: give everything that code or Flow creates its own row cause, and make the org setting a separate decision about how people share records. The row cause costs a sprint and a migration. The setting takes a minute, but you live with its least-privilege consequences until someone turns it off. Once your code stops writing Manual rows, the setting only affects human sharing.
Retire the workarounds and rewrite the tests
Remove things in this order: deploy the reason, deploy the new grant code, run the migration, confirm no integration-owned Manual rows remain, and only then delete the owner-change trigger. If you have a nightly rebuild batch, strip out the part that repairs transfer damage. You may still want a reconciliation job if junction records can change without going through your sharing service.
Replace tests that asserted the re-share trigger fired with one that proves the share survives a transfer on its own:
@IsTest
private class KeyAccountSharingTest {
@IsTest
static void shareSurvivesOwnerChange() {
Id profileId = [SELECT Id FROM Profile WHERE Name = 'Standard User' LIMIT 1].Id;
User member = buildUser(profileId, 'kam');
User newOwner = buildUser(profileId, 'own');
insert new List<User>{ member, newOwner };
Account acc = new Account(Name = 'Globex Holdings');
insert acc;
Key_Account_Member__c link = new Key_Account_Member__c(
Account__c = acc.Id, User__c = member.Id, Active__c = true);
insert link;
KeyAccountSharing.grant(new List<Key_Account_Member__c>{ link });
Test.startTest();
acc.OwnerId = newOwner.Id;
update acc;
Test.stopTest();
List<AccountShare> shares = [
SELECT Id FROM AccountShare
WHERE AccountId = :acc.Id
AND UserOrGroupId = :member.Id
AND RowCause = :KeyAccountSharing.ROW_CAUSE
];
Assert.areEqual(1, shares.size(), 'Key account share should survive the transfer');
}
private static User buildUser(Id profileId, String alias) {
String unique = alias + DateTime.now().getTime();
return new User(
ProfileId = profileId, Alias = alias, LastName = alias,
Email = unique + '@example.com', Username = unique + '@example.com.test',
TimeZoneSidKey = 'America/New_York', LocaleSidKey = 'en_US',
EmailEncodingKey = 'UTF-8', LanguageLocaleKey = 'en_US'
);
}
}
Add a second test that inserts a Manual share, transfers the record, and asserts whatever your org currently does with it. If someone later flips Keep Manual Shares, that test fails in CI and the change gets a conversation before it reaches production.
What to watch for
- Every share your code wrote before this release is still Manual. RowCause can't be updated on an existing share (the Apex Developer Guide says 'This field can't be updated'), and Salesforce's announcement describes no automatic conversion, so you migrate those rows yourself.
- The Apex Developer Guide's "Sharing a Record Using Apex" page now says Apex managed sharing recalculation is supported for both custom and standard objects, although the older "Understanding Sharing" page still says custom objects only. Test a recalculation class in a sandbox before you depend on it.
- Setup management of standard-object sharing reasons was announced for November and is not confirmed in every org. Deploy through the Metadata API or Tooling API.
- The Apex Developer Guide says only users with Modify All Data can add or change Apex managed sharing on a record. Check who your code or flow runs as.
- A share that grants no more than the org-wide default already gives will fail to insert. The test above assumes a Private Account default, so adjust it if your org is more open.
- If a person and your integration both shared the same record with the same user, there may be only one Manual row. Deleting it during migration also removes the human grant, so filter on
LastModifiedByIdand spot-check high-value Accounts first. - Keep the reason name as a string until you have confirmed that the
Schemaconstant compiles.
Leave a Comment