Creating Sharing Rules in Apex
Figure 5.8 shows the Force.com managed sharing settings for the Project object, configured in Chapter 3. The sharing rules specify that projects owned by members of one role are shared by all users in that role. This is defined three times because three separate roles exist, one for each region in the sample company.
Navigate to an individual Project record and click the Sharing button. Figure 5.9 is an example of the resulting screen. It lists the sharing rules in effect for this record. The first sharing rule is the default one, specifying that the owner has full control over the record. The second is the sharing rule maintained by Force.com managed sharing, configured using the screen shown in Figure 5.8, which allows users in the same role as the owner (West) to edit the record.
You’ve visited screens in the native user interface where record sharing is taking place. Next, look a level deeper at the data driving the sharing behavior. Open the Force.com IDE’s Schema Explorer and run the query shown in Listing 5.21. It illustrates how Force.com stores the information for the sharing rules in Figure 5.9 and what you will be manipulating with Apex managed sharing.
Listing 5.21 SOQL Query on Project Share Object
SELECT ParentId, UserOrGroupId, AccessLevel
FROM Project__Share
WHERE Parent.Name = 'GenePoint'
Figure 5.10 is the result of running the query. Note that the identifiers in your Force.com organization will be different from those in the figure.
Try to decode the meaning of each record. The ParentId field contains the unique identifier of the record being shared. The query has filtered by the name GenePoint, which is a Project record. The UserOrGroupId field contains the unique identifier of a User or Group record. The AccessLevel field is one of the four access levels (All, None, Edit, View), although only Edit and View can be set using Apex managed sharing.
The first record has All access, so it’s the default sharing rule granting the owner of the record full access. The second record might be a mystery at first. The UserOrGroupId does not match up with the unique identifier of the West region’s role record. Run the query shown in Listing 5.22 to track down the meaning of this value.
Listing 5.22 SOQL Query on Group Object
SELECT Id, Type, RelatedId
FROM Group
The Group object stores information about roles and other groups in Force.com. Figure 5.11 displays the results of the query. The RelatedId field contains the same value as the UserOrGroupId value of the second sharing record. This is where Force.com managed sharing has stored the fact that the Project record named GenePoint is shared with other members of the West role.
Apex managed sharing allows you to insert new rows into the Project__Share object, and other sharing objects, and specify custom sharing reasons that are meaningful to your application. Custom sharing reasons are maintained for each object individually. To try adding one, go to the App Setup area and click Create, Objects and select the Project object. Scroll to the bottom of the page. In the Apex Sharing Reasons list, add a new reason with a label of My Sharing Reason. Force.com automatically suggests a Name, converting spaces to underscores. Refer to the custom sharing reason in your Apex code by adding __c to the end of the name.
Listing 5.23 contains sample code you can run in the Execute Anonymous view. It shares the GenePoint record with an additional user, specifying the custom sharing reason, with Read-only access.
Listing 5.23 Inserting Sharing Rule on Project Object
User carrie = [ SELECT Id FROM User
WHERE Name = 'Carrie Oakey' LIMIT 1 ];
Project__c genePoint = [ SELECT Id FROM Project__c
WHERE Name = 'GenePoint' LIMIT 1 ];
Project__Share share = new Project__Share(
ParentId = genePoint.Id,
UserOrGroupId = carrie.Id,
rowCause = Project__Share.rowCause.My_Sharing_Reason__c,
AccessLevel = 'Read'),
insert share;
After executing this code, refresh the Sharing Details for GenePoint and you should see the screen shown in Figure 5.12. It shows that the new custom sharing rule has been added. Because the sharing rule was created by Apex code and uses a custom sharing reason, it’s preserved across changes of record ownership and cannot be edited or deleted by users unless they have the Modify All Data administrative permission in their profile.
