Sharing a Record Using Apex

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

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. 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 don’t 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 Help.

A share object includes records supporting all three types of sharing: managed sharing, user managed sharing, and Apex managed sharing. Sharing that is granted to users implicitly through organization-wide defaults, the role hierarchy, and permissions such as the “View All Records” and “Modify All Records” permissions for the given object, “View All Data,” and “Modify All Data” aren’t 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, shown here as a placeholder value. For example, the property name for the LeadShare object is LeadAccessLevel. Valid values are: Edit Read All The All access level is an internal value and can’t be granted. This field must be set to an access level that’s higher than the organization’s default access level for the parent object. For more information, see Understanding Sharing.
ParentID	The ID of the custom object. This field can’t 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 can’t be updated.
UserOrGroupId	The user or group IDs to which you’re granting access. A group can be: A public group or a sharing group associated with a role. A territory group. This field can’t be updated. You can’t grant access to unauthenticated guest users using Apex.

You can share a standard or custom object with users or groups. 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.

It’s possible to manually share a record to a user or a group using Apex or 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.

Manual shares written using Apex contains RowCause="Manual" by default. Only shares with this condition are removed when ownership changes.

The object’s organization-wide default access level must not be set to the most permissive access level. For custom objects, this level is Public Read/Write. For more information, see Understanding Sharing.

Apex managed sharing enables developers to programmatically manipulate sharing to support their application’s behavior through either Apex or SOAP API. This type of sharing is similar to managed sharing. Only users with “Modify All Data” permission can add or change Apex managed sharing on a record. Apex managed sharing is maintained when the record owner changes or is deactivated.

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 aren’t available in Lightning Experience. Use Salesforce Classic to create sharing reasons within the UI. Creating sharing reasons within the UI is only supported for custom objects. For standard objects, sharing reasons are managed through the Metadata API, not through the Salesforce Classic UI. Apex managed sharing recalculation is supported for both custom and standard objects. See Point and Click Customization for the complete list of differences in features and settings between Salesforce Classic and Lightning Experience.

For custom objects, Apex sharing reasons are defined on the object’s detail page. For standard objects, create them using the Metadata API or Tooling API. 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 label 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, where CustomObject__Share and SharingReason__c are placeholder values:

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

For more information, see System.Schema Class.

To create an Apex sharing reason for custom objects:

1. From the management settings for the custom object, click New in the Apex Sharing Reasons related list.
2. 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.
3. 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 org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
4. Click Save.

For standard objects, Apex sharing reasons aren’t created from a detail-page related list. Create them by deploying a sharing reason component through the Metadata API. For the metadata format, see SharingReason in the Metadata API Developer Guide.

Apex sharing reasons are available for custom objects and for standard objects that have an associated share object (for example, AccountShare, OpportunityShare) and whose org-wide default is set to Private or Public Read-Only.

For this example, suppose that you’re 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 must 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:

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

The object’s organization-wide default access level must not be set to the most permissive access level. For custom objects, this level is Public Read/Write. For more information, see Understanding Sharing.

Customer Community Plus users are previously known as Customer Portal users. Share objects, such as AccountShare and ContactShare, aren’t available to these users. If you must use share objects as a Customer Community Plus user, consider using a trigger, which operates with the without sharing keyword by default. Otherwise, use an inner class with the same keyword to enable the DML operation to run successfully. A separate utility class can also be used to enable this access.

Granting visibility via manual or apex shares written to the share objects is supported but the objects themselves aren’t available to Customer Community Plus users. However, other users can add shares that grant access to Customer Community Plus users.

After enabling digital experiences, records accessible to Roles and Subordinates via Apex managed sharing are automatically made accessible to Roles, Internal, and Portal Subordinates. To secure external users’ access, update your Apex code so that it creates shares to the Role and Internal Subordinates group. Because this conversion is a large-scale operation, consider using batch Apex.