,

Record-based Sharing

The previous sections covered the standard security mechanisms that protect your Force Platform environment and the use of permissions to allow access to different pieces of Force Platform functionality, as well as the components you create. These permissions are fairly coarse—you have permission for a type of access to all the records in an object. The Force Platform gives you a way to implement different access to different data records stored in a single object. This type of security is based on individual rows of data, and implemented with a different set of tools and concepts. These tools and concepts are illustrated in the figure below, and the rest of this chapter is dedicated to explaining this chart in more detail.

Object-based and record-based permissions are complementary, not alternate ways to implement access. Object-based permissions allow access to an object and all the records contained within the object. If a user has the permission to access data in an object, access permissions for individual records can be limited through the use of record-based sharing. If a user does not have access to an object, record-based sharing cannot grant access to the object.

Record Ownership

The core concept behind data-based permissions is record ownership. The owner of a record has all privileges for that record—the ability to delete the record, share the record with other users or even transfer ownership of the record.

The owner of a record created through the user interface is, by default, the user who created the record. A record owner always has read and write access to the record, as well as delete, transfer, and the ability to share the record with other users. A queue, which is a collection of users, can also be designated as the owner of a record. You can change the owner of a record, either through the standard Force Platform interface, as shown in the following figure, or with Apex code, the Force Platform procedural language that is the topic of Chapters 10 and 11.

A record can be owned by one or more users, or groups of users. Any owner of a record can transfer ownership of the record to another user by using the Change link next to the name of the owner in the detail page for the record. In addition, any user with the Modify All Data permission, discussed above, has full privileges for all data in all objects.

For the rest of this chapter, the term owner refers to anyone with ownership permissions, including users who have Modify All Data permission and users whose role is above the owner in the role hierarchy.

Organization-wide defaults

To properly implement record-based permissions, you have to follow a two-step process:

1.	Lock down access to all records for an object based on the lowest level of permission that exists in your organization.
2.	Open up access to particular records for particular users.

To lock down records, the Force Platform provides a concept known as organization-wide defaults, usually referred to as org-wide defaults. As the name implies, this specification defines the default access to all records in an object for all users.

There are three settings for org-wide defaults:

• Public Read/Write allows all users to read and write data to all the records in an object.

  Caution

  This org-wide default does not grant delete, transfer or share permissions. These are only available to owners of a record.

  
  

• Public Read allows all users to read all the records in an object.

• Private only allows the owner of the record, and users with the appropriate permissions, such as Edit All Data or View All Data, to view or edit a record in the object.

By default, all custom objects are created with an org-wide default setting of Public Read/Write. You can change org-wide defaults through the page accessed by Setup Security Controls Sharing Settings Edit, shown below.

The org-wide default you choose should be based on an analysis of the intended usage of the data. Since org-wide defaults are used to lock down data, select the setting that matches the least amount of access granted to the least privileged user of your organization.

If all users of your organization are allowed to edit all records in an object, then the Public Read/Write setting is appropriate for the org-wide default. If all users of your organization are able to read all records in an object, but not be allowed to edit some of the records, the Public Read setting is appropriate. If any of the users of your organization are not allowed to read or write any of the records in an object, the Private setting is appropriate.

The diagram shown below explains the decision flow for selecting an org-wide default for an object.

Sharing

You use org-wide defaults initially to lock down the data in an object, since the core goal of security is to prevent unauthorized access to critical data. You can think of org-wide defaults as adding a door to a room where your precious data is kept—a solid door that is locked (private), a door made of glass and locked (read-only) or a door that is left open (read-write access). The Force Platform gives you a way to share a key to open that door with individual users, a process known as sharing.

When a record is shared with a user, the sharing privilege defines the type of access to that record. There are three levels of sharing access: Private, Read Only and Read/Write.

You use sharing to assign access rights that are greater than those assigned by org-wide defaults. You can only assign Read Only, and Read/Write sharing access to records in an object with a Private org-wide default setting and Read/Write to records with a Public Read org-wide default setting.

Ways to share

There are three ways that you can share a record:

• Manual sharing – If an object has an org-wide default other than Public Read/Write, a Sharing button displays on the detail page for each record. Clicking Sharing brings up the page shown in the following figure.

  Figure 125. Sharing a record

  [View full size image]

  

  Clicking Add brings up the page shown below.

  Figure 126. Adding a share

  [View full size image]

  

  On this page, you can choose to share a record with individual users or groups of users. You are given the choice of the type of sharing you wish to grant to the selected users, although you cannot grant sharing, delete or transfer permissions that are greater than the privileges you possess for the record.

  Once you add sharing for users, those users show up in the list shown above. The owner of a record, or any user with Full Access permission for the record, can drop any shares added through this manual method.

• Sharing rules - In some scenarios, you want to automatically share records owned by one group of users with those in another group. You can implement this type of sharing by using sharing rules. The Sharing Settings page of the Security Settings menu, partially shown in the figure below, has a section for sharing rules for each object in your Force Platform database.

  Figure 127. Sharing Settings page

  [View full size image]

  

  These rules automatically grant a type of sharing access for records owned by one group of users to another group. For instance, you might want to assign all users in the HR group read access to all Position records owned by users in the Recruiter group.

  Note

  The Winter ‘09 release of the Force Platform also supports criteria-based sharing, which allows you to define sharing rules based on logical criteria evaluated against the record. This feature is available as part of a Developer’s Preview—please see developer.force.com for more information on this feature.

  
  

