SharingReason

Represents an Apex sharing reason, which is used to indicate why sharing was implemented for a standard or custom object. Apex managed sharing allows developers to use Apex to programmatically share custom objects. When you use Apex managed sharing to share an object, only users with the “Modify All Data” permission can add or change the sharing on the object's record, and the sharing access is maintained when the record owner changes or is deactivated. Sharing reasons for standard objects are available for objects that have a corresponding share object (for example, AccountShare, OpportunityShare) and whose org-wide default can be set to Private or Public Read-Only. Objects on the detail side of a master-detail relationship, which have no share object of their own, aren't supported.

Use SharingReason to create, update, or delete sharing reason definitions for a custom object. This type extends the Metadata metadata type and inherits its fullName field.

Version

Sharing reasons for custom objects are available in API version 14.0 and later. Sharing reasons for standard objects are available in API version 68.0 and later.

Fields

Field	Field Type	Description
fullName	string	Required. Sharing reason name. The __c suffix is appended to custom sharing reasons. Inherited from Metadata, this field is defined in the WSDL for this metadata type. It must be specified when creating, updating, or deleting. See `createMetadata()` to see an example of this field specified for a call.
label	string	Required. Descriptive label for the sharing reason. Maximum of 40 characters.

Usage

Example

A maximum of 10 custom sharing reasons can be created per standard object.
Reserved row cause names (for example, Manual, Team, Sharing Rule, Record Collection) can't be used as sharing reason names.
Deleting a sharing reason deletes all share records on that object that use the reason. This can revoke access for users, so treat deletion as a destructive change.

Declarative Metadata Sample Definition

The definition of a sharing reason in a custom object:

1<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
2. . .
3    <sharingReasons>
4        <fullName>recruiter__c</fullName>
5        <label>Recruiter</label>
6    </sharingReasons>
7 . . .
8</CustomObject>

Managed Package Support

Sharing reasons for standard and custom objects can be included in second-generation managed packages. On install, the fullName is prefixed with the package namespace (for example, myns__Compliance_Team). Packaged sharing reasons are locked in the subscriber org, so subscribers can't edit the label or developer name, or delete the reason directly. Uninstalling a package that contains sharing reasons deletes those reasons and all associated shares.

Wildcard Support in the Manifest File

This metadata type doesn’t support the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.

Metadata API Developer Guide