Skip to Content

Reach

Reach is Vinyl's implementation of Row-level Security (RLS). Reach allows application developers to restrict which rows are available to each user.

Many Relational Database Management Systems (RDBMS) offer native support for RLS. Reach is not an abstraction for these native offerings. Instead, Reach is implemented by the Vinyl business engine. As a result, Reach is database independent.

Use Cases

Common use cases for Reach include:

  • Assignment - Sales people can only manage leads assigned directly to them.
  • Organizational units - Reach can restrict employee access to data by geographic region or division.
  • Multi-tenancy - If an application supports multiple customers, Reach can limit the customer's access to their segment of the data.

Concepts

Reach is composed of the following core concepts:

  • Reach Rule
  • Reach Token
  • Reach Registration

Reach Rule

A Reach Rule is a type of business rule like a Default or Validation rule. As with all business rules, Reach Rules are fundamentally mvSQL queries.

The Reach Rule determines which segments of the data a user can access. In many cases, a Reach Rule will utilize the who() or session() mvSQL functions to correlate the current user with the data they can access.

Reach Token

Each Reach Rule selects one-and-only-one column designated as the Reach Token. This column is identified by the "Reach Token" column usage type.

The Reach Token identifies segments of the data accessible to the user. A Reach Rule may return multiple rows, each row identifying a different segment. If the rule does not return any rows, the user will not have access to any data.

For performance reasons, the Reach Token generally identifies a segment of rows—not individual rows. For example, a Reach Token might identify a geographic region. A sales manager will only be able to generate reports for customers within their region.

Typically, a Reach Token would not identify individual customers. There are exceptions, however. When building a multi-tentant system, the Reach Token might identify the user's own customer row. In this scenario, the customer is the segment.

Reach Registration

Developers must explicitly register a Reach Rule to a data object. A data object may have multiple registrations. In which case, the intersection of those Reach Rules determines which rows the user can access.

A Reach Registration includes the following:

  • Reach Rule - The rule that restricts which segments of the data object are accessible to the user.
  • Binding Column - The data object column bound by the Reach Token.
  • Role - The Role for which the Reach Rule applies. If not associated with a Role, the rule applies to all users.
  • Active - Enable or disable the Reach Rule for development and testing purposes.
  • Index - Order in which Reach Rules are applied.

Note

Note that Reach Rules cannot be registered to arbitrary data objects. Reach Rules target a physical table or view. The rules can only be registered to data objects that target the same table or view.

Implementation

All Vinyl rules support a set of intrinsic events. The Filter event is responsible for retrieving rows. Reach is applied by the Filter event.

As a consequence, Reach is supported in the following scenarios:

  • Panels - Includes Multi-row and Single-row panels, Charts and Calendars, etc.
  • Controls - Includes List and Radio controls.
  • CRUD - Includes Business CRUD rules only—not database-direct CRUD rules.

Example

Given the following table schema:

Table Primary Key Relationships
Region RegionId
Customer CustomerId RegionId, foreign key to Region table.
Employee EmployeeId RegionId, foreign key to Region table.
UserId, reference to Vinyl user.

In this model:

  • Employees and customers both belong to a region.
  • Each employee is associated with a Vinyl user.

The following Reach Rule restricts users such that they can only access customers in their own region:

SELECT RegionId
FROM Employee
WHERE UserId = who('userid')

Assuming the Reach Rule targets the Customer table, it can be registered to the Customer (Source) data object. At which point, Reach will be applied to all panels bound to the Customer (Source) data object.

In many cases, Reach should only be applied for some users. This can be achieved with Roles-based Security (RBS). For example, assume that the data source defines the following Roles:

  • Administrator - Can access all customers.
  • Sales - Can access only customers in their own region.

When registering the Reach Rule, associate it with the Sales role. This will ensure that Reach is only applied to users in the Sales role: users in the Administrator role will have access to all customers.

Limitations

  • Reach is only currently supported for RDBMS data sources.
  • Reach does not currently support cross-platform operations: the Reach rule and data object must belong to the same source data source.
  • Reach is not supported for database-direct CRUD operations. Reach is applied by the business engine: database-direct operations bypass the business engine.
  • A Reach Rule can only have one Reach Token column. Consequently, data objects are bound to Reach Rules by a single column. This differs from other rule types which allow developers to bind data objects to rules using multiple columns.
  • Reach is not currently supported in conjunction with the Vinyl Connector.
  • Copying a data object does not copy Reach Registrations. This is consistent with other rules types: Defaults, Validations and Actions are not copied either.