InCountry logo
mobile-nav
Search
  • Products
    • Products
      • InCountry for Salesforce
      • Data Residency-as-a-Service
      • Alibaba Cloud InCountry Service
      • Compliance and security
    • Gateways
      • Email
      • Payment Vault
      • Web Forms
      • HTML
    • Developers
      • REST API
      • SDK
  • Solutions
    • Automotive
    • Energy
    • Financial services
    • Healthcare
    • Retail
    • Technology
    • Latest success story
      • IBM Consulting
  • Integrations
    • Cegid
    • Intertrust
    • MuleSoft
    • PayPal
    • Salesforce
    • ServiceNow
    • Stripe
    • Veeva Systems
    • Yandex
  • Resources
    • Country compliance
    • Documentation
    • Library
    • Partners
    • Pricing
  • About
    • News and Blog
    • Careers
    • Contact Us
    • FAQ
    • Leadership
  • Login
  • Schedule a Demo

›Administrator's guide

Home
  • InCountry Platform
Portal
  • Getting started
  • Documentation
    • Dashboard
    • Managing environments
    • Managing SDK credentials and services
    • Managing Border configuration
    • Managing payment vaults
    • Managing email gateways
    • Managing resident functions
    • Managing file imports
    • Managing profile and organization
    • Managing users
    • Managing encryption keys
  • Release notes
Border
  • Documentation
  • Release notes
REST API
  • Documentation
  • How to test CRUD requests through REST API
  • Release notes
Resident Functions
  • Documentation
Salesforce
  • About
  • Overview
  • Quick start guide for three-model package
  • Quick start guide for legacy package
  • Administrator's guide
    • Managing the package
    • Managing permissions
    • Managing OAuth2 authentication and authorization
    • Managing certificates
    • Registering CSP Trusted Sites
    • Managing InCountry Endpoints
    • Managing REST endpoints
    • Managing InCountry flags
    • Loading the application
    • Managing data regulation policies
    • Managing protected fields
    • Hashing the UserName field
    • Managing custom objects
    • Replacing standard elements
    • Configuring record search
    • Managing components
    • Setting up Salesforce Experience Cloud
    • Managing resident functions
    • Managing InCountry cache
    • Managing Apex triggers
    • Managing record synchronization
    • Managing web forms
    • Tracking changes to data regulation policies and regulated fields
    • Using Email-to-Case feature
    • Debugging
    • Migrating data from one Salesforce organization to another
  • Developer’s guide
    • Apex SDK
    • JavaScript API
    • Retrieving record statistics
    • Tracking field history
  • User's guide
    • Working with protected fields
    • Sending compliant email messages
    • Importing data into Salesforce
    • Migrating records
    • Managing audit reports
    • Converting leads
    • Managing reports
    • Using formula fields
    • Using frontend validations
    • FAQ
    • Release notes
Payment Vault
  • Documentation
BYOK
  • Documentation
FAQ
  • Get started with the platform
  • Integration options
  • Data regulation models
  • Limits and quotas
  • Video tutorials
Service Status
  • Status

Managing protected fields

note

Management of protected fields is identical for the three-model package and for the legacy package.

PROTECTED fields (regulated fields) are fields that contain information that may be used to identify the person. Due to regulations of different countries, such information must be protected, and in some situations stored in the country of origin.

For each Salesforce object, you can define the PROTECTED fields that store the personal identifiable information (PII) or any sensitive information users choose to localize. Such fields will be processed by the package according to the configured data store policy.

Managing PROTECTED fields

The package lets you manage PROTECTED fields as follows:

  • Add PII fields for each Salesforce object

  • Delete the no longer needed PROTECTED fields for each Salesforce object

On the menu, select Settings. The page with the app settings loads, as follows:

Settings

Here you need to select the Salesforce object which PROTECTED fields will be added for.

