3- Programmatic Sharing

Programmatic Apex Sharing

Copyright © Walid El Horr 1

Programmatic Apex Sharing
• Topics covered in this lecture:

• Apex Managed Sharing Overview

• Share Object and Share Object Columns

• Sharing Reasons

• Creating Share Object records using Apex

Copyright © Walid El Horr 2

Apex Managed Sharing Overview

• Allows to open up record access through code

• Apex Managed Sharing allows developers to build sophisticated and dynamic sharing settings

• Available for objects with a default OWD of ‘Private’ or ‘Public Read Only’

• Only users with Modify All Data permission can add or change Apex managed sharing on a record

Copyright © Walid El Horr 3

Share Object

• A Share object exists for a Salesforce object if the OWD sharing settings for this object is
restrictive: Private or Public Read only

• If an Object is Public Read/Write, the Share object table has 0 records; there is no need to share as it
is already publicly Read/Write

• Objects on the detail side of a master-detail relationship do not have an associated sharing object.
The detail record’s access is determined by the master’s sharing object.

Copyright © Walid El Horr 4

Share Object

• A share object includes records supporting:

• Explicit Sharing:

• Managed sharing (record ownership and Sharing Rules)

• User managed sharing (manual sharing by the owner or a User with Full Access permission on the record)

• Apex managed sharing

• Implicit sharing

• Apex Managed Sharing is creating records in the Share object through Apex

Copyright © Walid El Horr 5

Share Object

• For standard Objects:

• Share object is defined as ObjectNameShare. Example: OpportunityShare.

• The Share object has 0 records until you make the object OWD restrictive

• For custom Objects:

• Share object is defined as CustomObjectName__Share. Example: Invoice__Share.

• There is no Share object until you make the object OWD restrictive

Copyright © Walid El Horr 6

Share Object

• Opportunity OWD is Public Read Write

• SOQL Query
SELECT Id
FROM OpportunityShare

• Change the Opportunity OWD to

Public Read and run the query again

Copyright © Walid El Horr 7

Share Object

• Let’s add a more detailed query

• SOQL Query
SELECT Id, OpportunityAccessLevel,
OpportunityId, RowCause,
UserOrGroupId
FROM OpportunityShare

Copyright © Walid El Horr 8

OpportunityShare Object Fields
Field Description Example
Id Id of the sharing record 00t1U000006oIYPQA2

OpportunityAccessLevel The level of access that the specified user or All

group has been granted for a share sObject.
Values are:
• Edit
• Read
• All (only used by managed sharing)
This field must be set to an access level
that is higher than the OWD

OpportunityId The Id of the specific Opportunity record to 0061U000002szd9QAA

share

Copyright © Walid El Horr 9

OpportunityShare Object Fields
Field Description Example
RowCause The reason why the user or group is being Owner
granted access. The reason determines the
type of sharing, which controls who can
alter the sharing record. Values for this field
cannot be updated for Standard objects.

UserOrGroupId The user or group IDs to which you are 0051U0000010NTwQAM

granting access. Group can be: public
group, sharing group associated with a role.
This field cannot be updated.

Copyright © Walid El Horr 10

Share Object

• SOQL Query

SELECT Id, OpportunityAccessLevel,

OpportunityId, RowCause,
UserOrGroupId
FROM OpportunityShare

Copyright © Walid El Horr 11

Custom Objects Share Object Fields

• In custom sharing tables, Salesforce uses:

• AccessLevel instead of StandardObjectNameAccessLevel (OpportunityAccessLevel)

• ParentId instead of StandardObjectNameId (OpportunityId)

• SOQL Query
SELECT Id, AccessLevel,
ParentId, RowCause,
UserOrGroupId
FROM Invoice__Share

Copyright © Walid El Horr 12

RowCause

• RowCause explains the reason the record is shared to the specified User or Group

• Standard Share objects like OpportunityShare will NOT have write access on RowCause field

RowCause Description
Owner The specified User is the record owner
ImplicitParent A child record related to this record is owned by the specified User
Team The specified User is a Team member (ex. Account Team)
Manual Sharing was manually granted to the specified User
TerritoryManual The Account record was manually assigned to a Territory
Territory A Territory assignment rule granted access for this Account to the specified Group
Apex sharing Only available for custom objects
reason

Copyright © Walid El Horr 13

Apex sharing reason

• Only available for Custom objects, not Standard

• Set from the Object settings in Classic

• You can create Apex sharing reasons using the Metadata

API.

• You can create up to 10 Apex sharing reasons per object.

• Once created, reason can be used in Apex Sharing

Copyright © Walid El Horr 14

Apex sharing reason

• Deleting an Apex sharing reason will delete all sharing on

the object that uses it

• Share records written using Apex contains

