Managing Border configuration
You can manage the configuration of Border and define redaction and unredaction strategies, as well as define rules for data payloads that are subject to redaction or unredaction.
Before you proceed with the configuration of Border, you need to understand the principle of how Border works.
Border supports two data flows when
it redacts ingress data: converts clear-text values into tokenized values.
it unredacts egress data: converts tokenized values into clear-text values.
Redaction and unredaction rules define how Border handle data - either redacts or unredacts it. Border intercepts web requests with their payloads and acts accordingly to the configured redaction or unredaction rules. The intercepted values are either saved to the InCountry platform (in redaction rules) or queried from the InCountry platform (in unredaction rules). For example, for the POST, PUT, and UPDATE methods, you can apply redaction rules, for the GET method you can apply the unredaction rule.
Depending on the data format, the appropriate strategy to redact or unredact data should be applied. This greatly depends on your system architecture and handled values, as well as validation rules
To preserve the search capabilities, you need to explicitly indicate what values in the payload should be treated as searchable. You will be able to search for records against these values and other values will be stored as-is on the InCountry platform.
Redaction and unredaction rules deal with collections, so-called objects whose data undergoes redaction or unredaction. Border uses collections to produce unique hash values and identify the applicable redaction or unredaction strategies in the data communication pipeline.
Defining Border configuration
Open the environment where Border integration was created.
Click the Integration block.
On the list with integrations, locate the integration of the Border type.
Click the Configure Border icon. Portal opens the list of Border configurations.
Click New Configuration.
At the Parameters step, specify the following information:
Configuration Name - enter the name of the Border configuration.
Target - specify the URL of the endpoint through which regulated data is transferred.
When complete, click Next.
At the Redaction Rules step, add rules that will regulate how Border redacts regulated data passing through the endpoint. For the details on how to configure a redaction rule, please see the Managing redaction rules section.
When complete, click Next.
At the Unredaction Rules step, add rules that will regulate how Border unredacts regulated data passing through the endpoint. For the details on how to configure an unredaction rule, please see the Managing unredaction rules section.
When complete, click Next.
At the Review step, review the Border configuration you defined.
When complete, enter the verification code and click Submit.
Managing redaction rules
While defining the configuration of Border, you can set up redaction rules that regulate how Border redacts ingress regulated data passing through the endpoint. You can add multiple rules to redact data passing through different endpoints.
At the Redaction Rules step, click Add Rule.
Configure the redaction rule, as follows:
Method - select the request type, as follows:
GET- used to retrieve data.POST- used to submit/create new data.PUT- used to submit/create new data.PATCH- used to update data.DELETE- used to delete data.
Path - enter the URI path to the endpoint and append the regular expression if needed to handle cases when the slash is either present or not in the request.
Configure the operation mode, as follows:
Processing & Storage - ingress regulated data is saved to the InCountry platform and then it is redacted and passed to the endpoint.
Processing - ingress regulated data is redacted and passed to the endpoint without its saving on the InCountry platform.
Configure the collection, as follows:
Collection Name - enter the name of the collection in the JSON payload. In most scenarios use the name of the object which is managed by the current request.
Entity ID Path - enter the JSON path to the entity identifier in the response body returned to this request.
Entity Error Correction Field Path - enter the JSON path to the entity’s field carrying a unique identifier of the record, for example, email or SSN. It must be a redacted field with a random-output tokenization strategy (alphaNumeric, alphaNumericLowerCase, or email).
Global Entity ID - activate this option to allow Border to use the entity id as a profile key value directly without applying a key generation algorithm based on collection name and entity id. Use this option only when the entity id within the payload is a completely unique value that cannot be duplicated.
Click Add Strategy and configure the strategy, as follows:
Strategy - select the appropriate strategy to redact the regulated value from the available options. Please use the strategy that matches the value format.
alphaNumeric- applies an alpha-numeric hash to a string containing letters and numbers. The produced alphanumeric string varies during every redaction.alphaNumericLowerCase- applies a lower-case alphanumeric hash to a string containing letters and numbers.alphaPrepended- applies a prefix comprised of a single letter.email- applies an email-pattern string, e.g.dsf34fsdf@redactedemail.com. The produced email-pattern string varies during every redaction.plain- forwards the original value.one- applies '1' ( a single digit).zero- applies '0' (a single digit).numeric- applies a random numeric value of the length equal to the original value.dateISO- applies a random date in the ISO format.defaultDateISO- applies a random date in the default ISO format (1970-01-01T00:00:00Z).fixed- applies any hardcoded value. If you select this option, in the Value box, enter the value that should be applied by default.emailPersistent- applies an email-pattern string that remains the same for the same email address during every redaction.alphaNumericPersistent- applies an alpha-numeric hash that remains the same for the same alphanumeric string during every redaction.
Path - for each strategy, specify the JSON path to the field carrying a regulated value that should be redacted.
Length - enter the length for the hashed value if your system performs some validation of value length, otherwise leave this parameter empty.
Click Add Searchable and configure searchable values of the record, as follows:
Key - select the record’s key that will be used to store a searchable value of the record on the InCountry platform.
Value - enter the JSON path to the field that carries a value against which you want to search records. You can copy the corresponding values from the Path column.
When complete, click Next.
You can create multiple redaction rules within the same Border configuration.
Example of configuring redaction rules
Let’s say we have a system with the endpoint that creates users that is accessible at:
https://crm-services.com/api/authors/
The POST request passes a JSON payload to the endpoint. We want to redact this data, so the backend of our system will handle redacted data and clear-text regulated data is saved to the InCountry platform.
Request example:
The request is used to create new authors.
POST https://crm-services.com/api/authors/
{
"author_alias": "acdoyle",
"email": "acdoyle@gmail.com",
"first_name": "Arthur",
"middle_name": "Conan",
"last_name": "Doyle",
"birthdate": "1859-05-22",
"address": {
"street": "221b, Baker street",
"city": "London",
"location": "Sherlock Holmes Shelter"
}
}
Response example:
When a new author is created, their ID is returned in the response.
{
"author_id": "ACD4668774"
}
There is one more request that can be used to update the author’s data, like this:
PATCH https://crm-services.com/api/authors/ACD4668774
{
"email": "acdoyle@hotmail.com"
}
Knowing the request format and response format, we can proceed with the configuration of a redaction rule for Border.
| Parameter | Value | Notes |
|---|---|---|
Target |
| Here you need to place the URL of your system only. Please avoid putting a slash at the end of the URL. |
Method |
| Use the actual method type. For redaction rules, the commonly used method types are:
|
Path |
| Here you need to provide the URI path of the endpoint and append the regular expression to correctly handle the situation when the endpoint has or has no slash at the end. |
Operation Mode |
| Select the Processing & Storage value if you need to redact regulated data and store it on the InCountry platform. Select the Processing value if you need to redact regulated data and proxy it to the endpoint without saving to the InCountry platform. |
COLLECTION | ||
Collection Name |
| Use some meaningful name denoting the entity which the endpoint deals with. |
Entity Id Path |
| Add the JSON path to the unique record identifier in the response. If the identifier is placed within the nested groups, please use the full path to the identifier in the JSON payload. Please follow this pattern: |
Entity Error Correction Field Path |
| Here you need to specify the JSON path to to the entity’s field carrying a unique identifier of the record, for example, email or SSN. It must be a redacted field with a random-output tokenization strategy ( |
Global Entity ID | Unchecked | You can activate this option if you want to fetch regulated data from the InCountry platform through REST API or SDK by querying By default, the |
Strategies | ||
Strategy 1 |
| Select the strategy to hash the first name. |
Path 1 |
| Enter the JSON path to the |
Length 1 | 20 | Enter the number of characters in the produced redacted value, if your system has some validation of the value length, you can enter the expected length of the hashed value. |
Strategy 2 |
| Select the strategy to hash the middle name. |
Path 2 |
| Enter the JSON path to the |
Length 2 | 20 | Enter the number of characters in the produced redacted value, if your system has some validation of the value length, you can enter the expected length of the hashed value. |
Strategy 3 |
| Select the strategy to hash the last name. |
Path 3 |
| Enter the JSON path to the |
Length 3 | 20 | Enter the number of characters in the produced redacted value, if your system has some validation of the value length, you can enter the expected length of the hashed value. |
Strategy 4 |
| Select the strategy to hash the email. |
Path 4 |
| Enter the JSON path to the |
Length 4 | 20 | Enter the number of characters in the produced redacted value, if your system has some validation of the value length, you can enter the expected length of the hashed value. |
Strategy 5 |
| Select the strategy to hash the birthdate. |
Path 5 |
| Enter the JSON path to the |
Strategy 6 |
| Select the fixed strategy if you want to apply the default value to all such values of records. |
Path 6 |
| Enter the JSON path to the street value within the |
Value 6 |
| Enter the JSON path to the |
SEARCHABLE | ||
Searchable Key 1 |
| Select the keyN field to store the value as searchable. |
Value 1 |
| Enter the JSON path to the |
Searchable Key 2 |
| Select the keyN field to store the value as searchable. |
Value 2 |
| Enter the JSON path to the |
Searchable Key 3 |
| Select the keyN field to store the value as searchable. |
Value 3 |
| Enter the JSON path to the |
Searchable Key 4 |
| Select the keyN field to store the value as searchable. |
Value 4 |
| Enter the JSON path to the |
As the result, the configuration of Portal should look like this:
Managing unredaction rules
While defining the configuration of Border, you can set up unredaction rules that regulate how Border unredacts outgress regulated data passing through the endpoint. You can add multiple rules to unredact data passing through different endpoints.
At the Unredaction Rules step, click Add Rule.
Configure the unredaction rule, as follows:
Method - select the request type, as follows:
GET- used to retrieve data.POST- used to submit/create new data.PUT- used to submit/create new data.PATCH- used to update data.DELETE- used to delete data.
Path - enter the URI path to the endpoint and append the regular expression if needed to handle cases when the slash is either present or not in the request.
Click Add Collection and configure the collection, as follows:
Collection Name - enter the name of the collection from the redaction rule. Border will use the name of the collection to identify records pertaining to the collection name to unredact their hashed values. When the response combines multiple collections, you need to properly reference them in the configuration.
Entity ID Path - enter the JSON path to the entity identifier in the response. When using nesting for multiple objects within the same response body, please verify that your JSON path points to the correct position.
Entity Error Correction Field Path - enter the JSON path to the entity’s field carrying a unique identifier of the record, for example, email or SSN. It is a redacted field with a random-output tokenization strategy (alphaNumeric or alphaNumericLowerCase).
Global Entity ID - activate this option if you pass the existing record’s identifier in the request which is used in the profile_key field of the record stored on the InCountry platform.
Click Add Strategy and configure the strategy, as follows:
Path - enter the JSON path to the field carrying a regulated value that should be unredacted.
Original Path - enter the original JSON path to the field carrying a regulated value that should be unredacted. You can leave this box empty, it is optional.
Check the Error Correction Field option for the strategy that deals with the unique identifier of the record user for error correction, for example, email or SSN.
When complete, click Next.
You can create multiple unredaction rules within the same Border configuration.
You can create multiple collections when you need to unredact data of multiple objects outputted within the same response.
Example of configuring unredaction rules
Let’s say we have a system with the endpoint that allows you to get the list of posts written by each author:
https://crm-services.com/api/authorPosts/
The GET request passes a JSON payload to the endpoint. We want to unredact this data, so the backend of our system will handle redacted data and clear-text regulated data will be rendered on the frontend side.
Request example:
The request is used to query posts of authors.
GET https://crm-services.com/api/authorPosts/
Response example:
The response contains an array of posts with information about authors.
[
{
"post_id": 646494631654876941313,
"title": "Conan Doyle announces a new story",
"post_body": "Conan Doyle will soon announce a new store about Sherlock Holmes",
"author": {
"author_id": "ACD4668774",
"author_alias": "acdoyle",
"email": "acdoyle@gmail.com",
"first_name": "Arthur",
"middle_name": "Conan",
"last_name": "Doyle",
"birthdate": "1859-05-22"
}
},
{
"post_id": 6464946316548769413547,
"title": "Agatha Christie releases a new detective story",
"post_body": "Agatha Christie is about to publish a new detective story about Hercule Poirot",
"author": {
"author_id": "AMC4668778",
"author_alias": "amcchristie",
"email": "achristie@gmail.com",
"first_name": "Agatha",
"middle_name": "Mary Clarissa",
"last_name": "Christie",
"birthdate": "1890-09-15"
}
]
Knowing the request format and response format, we can proceed with the configuration of an unredaction rule for Border.
| Parameter | Value | Notes |
|---|---|---|
Target |
| Here you need to place the URL of your system only. Please avoid putting a slash at the end of the URL. |
Method |
| Use the actual method type. For unredaction rules, the commonly used method types is:
|
Path |
| Here you need to provide the URI path of the endpoint and append the regular expression to correctly handle the situation when the endpoint has or has no slash at the end. |
Collection | ||
Collection Name |
| Specify the name of the collection you used in the redaction rule. In our case, the collection name is authors, as we want to unredact PII data of authors. |
Entity Id Path |
| Add the JSON path to the unique record identifier in the response. If the identifier is placed within the nested groups, please use the full path to the identifier in the JSON payload. Please follow this pattern: |
Entity Error Correction Field Path |
| Here you need to specify the JSON path to the record’s value that carries a unique identifier that can be used for error correction. |
Global Entity ID | Unchecked | You can activate this option if you want to fetch regulated data from the InCountry platform through REST API or SDK by querying By default, the |
Strategies | ||
Path 1 |
| Enter the JSON path to the |
Original Path 1 |
| Enter the JSON path to the |
Path 2 |
| Enter the JSON path to the |
Original Path 2 |
| Enter the JSON path to the |
Path 3 |
| Enter the JSON path to the |
Original Path 3 |
| Enter the JSON path to the |
Path 4 |
| Enter the JSON path to the |
Original Path 4 |
| Enter the JSON path to the |
Error Correction Field | Checked | Activate the option for the email value that was used as an error correction field in the redaction rule. |
Path 5 |
| Enter the JSON path to the |
Original Path 5 |
| Enter the JSON path to the |
As the result, the configuration of Portal should look like this:
Editing Border configuration
On the list with Border configurations, locate the configuration you want to edit.
Click the Edit icon.
Make the required modifications to the Border configuration.
Save the configuration.
Viewing Border configuration details
When using Border for creating a custom configuration for the Salesforce package, you may need to view the configuration details to automatically populate Border configuration with the redaction rules from the Salesforce package.
On the list with Border configurations, locate the configuration you want to view.
Click the View icon.
Save the Border configuration details. Click Download Text to save Border configuration details as a text file. Click Copy to Clipboard to copy Border configuration details to the clipboard. Use the acquired Border configuration parameters to configure the InCountry Data Residency for Salesforce package.
When complete, click Close.
Deleting Border configuration
On the list with Border configurations, locate the configuration you want to view.
Click the Delete icon.
Enter the verification code and then click Delete.