Adding PROTECTED fields

  1. Select the Salesforce object which PROTECTED fields you want to add.

    Adding PROTECTED fields

  2. Click Add Field. The Add PII Fields form opens.

    Add Form

  3. In the Select Field box, start entering the field name. Select the field from the prompted matches.

  4. In the Hash Function box, select the hash function which will be applied to the value of the field. Ensure that the applied hash function is valid for data contained within the field, otherwise the hashed data pattern will be incorrect for storing in Salesforce. You can use the fixed hash function to apply your own custom value to hashed fields.

  5. In the Lookup relationship box, enter the lookup relationship for the current field. In Salesforce this corresponds to the Lookup Relationship Name.

  6. In the Reference field box, enter the field name which value the current field will reference.

  7. In the Reference order box, specify the order in which fields are referenced. Use the comma to separate different fields from each other.

  8. In the Lookup api name box, enter the field name of the Salesforce object for making calls to Salesforce API. In Salesforce this corresponds to the LookupObjectApiName.

  9. In the Indexed Key box, map the Salesforce protected field to the InCountry record’s field, as follows:

    • key - is used to store alphanumeric values. You can have up to 25 searchable protected fields of this type per one Salesforce object.

    • range_key - is used to store integer and date values for protected fields. You can have up to 10 searchable protected fields of this type per one Salesforce object. Dates when they are saved to the range_key field are converted to the Unix timestamp format.

    The total number of the key + range_key fields is controlled by the RestAPIFieldsAvailable setting in InCountry Value. For example, if you need 25 fields of the key type and 10 fields of the range_key type, the required value for RestAPIFieldsAvailable must be specified as 35.

    note

    Using the improper parameters for protected fields may result in problems with value searchability or record saving.

  10. Check the Need to hash box to enable the hashing for the PROTECTED field. By default, it it enabled automatically when you select the hash function.

  11. Check the Is Compound box to indicate that the field is comprised of multiple fields.

  12. Check the Is Country field box to indicate that the field contains information about the country.

  13. When complete, click Add.

The newly added PROTECTED field will appear on the list with other PROTECTED fields that are attributed to the currently selected Salesforce object. These fields will be processed by the package and shown according to the configured data regulation policy.

Using the deterministic tokenization functions

The InCountry Data Residency for Salesforce package supports the deterministic tokenization that produces the same redacted value every time you pass the same value to it, unlike producing a unique token every time for the same value. This is needed when you need to use duplicate rules to ensure that the same record already exists in Salesforce while submitting it through the InCountry Data Residency for Salesforce package.

After enabling the deterministic tokenization, the package will generate the deterministic tokenization key which you may need to enter when creating a Border configuration on the InCountry Portal. If you do not use Border for submitting records to Salesforce, the package will automatically apply the deterministic tokenization key when using the dtkSha256 or formula hash functions containing dtkSha256.

Generating the deterministic tokenization key

  1. In the App Launcher form, select InCountry.

  2. Select Settings.

  3. Locate the deterministic tokenization block.

  4. Click Generate.

    As the result, the generated key should look like this:

    note

    Once the deterministic tokenization key has been successfully generated, the dtk.txt file with this key will be downloaded. Please save this file and use it in the Border configuration if needed.

    note

    The key can be copied with the Copy button.

  5. Copy this key and paste into the Border configuration. If you need it for execution of duplicate rules, you do not need to enter it anywhere. The package will automatically use it when you use the dtkSha256 function or include it into the formula function.

note

The deterministic tokenization key is generated only once and cannot be regenerated to preserve the consistency of redacted data.

After generation of the deterministic tokenization key, the two new hash functions will appear in the Add PII Fields form:

  • dtkSha256

  • formula

Specifics of the dtkSha256 function

The dtkSha256 as well as the sha256 function is available only for fields with the length equal to or more than 64 symbols. PII fields can be configured to apply this new hash function dtkSha256. In situations, when you need to apply it against fields that accept fewer than 64 characters you need to use the formula function with the applied character limit.

Specifics of the formula function

The formula function is an advanced option to redact sensitive values. It allows you to fine tune the hashing function and adjust the outputted redacted value to your actual needs. The formula function can take two functions: sha256 and dtkSha256.

In addition, you can apply the tranform function within the formula function to customize the outputted redacted value. It can take an array of transformation functions including toLowerCase, toUpperCase, and trim.

Below you can see an example of the formula function:

dtkSha256(value.transform(['trim', 'toLowerCase'])).format("[A-Za-z0-9]{12}@redacted.com")

The anatomy of the formula function is presented below:

note

When using the formula function you need to consider the length of the field. The package shows the maximal number of characters as a hint below the Formula text box.

Viewing the formula for the protected field

  1. On the menu, select Settings.

  2. Select the Salesforce object whose PII fields you want to see.

  3. Locate the protected field with the configured formula.

  4. Click the box with the down arrow and then select Show formula.

The View Formula form opens where you can see all the necessary details about the used formula.

The formula function can be comprised of the following constituents:

ParameterDescription
FunctionName of the function used for redaction of sensitive values. You can use the following:

- sha256

- dtkSha256
Transformation functionsHere you can specify additional transformation functions that will be applied to the original sensitive value for data normalization before redaction with the formula function.

