Apex SDK documentation
Apex SDK is supported in the legacy package and in the three-model package.
The InCountry Apex SDK allows users of the InCountry Data Residency for Salesforce package to make CRUD (create/read/update/delete) operations with their regulated data stored in InCountry PoP's (Points of Presence). The Apex SDK is provided as a part of the InCountry Data Residency for the Salesforce app. All the SDK components are defined as global Apex classes. That’s why the SDK can be used by the app subscribers within their custom code solutions.
Supported data regulation models
The InCountry Apex SDK supports the replication and restriction data regulation models. The Apex SDK provides the following operations on protected data depending on the used data regulation model:
| Operation | Replication | Restriction |
|---|---|---|
| Finding records | Supported | Supported |
| Writing records | Supported | Supported |
| Writing multiple records | Supported | Supported |
| Updating records | Not supported | Supported |
| Synchronizing records | Not supported | Supported |
| Synchronizing multiple records | Not supported | Supported |
| Deleting records | Supported | Supported |
| Attaching files | Not supported | Supported |
| Deleting files | Not supported | Supported |
| Setting the time to live (TTL) for records | Supported | Not supported |
| Resetting the time to live (TTL) for records | Supported | Not supported |
| Check if records are regulated | Supported | Supported |
| Check if multiple records are regulated | Supported | Supported |
| Redacting records | Supported | Supported |
| Redacting values | Supported | Supported |
| Redacting values in a Salesforce object | Supported | Supported |
Internally, the Apex SDK automatically differentiates records by country and makes callouts to InCountry Rest API.
InCountry Rest API endpoints must be registered within the InCountryRestAPIEndpoint custom metadata type and added into the remote site settings to allow server-side callouts. This guide does not cover the initial setup and configuration of InCountry Data Residency for Salesforce. You can find all the relevant information about this at our documentation site.
Quick Start Guide
To access operations available in InCountry PoP, you need to create an instance of the InCountry class. You should prepend the InCountry Managed Package namespace to the class name, like <namespace>.InCountry. For example, if the namespace of the InCountry Data Residency for Salesforce package is testIncountry1, you need to use the following class name: testIncountry1.InCountry.
All the following code samples below are provided without a namespace. Please prepend the InCountry Namespace to class names.
How to instantiate the Apex SDK
You need to execute the static getInstance() method from the InCountry class. It returns an instance of the Apex SDK.
InCountry service = InCountry.getInstance();
How to find records stored in the InCountry Platform
You can find records stored in the InCountry platform by using two different approaches:
by records ids;
by records instances.
The Apex SDK will automatically split records by country and make callouts to appropriate InCountry Points of Presence located in each target country. For example, if you want to fetch two leads stored in InCountry Sweden and one account stored in InCountry Russia, the Apex SDK will make two callouts: one callout to Sweden and the other callout to Russia.
Finding by records ids
In this scenario, you should provide a set of record ids. Please consider that the Apex SDK will perform additional SOQL queries to retrieve records from the Salesforce database. For example, if you provide three account Ids and five lead Ids, the SDK will perform two additional SOQL queries to retrieve accounts and leads from the database. These SOQL queries are required because the SDK should fetch all the regulated field values and the record originating countries from the database. In the following example, the SDK will fetch two leads and one account from the InCountry platform.
InCountry service = InCountry.getInstance();
Set<Id> input = new Set<Id>{'00Q5w00001vsLjVEAU', '00Q5w00001vrzjQEAQ', '0015w00002OUr9uAAD'};
List<InCountry.FindResult> results = service.find(input);
Finding by record instances
If you have queried all the necessary records from the Salesforce database, you can provide the record instances to the find() method so that the SDK will skip additional SOQL queries. Please ensure that all the required fields are included in your SOQL queries. The Apex SDK requires all the regulated fields and the Source Country Field field to use the record-level policy for determining the record originating country.
InCountry service = InCountry.getInstance();
List<Lead> input = [SELECT Id, FirstName, Email,
Phone, Country_Field__c
FROM Lead
ORDER BY CreatedDate DESC
LIMIT 10];
List<InCountry.FindResult> results = service.find(input);
The FindResult class contains data returned from the InCountry platform:
@JsonAccess(serializable='always' deserializable='always')
global class FindResult {
@AuraEnabled global List<RecordData> data;
@AuraEnabled global Map<String, String> meta;
}
The RecordData class represents a single Salesforce record stored in the InCountry platform:
@JsonAccess(serializable='always' deserializable='always')
global class RecordData {
@AuraEnabled global String key;
@AuraEnabled global String record_key;
@AuraEnabled global String profile_key;
@AuraEnabled global String range_key;
@AuraEnabled global String body;
@AuraEnabled global String key1;
@AuraEnabled global String key2;
@AuraEnabled global String key3;
@AuraEnabled global String key4;
@AuraEnabled global String key5;
@AuraEnabled global String key6;
@AuraEnabled global String key7;
@AuraEnabled global String key8;
@AuraEnabled global String key9;
@AuraEnabled global String key10;
@AuraEnabled global String key11;
@AuraEnabled global String key12;
@AuraEnabled global String key13;
@AuraEnabled global String key14;
@AuraEnabled global String key15;
@AuraEnabled global String key16;
@AuraEnabled global String key17;
@AuraEnabled global String key18;
@AuraEnabled global String key19;
@AuraEnabled global String key20;
@AuraEnabled global String created_at;
@AuraEnabled global String updated_at;
@AuraEnabled global String expires_at;
@AuraEnabled global List<FileData> attachments;
}
The @AuraEnabled global String expires_at; snippet is not available for the restriction data regulation model.
The FileData class represents a single file linked to a specific InCountry record:
@JsonAccess(serializable='always' deserializable='always')
global class FileData {
@AuraEnabled global String file_id;
@AuraEnabled global String filename;
@AuraEnabled global String hash;
@AuraEnabled global String mime_type;
@AuraEnabled global Integer size;
@AuraEnabled global String created_at;
@AuraEnabled global String updated_at;
@AuraEnabled global String download_link;
@AuraEnabled global String error;
}
How to write records into the InCountry Platform
Like the find operation, you can use two different methods to write single Salesforce records into the InCountry Platform.
Writing by record ids
Please consider that the Apex SDK will perform an additional SOQL query to fetch a salesforce database record. If the current user on behalf of whom an operation is executed has no sufficient permissions to the record id, an exception will be thrown.
InCountry service = InCountry.getInstance();
InCountry.WriteRequest result = service.write('00Q5w00001vrzjQEAQ');
Writing by record instance
Before executing the write(SObject record) method, ensure that you have included all the necessary regulated and country fields into your SOQL queries.
InCountry service = InCountry.getInstance();
Lead input = [SELECT Id, FirstName, Email, Phone, Country_Field__c
FROM Lead
LIMIT 1];
input.FirstName = 'ChangedValue';
InCountry.WriteRequest result = service.write(input);
The WriteRequest class represents a confirmation which the InCountry platform returns upon a successful execution of the write request.
@JsonAccess(serializable='always' deserializable='always')
global class WriteRequest {
@AuraEnabled global String country;
@AuraEnabled global String profile_key;
@AuraEnabled global String body;
@AuraEnabled global String record_key;
@AuraEnabled global String key;
@AuraEnabled global String key1;
@AuraEnabled global String key2;
@AuraEnabled global String key3;
@AuraEnabled global String key4;
@AuraEnabled global String key5;
@AuraEnabled global String key6;
@AuraEnabled global String key7;
@AuraEnabled global String key8;
@AuraEnabled global String key9;
@AuraEnabled global String key10;
@AuraEnabled global String key11;
@AuraEnabled global String key12;
@AuraEnabled global String key13;
@AuraEnabled global String key14;
@AuraEnabled global String key15;
@AuraEnabled global String key16;
@AuraEnabled global String key17;
@AuraEnabled global String key18;
@AuraEnabled global String key19;
@AuraEnabled global String key20;
@AuraEnabled global String expires_at;
}
The @AuraEnabled global String expires_at; snippet is not available for the restriction data regulation model.
How to write multiple records into the InCountry platform
The Apex SDK performs requests to a separate /api/records/batch endpoint in InCountry Rest API to write multiple records to the InCountry platform to perform batch write operations. The Apex SDK will automatically split records by country and will make several callouts to different InCountry Points of Presence in the target countries. For example, if you want to write two Leads to InCountry Sweden and one account to InCountry Russia, the Apex SDK will make two callouts, as follows: one callout to Sweden and the other callout to Russia.
Writing a batch of records by records ids
Please consider that InCountry SDK will perform additional SOQL queries to fetch records from the Salesforce database. If the current user on behalf of whom an operation is executed has no sufficient permissions to record id, an exception will be thrown.
For example, if you provide three account ids and five lead ids, the SDK will perform two additional SOQL queries to fetch accounts and leads from the database. These SOQL queries are required because the Apex SDK should take all the regulated field values and record originating countries from the database.
InCountry service = InCountry.getInstance();
Set<Id> input = new Set<Id>{'00Q5w00001vsLjVEAU', '00Q5w00001vrzjQEAQ', '0015w00002OUr9uAAD'};
List<InCountry.WriteRequest> result = service.write(input);
Writing a batch of records by record instances
Before executing the write(List<SObject> records) method, ensure that you have all the required regulated and country fields included in your SOQL queries.
InCountry service = InCountry.getInstance();
List<Lead> input = [SELECT Id, FirstName, Email, Phone, Country_Field__c
FROM Lead
LIMIT 40];
for (Lead leadRecord : input) {
leadRecord.Phone = '+37529000000';
}
List<InCountry.WriteRequest> result = service.write(input);
How to update multiple records on the InCountry platform
The Apex SDK performs requests to a separate /api/records/batch/update endpoint in InCountry Rest API to update multiple records to the InCountry platform. The Apex SDK will automatically split records by country and will make several callouts to different InCountry Points of Presence in the target countries.
Updating a batch of records by record instances
To update certain fields you have to add them in your SOQL request and then execute the update(List<SObject> records) method.
InCountry service = InCountry.getInstance();
List<Lead> input = [SELECT Id, Phone FROM Lead LIMIT 5];
for (Lead leadRecord : input) {
leadRecord.Phone = '+37529000000';
}
List<InCountry.WriteRequest> result = service.updateRecords(input);
How to synchronize single records with the InCountry platform
Like the find and writeoperations, you can use two different methods to synchronize single Salesforce records with the InCountry platform.
Synchronizing by record ids
Please consider that the Apex SDK will perform an additional SOQL query to fetch a record from the Salesforce database. If the current user on behalf of whom an operation is executed has no sufficient permissions to the record id, an exception will be thrown. Once the Apex SDK has written a data record into the InCountry platform, it will perform a DML query to update a record in the Salesforce database with hashed values.
InCountry service = InCountry.getInstance();
InCountry.WriteRequest result = service.sync('00Q5w00001vrzjQEAQ');
Synchronizing by record instance
Before executing the sync(SObject record) method, ensure that you have included all the necessary regulated and country fields into your SOQL queries. Once the Apex SDK has written a data record into the InCountry platform, it will perform a DML query to update a record in the Salesforce database with hashed values.
InCountry service = InCountry.getInstance();
Lead input = [SELECT Id, FirstName, Email, Phone, Country_Field__c
FROM Lead
LIMIT 1];
input.FirstName = 'ChangedValue';
InCountry.WriteRequest result = service.sync(input);
The WriteRequest class represents a confirmation which the InCountry platform returns upon a successful execution of the write request.
@JsonAccess(serializable='always' deserializable='always')
global class WriteRequest {
@AuraEnabled global String country;
@AuraEnabled global String profile_key;
@AuraEnabled global String body;
@AuraEnabled global String record_key;
@AuraEnabled global String key;
@AuraEnabled global String key1;
@AuraEnabled global String key2;
@AuraEnabled global String key3;
@AuraEnabled global String key4;
@AuraEnabled global String key5;
@AuraEnabled global String key6;
@AuraEnabled global String key7;
@AuraEnabled global String key8;
@AuraEnabled global String key9;
@AuraEnabled global String key10;
@AuraEnabled global String key11;
@AuraEnabled global String key12;
@AuraEnabled global String key13;
@AuraEnabled global String key14;
@AuraEnabled global String key15;
@AuraEnabled global String key16;
@AuraEnabled global String key17;
@AuraEnabled global String key18;
@AuraEnabled global String key19;
@AuraEnabled global String key20;
@AuraEnabled global String expires_at;
}
How to synchronize multiple records with the InCountry platform
The Apex SDK performs requests to a separate /api/records/batch endpoint in InCountry Rest API to write multiple records to the InCountry platform to perform batch write operations. The Apex SDK will automatically split records by country and will make several callouts to different InCountry Points-of-Presence in the target countries. For example, if you want to write two Leads to InCountry Sweden and one account to InCountry Russia, the Apex SDK will make two callouts, as follows: one callout to Sweden and the other callout to Russia. Once the Apex SDK has written data records into the InCountry platform it will perform A DML query to update records in the Salesforce database with hashed values.
Synchronizing multiple records by records ids
Please consider that the Apex SDK will perform additional SOQL queries to fetch records from the Salesforce database. If the current user on behalf of whom an operation is executed has no sufficient permissions to record id, an exception will be thrown.
For example, if you provide three account ids and five lead ids, the Apex SDK will perform two additional SOQL queries to fetch accounts and leads from the database. These SOQL queries are required because the Apex SDK should take all the regulated field values and record originating countries from the database.
InCountry service = InCountry.getInstance();
Set<Id> input = new Set<Id>{'00Q5w00001vsLjVEAU', '00Q5w00001vrzjQEAQ', '0015w00002OUr9uAAD'};
List<InCountry.WriteRequest> result = service.sync(input);
Synchronizing multiple records records by record instances
Before executing the sync(List<SObject> records) method, ensure that you have all the required regulated and country fields included into your SOQL queries.
InCountry service = InCountry.getInstance();
List<Lead> input = [SELECT Id, FirstName, Email, Phone, Country_Field__c
FROM Lead
LIMIT 40];
for (Lead leadRecord : input) {
leadRecord.Phone = '+37529000000';
}
List<InCountry.WriteRequest> result = service.sync(input);
How to remove records from the InCountry platform
As of now, the InCountry platform does not support batch delete operations. If you want to delete multiple records from the InCountry platform, please consider that the Apex SDK will perform multiple callouts.
Removing a single record by record id
Please consider that the Apex SDK will perform an additional SOQL query to fetch a record from the Salesforce database.
InCountry service = InCountry.getInstance();
Id input = '0015w00002OUr9uAAD';
InCountry.DeleteResult result = service.remove(input);
Removing multiple records by records ids
Please consider that the Apex SDK will perform additional SOQL queries to fetch your records from the Salesforce database. In the following example, the Apex SDK will perform two additional SOQL queries and three callouts.
InCountry service = InCountry.getInstance();
Set<Id> input = new Set<Id>{'00Q5w00001vsLjVEAU', '00Q5w00001vrzjQEAQ', '0015w00002OUr9uAAD'};
List<InCountry.DeleteResult> result = service.remove(input);
How to attach files to records saved to the InCountry platform
Please consider that the Apex SDK will perform an additional SOQL query to fetch a record from the Salesforce database. The record to which you want to attach the file must be saved on the InCountry platform. Using the last parameter of the method, you can specify whether to delete the file from the Salesforce database after writing it to the InCountry platform.
InCountry service = InCountry.getInstance();
InCountry.FileData result = service.attachFile('003S000001XcKebIAF', 'test.txt', Blob.valueOf('test data'), false);
How to remove files from the InCountry platform
Please consider that the Apex SDK will perform additional SOQL queries to fetch your records from the Salesforce database.
InCountry service = InCountry.getInstance();
List<InCountry.DeleteResult> result = service.deleteFile('003S000001XcKebIAF','9097d392-84de-4227-9e76-fc05403747e9');
How to set and reset time to live (TTL) for records with protected data
These operations are not available in the restriction data regulation model. Please consider this while using the Apex SDK.
The InCountry platform provides the ‘Recycle Bin’ feature which allows you to define the time to live for specific records and automatically delete these records with all their protected data upon reaching the specified date and time.
Setting TTL for records
Please consider that the Apex SDK will perform an additional SOQL query to fetch a record from the Salesforce database. The function accepts a set of record ids and the number of days. A record will be automatically deleted on the date specified as expires_at = NOW() + <NUMBER_OF_DAYS>.
InCountry service = InCountry.getInstance();
Set<Id> recordIds = new Set<Id>{'0012100000vUyEoAAK'};
Integer numberOfDays = 30;
service.setTTL(recordIds, numberOfDays);
Resetting TTL for records
This example shows how to reset the TTL (expires_at) value for records with protected data. The reset operation sets the expires_at value to null, which means that a record will not be automatically deleted from the InCountry platform when reaching the previously specified date (TTL).
InCountry service = InCountry.getInstance();
Set<Id> recordIds = new Set<Id>{'0012100000vUyEoAAK'};
service.resetTTL(recordIds);
How to check if a record will be processed by the InCountry platform
You can check if a record will be processed by the InCountry platform or not. There are two different methods that allow you to check either a single record or multiple records.
How to check a single record
This operation is available in the three-model package for the restriction and redaction model only. Please consider this while using the Apex SDK.
InCountry service = InCountry.getInstance();
Boolean result = service.isRegulatedRecord('00Q5w00001vrzjQEAQ');
How to check multiple records
This operation is available in the legacy package and in the three-model package for the restriction and redaction models. Please consider this while using the Apex SDK.
Please consider that the Apex SDK will not perform an SOQL query to fetch a Salesforce database record. Please ensure that all the required fields are included into your SOQL queries. The Apex SDK requires all the regulated fields and the Source Country Field field to use the record-level policy for determining the record’s country of origin.
InCountry service = InCountry.getInstance();
List<Contact> recordsToCheck = [SELECT Id, MailingCountry FROM Contact LIMIT 5];
Incountry.RegulatedRecordsResult result = service.identifyRegulatedRecords(recordsToCheck);
The RegulatedRecordsResult class contains two lists. The first list regulatedObjects contains a list of regulated records, the second list nonRegulatedObjects contains a list of non-regulated records.
@JsonAccess(serializable='always' deserializable='always')
global class RegulatedRecordsResult {
@AuraEnabled global List<SObject> regulatedObjects = new List<SObject>();;
@AuraEnabled global List<SObject> nonRegulatedObjects = new List<SObject>();
}
How to redact records with the tools of the InCountry platform
InCountry service = InCountry.getInstance();
List<Contact> recordsToRedact = [SELECT Id, Phone, Title FROM Contact LIMIT 5];
List<SObject> redactedRecords = service.redactRecords(recordsToRedact);
The redactedRecords list will contain records from the recordsToRedact list but the values of each record will be redacted according to the InCountry regulation policies in Settings.
How to redact a value in a Salesforce object with the tools of the InCountry platform
InCountry service = InCountry.getInstance();
List<Contact> recordsToRedact = [SELECT Id, Phone, Title FROM Contact LIMIT 1];
SObject redactedRecord = service.redactField(recordsToRedact[0], 'Title');
The redactedRecord list will contain a record but the record value will be redacted according to the InCountry regulation policies in Settings.
How to redact a value with the tools of the InCountry platform
InCountry service = InCountry.getInstance();
String valueToRedact = 'John Martin';
String redactionAlgorith = 'sha256';
Object redactedValue = service.redactValue(valueToRedact, redactionAlgorith);
The redactedValue variable is redacted according to the InCountry redaction rules.
Supported algorithms
The InCountry Apex SDK supports the following redactionAlgorithms types:
uniqueHashuniqueEmailHashsha256dtkSha256defaultNumberdefaultBooleandefaultDatedefaultDateTimenothingdefaultTextvalueOnefixed
Also, values can be redacted with the formula redaction algorithm, but with the following code:
InCountry service = InCountry.getInstance();
String valueToRedact = 'John Martin';
String redactionAlgorith = 'sha256';
String formula = '{
"fn":"dtkSha256",
"transform":["trim"],
"format":"{18}"
}';
Map<String, Object> redactionParams = new Map<String, Object> {
'formula' => formula
};
Object redactedValue = service.redactValue(valueToRedact, redactionAlgorith);
The formula redaction algorithm requires the additional parameter formula.
For the details, please check our documentation for the formula function.
Hash functions work only with values, if there are no values, the hash function is not applied.
Error handling
The Apex SDK may throw the following exception:
SObject was retrieved without a required field. For example, you need to specify the Source Country field if you are using a record-level policy set for a current SObject.