RowCause="Manual" by default.

• When ownership changes, Only shares with

RowCause="Manual" are removed

Copyright © Walid El Horr 15

Apex sharing reason

• All Apex sharing reason names have the following format:

MyReasonName__c

• Apex sharing reasons can be referenced in Apex as follows

Schema.CustomObject__Share.rowCause.SharingReason__c

• For example, an Apex sharing reason called Recruiter for

an object called Job can be referenced as follows:

Schema.Job__Share.rowCause.Recruiter__c

Copyright © Walid El Horr 16

Reasons for Using Apex Managed Sharing

• Best practice is to always use declarative sharing

• Standard sharing functionality is not sufficient, and sharing logic is too complex to be
established declaratively.

• Sharing rules depend on a combination of values across multiple objects.

• Sharing access is criteria-based but the evaluated field isn’t supported by declarative sharing

• All attempts to share declaratively have failed

Copyright © Walid El Horr 17

Steps for Apex Managed Sharing

1. Sharing Reason must first be defined for the custom object:

• these can be created by navigating to the ‘Apex Sharing Reasons’ related list of an object.

• Each Apex sharing reason has a label and a name.

Copyright © Walid El Horr 18

Steps for Apex Managed Sharing

2. While creating Apex code for sharing a record, the following fields must be defined:

• ParentId corresponds to the record being shared.

• UserOrGroupId is the ID of the user or public group to whom access is being granted.

• AccessLevel can be either ‘Read’ or ‘Edit’ or ‘All’.

• RowCause is used for specifying the reason why the user or group is being granted access.
Note that either a custom or ‘Manual’ RowCause can be used in Apex code to create records
in share tables. If left blank, it will be ‘Manual’

Copyright © Walid El Horr 19

Apex Managed Sharing Examples

• Standard Object
OpportunityShare oppShare = new OpportunityShare();
oppShare.OpportunityAccessLevel = 'Read';
oppShare.OpportunityId = '0061U000002szd9QAA';
oppShare.UserOrGroupId = '0051U0000010dxpQAA';
oppShare.RowCause = Schema.OpportunityShare.RowCause.Manual; //optional – Manual is default
insert oppShare;

Copyright © Walid El Horr 20

Apex Managed Sharing Examples

• Custom Object
Invoice__Share invShare
OpportunityShare oppShare
= new= new
Invoice__Share();
OpportunityShare();
oppShare.OpportunityAccessLevel
invShare.AccessLevel = 'Read'; = 'Read';
oppShare.OpportunityId
invShare.ParentId = 'a001U000000yS7yQAE';
= '0061U000002szd9QAA';
oppShare.UserOrGroupId=='0051U0000010dxpQAA';
invShare.UserOrGroupId '0051U0000010dxpQAA';
oppShare.RowCause==Schema.Invoice__Share.RowCause.Walid_Reason__c;
invShare.RowCause Schema.OpportunityShare.RowCause.Manual; //optional
//optional
– Manual is default
insert invShare;
oppShare;

Copyright © Walid El Horr 21

Apex Managed Sharing Examples

• Example from
the Developer
Guide

• Test Class

• LINK

22
Apex Managed Sharing Considerations

• Only users with ‘Modify All Data’ permission can add, edit or delete apex managed
sharing records.

• A record can be shared multiple times with a user or group using different Apex sharing
reasons.

• When multiple entries in the share object apply for the logged-in user, the most-
permissive rule applies

• Apex managed sharing is maintained across record owner changes if the RowCase is not
‘Manual’

Copyright © Walid El Horr 23

Demo

Demo

Programmatic
Apex Sharing

24
Summary - Programmatic Apex Sharing
Subject Description
Apex Sharing Allows developers to build sophisticated and dynamic sharing settings
Only users with Modify All Data permission can add or change Apex managed sharing on a record
Share Object Apex Managed Sharing is creating records in the Share object through Apex
Standard objects: AccountShare
Custom Object: Invoice__Share
Types of Sharing A share object includes records supporting:
Explicit Sharing (Apex Managed Sharing is here) / Implicit Sharing
Share Object ParentId: corresponds to the record being shared.
Columns UserOrGroupId: is the ID of the user or public group to whom access is being granted.
AccessLevel: can be either ‘Read’ or ‘Edit’.
RowCause: specifies the reason why the user or group is being granted access
Sharing Reason Can only be defined for Custom Objects, and not Standard Object
If the owner of record is changed, all Share records with the Manual reason are deleted
Deleting an Apex sharing reason will delete all sharing on the object that uses it
Example: OppShareRecord.RowCause = Schema.OpportunityShare.RowCause.Manual;

Copyright © Walid El Horr 25

Programmatic Apex Sharing

Thanks for Watching! ☺

Copyright © Walid El Horr 26