You can use the following:

- toLowerCase adjusts the string to the lower case

- toUpperCase adjusts the string to the upper case

- trim removes all spaces from the string.
Field value lengthThe length of the produced redacted value. By default, the sha256 and dtkSha256 functions return a 64-character string. This string will be cut to the specified length.

You need to specify it in the following format: {20}.

When using the dtkSha256 function, keep the field value length not smaller than 20 characters. Smaller values can potentially cause collision of similar redacted values for different sensitive values.
Static textThis text will be appended as-is to the redacted value produced by the sha256 or dtkSha256 functions. You can append any alphanumeric string. Please consider the field length not to exceed the maximal number of characters.

Below you can see the configuration of the formula function for the Email and First Name fields.

When creating a new lead, you enter the email address as Useremail@domain.com.

How this value will be hashed with the formula function:

  1. The trim function is applied to the Useremail@domain.com value.

  2. The toLowerCase function is applied to the Useremail@domain.com value and transforms it to useremail@domain.com.

  3. The dtkSha256 function produces a hash for the provided value as bc95131c6fb5e2b2c57604d53283eac6f0a0fa05b910830c5f264d24859cb22f.

  4. The trim function cuts the hash value to 12 symbols resulting in bc95131c6fb5.

  5. The static text is appended to the hashed value resulting in bc95131c6fb5@redacted.com.

Limitations of the formula function

  1. Only two hash functions are supported: sha256 and dtkSha256.

  2. When appending a static text string to the redacted value consider the length of the field and adjust the length of the redacted value accordingly.

Selecting hash functions for PROTECTED fields inline

You can select or change hash functions for PROTECTED fields inline when viewing the list of such fields for a specific Salesforce object.

  1. On the list with PROTECTED fields, locate the field for which you want to change the hash function.

  2. Hover over the field with the hash function.

    Hover over the Hash Function field

  3. Click the Edit icon.

    Select the hash function inline

  4. Select the appropriate hash function.

The selected hash function will be applied to the current PROTECTED field.

Supported field types and their hash functions

nothingfixedsha256dtkSha256uniqueHashuniqueEmailHashdefaultTextdefaultDateTimedefaultBooleandefaultNumberrandomformula
Text(tick)(tick)(tick)(tick)(tick)(error)(tick)(error)(error)(error)(tick)(tick)
Text Area(tick)(tick)(tick)(tick)(tick)(error)(tick)(error)(error)(error)(tick)(tick)
Picklist (single-select)(tick)(tick)(tick)(tick)(tick)(error)(tick)(error)(error)(error)(error)(error)
Picklist (Multi-Select)(tick)(tick)(tick)(tick)(tick)(error)(tick)(error)(error)(error)(error)(error)
Time(tick)(tick)(error)(error)(error)(error)(error)(error)(error)(error)(error)(error)
Date OR Date/Time(tick)(tick)(error)(error)(error)(error)(error)(tick)(error)(error)(error)(error)
Checkbox(tick)(tick)(error)(error)(error)(error)(error)(error)(tick)(error)(error)(error)
Percent(tick)(tick)(error)(error)(error)(error)(error)(error)(error)(tick)(error)(error)
Number(tick)(tick)(error)(error)(error)(error)(error)(error)(error)(tick)(tick)(error)
Currency(tick)(tick)(error)(error)(error)(error)(error)(error)(error)(tick)(error)(error)
Phone(tick)(tick)(error)(error)(error)(error)(tick)(error)(error)(error)(error)(tick)
Email(tick)(tick)(error)(error)(error)(tick)(error)(error)(error)(error)(tick)(tick)
URL(tick)(tick)(tick)(tick)(error)(error)(tick)(error)(error)(error)(error)(error)
Geolocation(tick)(error)(error)(error)(error)(error)(error)(error)(error)(tick)(error)(error)
Base64(tick)(error)(tick)(tick)(tick)(error)(error)(error)(error)(error)(error)(error)

Hash function examples

note

Hash functions work only with values, if there are no values, the hash function is not applied.

Hash function How it works Input value Value saved to Salesforce Value saved to the InCountry platform Recommendations

nothing

The function preserves the original value as-is without any changes.

text

text

text

Avoid using this hash function for PII data as it does not redact values and keeps the clear-text values in the Salesforce database.

fixed

The function applies the specified default value to all records making the same dataset store one value. You can adjust the default value depending of the field type.

50

10

50

 

When configuring the default fixed value: 10.

sha256