• Apex code - The end result of adding a sharing privilege is an entry into a sharing object. The Force Platform automatically creates a sharing object for every object in your database. Apex sharing uses Apex code to add entries into the sharing object. Apex code is a complete procedural language so you can implement sharing using virtually any type of logical and data-based conditions.

  The Apex Language Reference contains code samples to demonstrate how to implement sharing with Apex code.

Sharing Recipients

A record share is associated with either individual users or groups of users. The Force Platform comes with two ways to group users—roles, discussed later in this chapter, and public groups. Both entities are groups of users, but roles have some special features. You can create a public group through the following steps.

1.	Go to Setup Manage Users Public Groups, which brings up a standard list view of existing public groups.
2.	Click the New button to define a new group on the page shown below.

You can add individual users, other public groups, or two different choices for roles, which are discussed later in this chapter, to a public group.

To reduce the entries in a sharing object, strive to share with groups of users, rather than grant extensive sharing entries for individual users.

Changes Which Affect Sharing

Best practices suggest that you design your sharing scheme as part of your overall application design effort; however, there may be times when you will have to make a change that affects the sharing rules for a record.

Normally, changing a sharing rule automatically recalculates the sharing privileges affected by the change. If the Force Platform determines that the change affects a large number of users, you have to manually trigger a recalculation of shares. In the Sharing Settings page shown above, you can see the Recalculate button for each object.

If you change the org-wide defaults for an object, Force Platform recalculates shares on the object. Any shares granted to a record are dropped if they are now redundant, in that the new org-wide default encompasses the previous permission granted by the share. For instance, if you changed the org-wide default for an object from Private to Public Read Only, any read shares granted to records for the object would not be re-applied.

If you change the owner for an object, all shares for that object are dropped. New shares, based on sharing rules, are added as appropriate.

This final possibility brings up a potential problem. You might have created fairly sophisticated shares using Apex code, and if the owner of the record goes and transfers ownership to another user, all that sharing information is lost. The next section covers Apex-managed shares that address this and other issues.

Apex-managed Sharing

As mentioned previously, you can use Apex code to add shares for a record. Normally, these shares show up in the list of shares, as shown in the figure titled “Sharing a record” above. The owner of the record has the ability to delete any of these shares, and all of these shares are lost when the owner of the record changes. How can you create shares for a record and protect them from this type of destruction?

The solution is Apex-managed shares. You begin the process of creating an Apex-managed share by adding an Apex Sharing Reason, accessible from the main page for an object. The page for adding an Apex Sharing Reason is shown in below.

Once you create an Apex Sharing Reason, you can add shares to a record through Apex code, labeling them with the Sharing Reason.

Any shares that are associated with a Sharing Reason cannot be deleted by a user or a change of ownership. Additionally, you can use standard Apex data access statements to retrieve all the share records for a particular reason.

For more detail on Apex-managed shares, such as sample code and dealing with recalculation of these shares, see the Apex Language Reference. Apex-managed shares add a final bit of subtlety that can be crucial in designing sophisticated sharing schemes for your data.

Roles

You learned about using public groups to share records with more than one user earlier in this chapter. The Force Platform also includes a rich feature called a role. A role, like a public group, can include one or more users. But what makes a role different is the concept of a role hierarchy.

Each org has its own role hierarchy—you can see the sample hierarchy that comes with a default organization below.

A role hierarchy is used to enforce a basic rule—all superior roles have all the sharing permissions granted to all roles below them in the hierarchy. In the hierarchy shown on the Roles page under Manage Users in the Force Platform environment in the figure above, anyone who is in the VP of Development role automatically has all sharing privileges assigned to anyone in the Director of Product Management role. These permissions include those of record ownership so that anyone in the VP of Development role has ownership permissions on all records owned by the Director of Product Management.

When you set org-wide defaults for a custom object, you can specify when the Force Platform should use hierarchies to grant access to users whose role is superior in the hierarchy to a specified user.

Since many organizations have a hierarchical reporting structure, using roles can help you to implement a sophisticated record-based sharing system without extensive rules or coding.

There are two main differences between roles and public groups. One is that a role hierarchy grants permissions in only one direction; your boss has all the permissions you have, but you do not have the same permissions that your boss owns.

You can have public groups that are members of other public groups, but the permission sharing is reciprocal. If Group A is a member of Group B, all members of Group A have all the permissions granted to Group B, and all members of Group B have all the permissions granted to Group A.

Secondly, a user can only belong to one role, and each Force Platform org only supports one role hierarchy, while a user can belong to many public groups. Due to these limitations on roles and role hierarchy, you might be in a situation where roles and a role hierarchy have already been defined for your org, and those definitions do not match the security scheme you would like to implement for your application. Because of this, there may be times when you have to use public groups with your sharing scheme.