To access sharing programmatically, you must use the share object associated with the standard or custom object for which Sharing a Record Using Apex
for the Contact object, and so on. In addition, all custom object sharing objects are named as follows, where MyCustomObject is the name of the custom object:
MyCustomObject__Share
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 and the relationship’s sharing setting. For more information, see "Custom Object Security" in the Salesforce online help.
A share object includes records supporting all three types of sharing: Force.com managed sharing, user managed sharing, and Apex managed sharing. Sharing granted to users implicitly through organization-wide defaults, the role hierarchy, and profile permissions such as "View All Data" and "Modify All Data" are not tracked with this object.
Every share object has the following properties:
Description Property Name
The level of access that the specified user or group has been granted for a share sObject. The name of the property is AccessLevel appended to the object name. For example, the property name for LeadShare object is LeadShareAccessLevel. Valid values are:
objectNameAccessLevel
• Edit
• Read
• All
Note: The All access level can only be used by Force.com managed sharing.
This field must be set to an access level that is higher than the organization’s default access level for the parent object. For more information, see Access Levels on page 119.
The ID of the object. This field cannot be updated.
ParentID
The reason why the user or group is being granted access. The reason determines the type of sharing, which controls who can alter the sharing record. This field cannot be updated.
RowCause
The user or group IDs to which you are granting access. A group can be a public group, role, or territory. This field cannot be updated.
UserOrGroupId
For more information, see the individual sharing objects in the Force.com Web Services API.
Creating User Managed Sharing Using Apex
It is possible to manually share a record to a user or a group using Apex. If the owner of the record changes, the sharing is automatically deleted. The following class provides an example:
public class JobSharing {
static boolean manualShareRead(Id recordId, Id userOrGroupId){
// Create new sharing object for the custom object Job.
Job__Share jobShr = new Job__Share();
// Set the ID of record being shared.
jobShr.ParentId = recordId;
// Set the ID of user or group being granted access.
jobShr.UserOrGroupId = userOrGroupId;
Sharing a Record Using Apex
// Set the access level.
jobShr.AccessLevel = 'Read';
// Set rowCause to 'manual' for manual sharing.
// This line can be omitted as 'manual' is the default value for sharing objects.
jobShr.RowCause = Schema.Job__Share.RowCause.Manual;
// Insert the sharing record and capture the save result.
// The false parameter allows for partial processing if multiple records passed // into the operation.
Database.SaveResult sr = Database.insert(jobShr,false);
// Process the save results.
if(sr.isSuccess()){
// Indicates success return true;
} else {
// Get first save result error.
Database.Error err = sr.getErrors()[0];
// Check if the error is related to trival access level.
// Access levels equal or more permissive than the object's default // access level are not allowed.
// These sharing records are not required and thus an insert exception is acceptable.
if(err.getStatusCode() == StatusCode.FIELD_INTEGRITY_EXCEPTION &&
// Test for the manualShareRead method
static testMethod void testManualShareRead(){
// Select users for the test.
List<User> users = [select id from user where isActive = true limit 2];
Id user1Id = users[0].Id;
Id user2Id = users[1].Id;
// Create new job.
Job__c j = new Job__c();
j.Name = 'Test Job';
j.OwnerId = user1Id;
insert j;
// Insert manual share for user who is not record owner.
System.assertEquals(manualShareRead(j.Id, user2Id), true);
// Query job sharing records.
List<Job__Share> jShrs = [select id, userOrGroupId, accessLevel,
rowCause from job__share where parentId = :j.Id and userOrGroupId= :user2Id];
// Test for only one manual share on job.
System.assertEquals(jShrs.size(), 1, 'Set the object\'s sharing model to Private.');
// Test attributes of manual share.
System.assertEquals(jShrs[0].accessLevel, 'Read');
System.assertEquals(jShrs[0].rowCause, 'Manual');
System.assertEquals(jShrs[0].userOrGroupId, user2Id);
Sharing a Record Using Apex
delete j;
// Insert manual share for deleted job id.
System.assertEquals(manualShareRead(j.Id, user2Id), false);
} }
Important: The object’s organization-wide default access level must not be set to the most permissive access level.
For custom objects, this is Public Read/Write.
Creating Apex Managed Sharing
Apex managed sharing enables developers to programmatically manipulate sharing to support their application’s behavior.
This type of sharing is similar to Force.com managed sharing, only the application developer manages this sharing using Apex.
Only users with "Modify All Data" permission can add or change Apex managed sharing on a record. Apex managed sharing is maintained across record owner changes.
Note: Apex managed sharing is only available for custom objects.
Apex managed sharing must use an Apex sharing reason. Apex sharing reasons are a way for a developer to track why they shared a record with a user or group of users. Using multiple Apex sharing reasons simplifies the coding required to make updates and deletions of sharing records. They also enable developers to share with the same user or group multiple times using different reasons.
Apex sharing reasons are defined on an object's detail page. Each Apex sharing reason has a label and a name:
• The label displays in the Reason column when viewing the sharing for a record in the user interface. This allows users and administrators to understand the source of the sharing. The label is also enabled for translation through the Translation Workbench.
• The name is used when referencing the reason in the API and Apex.
All Apex sharing reason names have the following format:
MyReasonName__c
Apex sharing reasons can be referenced programmatically 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.Requester__c For more information, see Schema Methods. on page 209 To create an Apex sharing reason:
1. Click Setup ➤ Create ➤ Objects.
2. Select the custom object.
3. Click New in the Apex Sharing Reasons related list.
4. Enter a label for the Apex sharing reason. The label displays in the Reason column when viewing the sharing for a record in the user interface. The label is also enabled for translation through the Translation Workbench.
Sharing a Record Using Apex
5. Enter a name for the Apex sharing reason. The name is used when referencing the reason in the Force.com API and Apex.
The name can only contain numbers, letters, and the underscore (_) character, must start with a letter, and cannot end with an underscore or contain two consecutive underscore characters.
6. Click Save.
Apex Managed Sharing Example
The following example presumes that you are building a recruiting application and have a custom object called Job. You want the recruiter and hiring manager listed on the job to have full access to the record, similar to the record owner. The following trigger grants the recruiter and hiring manager access when the job record is created:
trigger JobApexSharing on Job__c (after insert) { if(trigger.isInsert){
// Create a new list of sharing objects for Job List<Job__Share> jobShrs = new List<Job__Share>();
// Declare variables for recruiting and hiring manager sharing Job__Share recruiterShr;
Job__Share hmShr;
for(Job__c job : trigger.new){
// Instantiate the sharing objects recruiterShr = new Job__Share();
hmShr = new Job__Share();
// Set the ID of record being shared recruiterShr.ParentId = job.Id;
hmShr.ParentId = job.Id;
// Set the ID of user or group being granted access recruiterShr.UserOrGroupId = job.Recruiter__c;
hmShr.UserOrGroupId = job.Hiring_Manager__c;
// Set the access level
recruiterShr.AccessLevel = 'edit';
hmShr.AccessLevel = 'read';
// Set the Apex sharing reason for hiring manager and recruiter recruiterShr.RowCause = Schema.Job__Share.RowCause.Recruiter__c;
hmShr.RowCause = Schema.Job__Share.RowCause.Hiring_Manager__c;
// Add objects to list for insert jobShrs.add(recruiterShr);
jobShrs.add(hmShr);
}
// Insert sharing records and capture save result
// The false parameter allows for partial processing if multiple records are passed // into the operation
Database.SaveResult[] lsr = Database.insert(jobShrs,false);
// Create counter Integer i=0;
// Process the save results
for(Database.SaveResult sr : lsr){
if(!sr.isSuccess()){
// Get the first save result error Database.Error err = sr.getErrors()[0];
// Check if the error is related to a trivial access level
Sharing a Record Using Apex
// These sharing records are not required and thus an insert exception is // acceptable.
if(!(err.getStatusCode() == StatusCode.FIELD_INTEGRITY_EXCEPTION &&
err.getMessage().contains('AccessLevel'))){
// Throw an error when the error is not related to trivial access level.
trigger.newMap.get(jobShrs[i].ParentId).
addError('Unable to grant sharing access due to following exception:
'
+ err.getMessage());
} } i++;
} } }
Important: The object’s organization-wide default access level must not be set to the most permissive access level.
For custom objects, this is Public Read/Write.