The function hashes a field value with the SHA-256 algorithm and is applicable for text string values only.

test

n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=

test

 

dtkSha256

The function produces the same token for the same value every time you use it.

test

b792aedc7cd1a35262308bfade04c1833b015c4d6

test

 

uniqueHash

The function hashes a field value with a custom algorithm and appends the current date into the resulting hashed value. It is applicable for text string values only.

test

n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=

test

 

uniqueEmailHash

The function hashes a field value with the SHA-256 algorithm and adjusts the hashed value to the email format.

test@gmail.com

h5JGBr@QTGo.incountryhash

test@gmail.com

Use this function when you perform validation of email address pattern in Salesforce.

defaultText

The function replaces a field value with an empty string.

test

 

test

Do not use this hash function for required fields.

defaultDate

The function replaces a field value with the default date (1970-01-01).

5/20/2023

1/1/1970

5/20/2023

 

defaultDateTime

The function replaces a field value with the default date/time (1970-01-01 00:00:00).

5/20/2023 5:32

1/1/1970 0:00

5/20/2023 5:32

 

defaultBoolean

The function replaces a field value with the false value.

true

false

true

 

defaultNumber

The function replaces a field value with the 0 value.

10

0

10

 

random

The function replaces a field value with some random value. This hash function generates a random alphanumeric string depending on the field type.

test

bMSzGOd89UXA0PxlmdeUS2ZZArsl2PWt

test

 

3

642

3

 

 

Mapping fields to hash functions

note

While configuring fields, please consider the using of the proper hash function for a specific data format. For example, if you need to tokenize the email address, you should use uniqueEmailHash function. Otherwise, email address will not be properly handled by Salesforce. For names, use the uniqueHash function.

If you use the redaction data regulation policy, you need to apply the correct hash functions to fields. Please check the mappings of hash functions to fields in the following table:

Internal Salesforce fieldUI fieldHash functionConditionsNotes
ANYTYPEN/AThis function is on our roadmap and is not available yet.
BASE64N/AuniqueHashIf the field length is greater than or equal to 50 characters.Supporting the backward compatibility.
BASE64N/Asha256 dtkSha256If the field length is greater than or equal to 64 characters.Supporting the backward compatibility.
BOOLEANCheckbox/0defaultBoolean
CALCULATEDN/AThis function is on our roadmap and is not available yet.
COMBOBOXN/AdefaultText
CURRENCYCurrencydefaultNumberA new function is to be implemented.
DATACATEGORYREFERENCEN/AThis function is on our roadmap and is not available yet.
DATEDatedefaultDate
DATETIMEDateTimedefaultDateTime
DOUBLENumberdefaultNumberA new function is to be implemented.
EMAILEmail/80uniqueEmailHashUse the uniqueEmailHash as the main function for the Email field. It generates the unique hash every time for this field.
EMAILEmail/80sha256EmailHashUse the sha256EmailHash function to generate the same hash for the same values of this field.
ENCRYPTEDSTRINGText (Encrypted)/175This function is on our roadmap and is not available yet.
HIERARCHYN/AThis function is on our roadmap and is not available yet.
IDN/AThis function is on our roadmap and is not available yet.
INTEGERN/AdefaultNumber
LOCATIONGeolocationdefaultNumberA new function is to be implemented.
LONGN/AThis function is on our roadmap and is not available yet.
LOOKUPN/AThis function is on our roadmap and is not available yet.
MULTIPICKLISTPicklist (Multi-Select)/4099This function is on our roadmap and is not available yet.
PERCENTPercentdefaultNumberA new function is to be implemented.
PHONEPhone/40defaultTextA new function is to be implemented.
PICKLISTPicklist/255sha256 dtkSha256A new function is to be implemented.Use the sha256 function if the pick list field is not restricted and it can take more than 64 characters. Otherwise use the defaultText function.
PICKLISTPicklist/255defaultTextA new function is to be implemented.
REFERENCELookup Relationship/18This function is on our roadmap and is not available yet.
REFERENCEExternal Lookup RelationshipThis function is on our roadmap and is not available yet.
STRINGAutoNumber/30uniqueHash formulaIf the field length is greater than or equal to 50 characters.Preparing the backward compatibility.Use the uniqueHash function to generate a unique hash value for this field every time. Otherwise use the defaultText function.
STRINGText/255sha256 dtkSha256 formulaIf the field length is greater than or equal to 64 characters,Use the sha256 function if the field can take more than 64 characters.
STRINGdefaultText formulaIf the field length is less than 30 characters,
TEXTAREAText Area (Long)/32768uniqueHash formulaIf the field length is greater than or equal to 50 characters.
TEXTAREATextArea/255sha256 dtkSha256 formulaIf the field length is greater than or equal to 64 characters,
TEXTAREAText Area (Rich)/32768defaultText formula
TIMETimeA new function is to be implemented.
URLURL/255sha256 dtkSha256
URLURL/255defaultText
Specifics of the compound Address field
STRINGCity/40uniqueHash formula defaultText
PICKLISTAccuracy/40defaultTextUse the sha256 if the picklist field is not restricted and its length is greater than 64 characters. Otherwise use defaultText.
PICKLISTCountry/80sha256 dtkSha256 defaultTextUse the sha256 if the picklist field is not restricted and its length is greater than 64 characters. Otherwise use defaultText.
PICKLISTCountryCodesha256 dtkSha256 defaultTextUse the sha256 if the picklist field is not restricted and its length is greater than 64 characters. Otherwise use defaultText.
DOUBLELatitude/18.15A new function is to be implemented.
DOUBLELongitude/18.15A new function is to be implemented.
STRINGPostalCode/20uniqueHash formula defaultText
STRINGState/80uniqueHash sha256 dtkSha256 formula defaultText
PICKLISTStateCodesha256 dtkSha256 defaultTextUse the sha256 if the picklist field is not restricted and its length is greater than 64 characters. Otherwise use defaultText.
TEXTAREAStreet/255uniqueHash sha256 dtkSha256 formula defaultText

