Sharing a Record Using Apex

To access sharing programmatically, you must use the share object associated with the standard or custom object for which you want to share. For example, AccountShare is the sharing object for the Account object, ContactShare is the sharing object 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 Overview” 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 permissions such as the “View All” and “Modify All” permissions for the given object, “View All Data,” and “Modify All Data” are not tracked with this object.

Every share object has the following properties:

Property Name	Description
`objectNameAccessLevel`	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: `Edit` `Read` `All` The `All` access level can only be used by Force.com managed sharing. Note 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.
`ParentID`	The ID of the object. This field cannot be updated.
`RowCause`	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.
`UserOrGroupId`	The user or group IDs to which you are granting access. A group can be a public group or a sharing group associated with a role or territory. This field cannot be updated.

You can share a standard or custom object with users or groups. Apex sharing is not available for Customer Community users. For more information about the types of users and groups you can share an object with, see User and Group in the Object Reference for Salesforce and Force.com.

Creating User Managed Sharing Using Apex

It is possible to manually share a record to a user or a group using Apex or the SOAP API. If the owner of the record changes, the sharing is automatically deleted. The following example class contains a method that shares the job specified by the job ID with the specified user or group ID with read access. It also includes a test method that validates this method. Before you save this example class, create a custom object called Job.

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. For more information, see Access Levels.

Important

Creating Apex Managed Sharing

Apex managed sharing enables developers to programmatically manipulate sharing to support their application’s behavior through Apex or the SOAP API. This type of sharing is similar to Force.com managed sharing. 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.

Apex managed sharing must use an Apex sharing reason. Apex sharing reasons are a way for developers 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:

Apex sharing reasons can be referenced programmatically as follows:

For example, an Apex sharing reason called Recruiter for an object called Job can be referenced as follows:

For more information, see Schema Class.

To create an Apex sharing reason:

From Setup, click Create | Objects.
Select the custom object.
Click New in the Apex Sharing Reasons related list.
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.
Enter a name for the Apex sharing reason. The name is used when referencing the reason in the API and Apex. This name can contain only underscores and alphanumeric characters, and must be unique in your organization. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
Click Save.

Apex sharing reasons and Apex managed sharing recalculation are only available for custom objects.

Note

Apex Managed Sharing Example

For this example, suppose you are building a recruiting application and have an object called Job. You want to validate that the recruiter and hiring manager listed on the job have access to the record. The following trigger grants the recruiter and hiring manager access when the job record is created. This example requires a custom object called Job, with two lookup fields associated with User records called Hiring_Manager and Recruiter. Also, the Job custom object should have two sharing reasons added called Hiring_Manager and Recruiter.

Under certain circumstances, inserting a share row results in an update of an existing share row. Consider these examples:

If a manual share access level is set to Read and you insert a new one that’s set to Write, the original share rows are updated to Write, indicating the higher level of access.
If users can access an account because they can access its child records (contact, case, opportunity, and so on), and an account sharing rule is created, the row cause of the parent implicit share is replaced by the sharing rule row cause, indicating the higher level of access.