DataMasque Portal

Salesforce connections

Preview feature. Salesforce connections are available only after an admin has enabled preview features on the Settings page. While preview features are off, the Salesforce connection type is not offered, existing Salesforce connections are hidden, and runs against them are refused.

A DataMasque connection for Salesforce requires an External Client App in the target org and an integration user that app is allowed to impersonate. See Salesforce Authentication.

Masking process

DataMasque masks Salesforce records in place through the Salesforce Bulk API 2.0. For each object in the ruleset, DataMasque reads the records with a Bulk API query job, masks them, and writes them back with a Bulk API update job that matches each record on its Id.

Important! The write-back is an ordinary record update. Apex triggers, validation rules, workflow rules and flows that are active on the object can run against the masked values. See Org automation.

Required privileges

Salesforce permission set

Assign the integration user a permission set that:

  • enables the API Enabled user permission, and
  • is named in the External Client App's permitted-users policy. See Salesforce Authentication.

Object and field access is granted the same way as for any Salesforce user:

  • Read on every object in the ruleset.
  • Edit on every field the ruleset masks.

DataMasque uses the Tooling API to list the org's automation and to disable Apex triggers and validation rules during a run. See Org automation. Disabling a trigger needs the Author Apex permission, and disabling a validation rule needs Customize Application.

  • If the user cannot list the automation, the run masks with that automation left on, and the run log says so.
  • If the org refuses to disable an item, the run re-enables what it already disabled and stops before it masks anything.

Connection parameters

Salesforce specific parameters

For Salesforce connections, the following additional fields are required:
Salesforce instance URL The org's My Domain URL. For example, https://example--uat.sandbox.my.salesforce.com.
Salesforce login URL The org's My Domain URL, normally identical to the instance URL. See Salesforce Authentication.
Consumer key The consumer key of the External Client App configured for the JWT bearer flow.
Integration username The Salesforce Username of the integration user that the External Client App impersonates. This is often different from the user's email address.
Private key file name The PEM-encoded RSA private key that signs the authentication assertion. See Salesforce Authentication.

The following fields are optional:
Private key fileset A connection fileset that holds the private key. See Salesforce Authentication.
Private key passphrase Required only when the private key file is encrypted. Leave blank for an unencrypted key.
Salesforce API version The REST and Bulk API version to call, as a major and minor number with no leading v, for example 62.0. Defaults to 62.0.

Salesforce Authentication

Salesforce connections authenticate with the OAuth 2.0 JWT bearer flow against an External Client App. DataMasque signs a short-lived assertion with an RSA private key, and Salesforce verifies it against the certificate registered on the app.

Configure the following:

  1. The External Client App, created in the target org, with the JWT bearer flow enabled and the api OAuth scope. Its consumer key is the Consumer key on the connection.
  2. The certificate on the app, which must be the certificate for the private key DataMasque holds. If they do not match, authentication fails with invalid_assertion.
  3. A pre-authorised user. Set the app's permitted-users policy to Admin approved users are pre-authorized and grant the app through a permission set assigned to the integration user. An External Client App does not appear in a profile's Connected App Access list. Without this, authentication fails with invalid_app_access.
  4. The login URL, which must be the org's own My Domain URL. With login.salesforce.com or test.salesforce.com, authentication fails with app_not_found.

The private key must be a PEM-encoded RSA private key (-----BEGIN PRIVATE KEY-----). Other key types are rejected. If the key file is encrypted, supply its passphrase as well.

There are two ways to supply the key:

  • Upload it as a supplementary file, and enter its path relative to the supplementary files directory as the Private key file name.
  • Upload a ZIP file that holds the key on the Files page, select it as the Private key fileset, and enter the key's path within the ZIP file as the Private key file name. Use a fileset when several connections point at different orgs.

Limitations

Fields that cannot be masked

DataMasque refuses a ruleset that masks one of these fields:

  • Id, the record key.
  • System audit fields: CreatedById, CreatedDate, LastModifiedById, LastModifiedDate, SystemModstamp, LastActivityDate, LastViewedDate, LastReferencedDate and IsDeleted.
  • Derived fields: formula, roll-up summary and auto-number fields. Mask the fields that a formula or roll-up references instead.
  • Compound fields such as BillingAddress and geolocation fields. Mask their components (BillingStreet, BillingCity, and so on) instead.
  • Fields the integration user cannot edit, normally because of field-level security.

imitate_date masks need explicit bounds

An imitate_date mask on a Salesforce connection must be given both min and max.

Salesforce storage behaviour

Salesforce normalises some values as it stores them, so a masked value is not always read back exactly as it was written:

  • An empty string is stored as NULL. A mask that produces an empty value nulls the field.
  • Leading and trailing whitespace is trimmed from text fields.
  • Date values must fall between 1700-01-01 and 4000-12-31. Salesforce rejects anything outside that range. Narrow date masks configured with a wider range.

Restricted picklists

A mask on a restricted picklist must produce values from the picklist's active values. DataMasque checks the masked values against the picklist, and fails the run before it writes a value that is not in it. An empty masked value clears the field.

Org automation

When a Salesforce connection is tested, DataMasque lists the org's active Apex triggers, active validation rules, workflow rules, and active flows as a connection warning. The connection is still usable.

A masking run disables the active Apex triggers and validation rules on the objects in the ruleset, and re-enables them when the run ends. Automation that was already inactive stays inactive. Nothing is disabled on a dry run or on a read-only connection. Set auto_manage_triggers to false on the ruleset, or on a single mask_table task, to leave the org's automation on.

A run that is stopped by force or crashes can leave these items disabled. After such a run, check the Apex triggers and validation rules on the masked objects in Salesforce Setup, and re-activate any that are still inactive.

Workflow rules and flows are not disabled. Either can overwrite a masked value or reject the update. Switch them off for the duration of the run, or leave the affected objects out of the ruleset.

Narrowing a discovery run

Salesforce has no schemas. The schema names you enter when starting schema discovery are namespaces, matched case-insensitively. Contact and Invoice__c belong to the org, and ACME__Invoice__c belongs to the ACME package.

  • Enter c to cover only the objects the org itself owns.
  • Enter a package's namespace to cover only that package's objects.
  • Enter nothing to cover every namespace.

The discovery result and any ruleset generated from it name each object without a namespace.

A discovery configuration can also list tables patterns. For Salesforce, the schema part of a pattern is SALESFORCE, for example SALESFORCE.Invoice__c.

Discovery reads the first records of an object

In-data discovery profiles the first records of each object in Id order, not a sample from across the whole object.

Unsupported features

The following tasks are not supported for Salesforce connections:

  • mask_unique_key.
  • truncate_table.
  • build_temp_table.
  • run_data_discovery. In-data discovery is still available as part of a discovery run.
  • run_sql.

The where, joins and alias options and use_calculated_bounds: false are not supported in mask_table tasks. Use conditional masking with if in place of where.

The following are also not supported:

Supported data types

DataMasque converts each value to the type the mask expects, from the field type that Salesforce reports.

Salesforce field type Value seen by masks
int, long, double, currency, percent A whole number when the field has no decimal places, otherwise a decimal
boolean Boolean
date Date
datetime Timestamp without a timezone, normalised to UTC
time Time of day
string, textarea, picklist, email, phone, url, reference, and all other types Text

Notes:

  • A ruleset can compare a datetime value against a plain UTC timestamp such as 2024-01-01 00:00:00.
  • An empty string and a null are both read as null.
  • A value that cannot be converted is passed to the mask as text.

Unsupported key columns

Salesforce connections always use the record Id as the key. DataMasque ignores a key given in the ruleset, and the run log says so.