Using the fixed hash function

You can use the fixed hash function to apply custom values that you need instead of using the built-in hash functions returning random strings.

The fixed has function for PROTECTED field

This function supports the following fields types:

  1. STRING

  2. TEXTAREA

  3. PICKLIST

  4. MULTIPICKLIST

  5. COMBOBOX

  6. TIME

  7. DATE

  8. DATETIME

  9. BOOLEAN

  10. PERCENT

  11. INTEGER

  12. LONG

  13. DOUBLE

  14. CURRENCY

  15. PHONE

  16. EMAIL

  17. URL

The length of the values that the fixed hash function can apply depends on the field type.

Deleting PROTECTED fields

note

You delete PROTECTED fields from the configuration of the InCountry Data Residency for Salesforce package only. These fields will be preserved in Salesforce itself.

You can delete the not needed PROTECTED fieds from the data store policy for a specific Salesforce object. Such fields will be no longer protected by the package when showing their values in the interface of Salesforce.

  1. Select the Salesforce object which PROTECTED fields you want to delete.

  2. On the list with PROTECTED fields, locate the one you want to delete.

    Select the field

  3. Click the box with the down arrow and then select Delete.

If you want to delete all the fields from the current configuration of the selected Salesforce object, click Delete All Fields.

← Managing data regulation policiesHashing the UserName field →
  • Managing PROTECTED fields
  • Adding PROTECTED fields
  • Using the deterministic tokenization functions
    • Generating the deterministic tokenization key
    • Specifics of the dtkSha256 function
    • Specifics of the formula function
    • Viewing the formula for the protected field
    • Limitations of the formula function
  • Selecting hash functions for PROTECTED fields inline
  • Supported field types and their hash functions
  • Hash function examples
    • Mapping fields to hash functions
    • Using the fixed hash function
  • Deleting PROTECTED fields
InCountry logo blue
© InCountry 2022.
All rights reserved. InCountry, Inc
  • PRIVACY POLICY
  • TERMS OF SERVICE
  • Social share
    • YouTube logo
    • Facebook logo
    • Twitter logo
    • LinkedIn
  • Column 1
    • Products
      • Products
        • InCountry for Salesforce
        • Data Residency-as-a-Service
        • Alibaba Cloud InCountry Service
        • Compliance and security
      • Gateways
        • Email
        • Payment Vault
        • Web Forms
        • HTML
      • Developers
        • REST API
        • SDK
  • Column 2
    • Solutions
      • Automotive
      • Energy
      • Financial services
      • Healthcare
      • Retail
      • Technology
    • Integrations
      • Cegid
      • Intertrust
      • MuleSoft
      • PayPal
      • Salesforce
      • ServiceNow
      • Stripe
      • Veeva Systems
      • Yandex
  • Column 3
    • Resources
      • Country compliance
      • Documentation
      • Library
      • Partners
      • Pricing
    • About
      • News and Blog
      • Careers
      • Contact Us
      • FAQ
      • Leadership