Tenant Data Sharing Policies

File:ISV-MSP.gif

> Setup > Administration > Tenant Data Sharing Policies

Tenant Data Sharing Policies let you configure programmatic access to your platform by other tenants.

Users that have the Manage Tenants and Company Capabilities permission can configure Tenant Data Sharing Policies

When you set up a tenant data sharing policy, you specify a User through which a designated tenant can access the platform. The designated tenants can use the Java Record Handling APIs to access your data, effectively "logging in" as that User to do so (without actually having to log in). They can also send an email using the Java sendEmail API.

Under that alias, designated tenants can access any objects that the specified User has access to, and can do whatever reads, adds, updates, and deletes that the User is allowed to do.

Considerations

• Only one Tenant Data Sharing Policy can be created for a designated tenant.
• Giving a designated tenant permission to access your Sales object does not give you permission to see theirs. To do that, a data sharing policy would need to be specified on their end.
• It is generally desirable to specify a different User for each data sharing policy, if only for audit-log purposes.

Learn more: Access Permissions

How it Works

For example, ABC Tenant decides to share data with XYZ Tenant. In order to set up this data sharing configuration, the following actions are taken:

1. ABC Tenant:
   • Contacts XYZ Tenant and obtains the Tenant Id of XYZ Tenant
   • Creates a User (or configures an existing User) associated with a Role. This Role defines the level of data access granted in the Tenant Data Sharing Policy.
   • Creates a Tenant Data Sharing policy, which specifies a User in ABC Tenant, and the Tenant Id of XYZ Tenant
   • Note: Any object or application rights granted via the Role and associated with the User are granted automatically to XYZ Tenant
2. XYZ Tenant:
   • Creates Java Code that will execute actions (like Read, Add, Update or Delete records) and implements this Java Code in Pages or Classes
   • Note: The Java Code actions are applied only when they comply with the rights granted for the specified User Role

Types of Tenant Data Sharing Policies

Two types of policies are available:

• The Global Data Sharing Policy shares data with all tenants, where:

• ISVs can share data with all MSPs or Tenants managed by an ISV
• MSPs can share data with all Tenants managed by an MSP

• A Tenant Data Sharing Policy shares data with a single designated recipient, where:

• ISVs can share data with a single designated MSP or Tenant managed by an ISV
• MSPs can share data with a single designated Tenant managed by an MSP
• Tenants can share data with a single designated Tenant (managed by any Service Provider)

Tenant Data Sharing Policy

To configure a Tenant Data Sharing Policy:

1. Click > Setup > Administration > Tenant Data Sharing Policies, and select one of the following options:

   • Add a new Tenant Data Sharing Policy

     Click the [New Policy Button]

     Update an existing Tenant Data Sharing Policy

     Click the Edit link

2. Complete the following information:

   Name

   Name of the Tenant Data Sharing Policy

   Tenant Id

   Record Id of the Tenant (who will access the shared data)

   User

   Username of a User in the Tenancy that is sharing the data. The Access Permissions associated with the Role of the User determines the data that can be shared.

3. Click [Save]

Global Data Sharing Policy

This option is available to ISVs and MSPs, and is not available to Tenants.

To Manage the Global Data Sharing Policy:

1. Click > Setup > Administration > Tenant Data Sharing Policies
2. Click the [Manage Global Policy] button
3. Select the User to associate with this Global Policy
4. Click [Save]

Using the JAVA API to Access Shared Data

With a Tenant Data Sharing Policy in place, data can be accessed using the Java Record Handling APIs. Those APIs ensure that a Tenant Data Sharing Policy has been configured and assure compliance with Access Permissions.

Considerations

• Memcached maintains the tenant context of each published tenant as per the entries in tenant sharing polices
• When the Tenant Data Sharing Policy is modified, the tenant context present in memcached is removed and user data is unloaded
• If no tenant context is available in memcached, it checks the policies under the publishing tenant that gives access to tenant, if access is available it creates the context and stores in the memcached

Java Record Handling APIs

These APIs are used to access and manage data shared by another tenant. They work by passing an additional tenantContext object to the Java Record Handling APIs.

Note: An exception is thrown if no Tenant Data Sharing Policy has not been set up, or if the User-alias specified in the policy does not have the permissions required for the attempted operation.

addRecord

Adds a tenantContext parameter to the Java Record Handling API addRecord, .

Syntax

<syntaxhighlight lang="java" enclose="div">

TenantContext tenantContext = new TenantContext(String tenantId); Result result = Functions.addRecord(String objectName, Parameters params,

                         TenantContext tenantContext);  

</syntaxhighlight>

updateRecord

Adds a tenantContext parameter to the Java Record Handling API updateRecord

Syntax

<syntaxhighlight lang="java" enclose="div">

TenantContext tenantContext = new TenantContext(String tenantId); Result result = Functions.updateRecord(String objectName, String recordID,

                            Parameters params, TenantContext tenantContext);  

</syntaxhighlight>

deleteRecord

Adds a tenantContext parameter to the Java Record Handling API deleteRecord

Syntax

<syntaxhighlight lang="java" enclose="div">

TenantContext tenantContext = new TenantContext(String tenantId); Result result = Functions.deleteRecord(String objectName, String recordID,

                            TenantContext tenantContext);  

</syntaxhighlight>

searchRecords

Adds a tenantContext parameter to the Java Record Handling searchRecords API.

An optional Parameters object can also added, to specify the Retrieve Record Permissions Parameter.

Simple Search Syntax

<syntaxhighlight lang="java" enclose="div">

TenantContext tenantContext = new TenantContext(String tenantId); Result result = Functions.searchRecords(String objectName, String fields,

                              String criteria, TenantContext tenantContext 
                              {, Parameters params} );  

</syntaxhighlight>

Detailed Search Syntax

<syntaxhighlight lang="java" enclose="div">

TenantContext tenantContext = new TenantContext(String tenantId); Result result = Functions.searchRecords((String objectId, String fields, String criteria,

                              String sortBy, String sortOrder,
                              String sortBy2, String sortOrder2,
                              int offset, int numberOfRows,
                              TenantContext tenantContext {, Parameters params} );  

</syntaxhighlight>

getRecord

Adds a tenantContext parameter to the Java Record Handling API getRecord

An optional Parameters object can also added, to specify the Retrieve Record Permissions Parameter.

Syntax

<syntaxhighlight lang="java" enclose="div">

TenantContext tenantContext = new TenantContext(String tenantId); Result result = Functions.getRecord(String objectName, String fields,

                         String recordId, TenantContext tenantContext {, Parameters params});  

</syntaxhighlight>

Example: Using Java APIs to Manage Shared Data

Assume that a Tenant Data Sharing Policy has been created by tenant ABC, that it specifies your tenancy, and that their ID is 7771212345. You can now use the Java API to add, modify, view and delete ABC's records, to the degree that the data sharing policy gives you permissions to do so.

<syntaxhighlight lang="java" enclose="div">

try {

   String tenantId = "7771212345";  // ID of tenant "ABC"
   TenantContext tenantContext = new TenantContext(tenantId);  

   Parameters  params = Functions.getParametersInstance();
   params.add("first_name", "John");  // Name of field in ABC's Customers object

   Result result = Functions.addRecord("Customers", params, tenantContext);  
   Functions.debug("Result Code and Message:" + result.getCode() + ":" + result.getMessage());

} catch(Exception e){

   Functions.debug("Exception :" + e.getMessage()); 
   throw e;

} </syntaxhighlight>

Note:

• The TenantContext constructor checks the tenant data sharing policies, and

throws an exception if there isn't one.