InCountry logo
mobile-nav
Search
  • Products
    • Platform
      • Overview
      • Compliance and security
      • How it works
      • For SaaS
      • For internal apps
    • Gateways
      • Email
      • HTML
      • Payments
      • Web Forms
  • Solutions
    • Energy
    • Financial services
    • Healthcare
    • Retail
    • Technology
  • Integrations
    • SaaS
      • Cegid
      • Intertrust
      • Mambu
      • PayPal
      • Salesforce
      • Segment
      • ServiceNow
      • Stripe
      • Twilio
      • Veeva Systems
    • IAAS
      • InCountry on Alibaba Cloud
      • InCountry on Yandex.Cloud
  • Resources
    • Country compliance
    • Documentation
    • Library
    • Partners
    • Pricing
  • About
    • Blog
    • Careers
    • Contact Us
    • FAQ
    • Leadership
  • Login
  • Schedule a Demo

›Border

Home
  • InCountry Platform
Portal
  • Getting started
  • Documentation
    • Dashboard
    • Managing environments
    • Managing clients and integrations
    • Managing Border configuration
    • Managing serverless scripts
    • Managing file imports
    • Managing profile and organization
    • Managing users
    • Managing secret keys
    • Managing recommendation modules
    • Managing subscription
  • Release notes
Border
  • Documentation
  • Release notes
REST API
  • Documentation
  • How to test CRUD requests through REST API
  • Release notes
Serverless
  • 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 serverless functions
    • Managing InCountry cache
    • Managing Apex triggers
    • Managing record synchronization
    • Using Email-to-Case feature
    • Debugging
  • 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
    • FAQ
    • Release notes
Payment Vault
  • Documentation
BYOK
  • Documentation
FAQ
  • How to use the InCountry platform
  • Integration options
  • Data regulation models
  • Limits and quotas
  • Video tutorials
Service Status
  • Status

InCountry Border documentation

This guide provides information about InCountry Border and how you can use it for implementation of data residency services without using the REST API or SDK.

Overview

InCountry Border is a component of InCountry Ecosystem which allows you to take advantage of data residency services without developing any solutions with the InCountry SDK. This component integrates between your customer-facing frontend and system backend. It provides on-the-fly redaction and unredaction of regulated or sensitive data transmitted during execution of API requests.

Data redaction and unredaction rules are specified within a YAML file. This configuration file is further deployed on the InCountry Border side.

Diagram

Pre-requisites

Before you proceed to using InCountry Border you need to do the following:

  1. Identify all REST endpoints which you want to integrate with InCountry Border and create a list of them.
  2. Identify data that is passed or retrieved from each REST endpoint.
  3. Identify which data is regulated and which data can be used as is. Regulated data will further follow the redaction and unredaction rules which InCountry sets up for you.

Requirements for REST requests

InCountry Border imposes several requirements for execution of REST requests, as follows:

  1. Data requests are performed through RESTful API. Data is communicated in the JSON format between the customer-facing frontend and system backend of the application.
  2. For the correct execution of modification (create, update) requests, there must be a field (error correction field) with a random output redaction strategy on it.
  3. id of a newly created record must be present in the response to the request for creating a new record.
  4. id of the record should be present in the body of a request or in the URL request (for example, POST /users/1) in data requests for updating records.
  5. id of the record should be present in the URL request for data requests for deleting records.
  6. Data requests should be performed in the JSON format (content-type: application/json) if data redaction should be applied. Other data formats will be ignored and will be passed as is.

Data redaction flow

Data redaction is automatically applied by InCountry Border according to the configured data redaction rules.

Let’s imagine a situation. We have a system which allows you to manage media content in the format of pages. The system provides the basic capabilities for managing these pages (like creating, reading, updating, or deleting). The page entity includes both regulated and non-regulated data, as follows:

{
  "title": "Page title",
  "author_name": "Author name", // PII data
  "author_email": "Author email", // PII data
  "created_at": "Date of creation"
}

Within this data structure we want to redact the two data fields with regulated data author_name and author_email. The rest of fields should be passed as is without redaction.

We publish a newly created page by sending a POST request to the REST endpoint, as follows:

POST /pages

{
  "title": "How to follow compliance requirements",
  "author_name": "John Doe",
  "author_email": "john.doe@gmail.com",
  "created_at": "2000-09-23T08:06:07.217Z"
}

To correctly handle data redaction of these two fields, InCountry Border will apply two strategies to the executed data request to the /pages endpoint. In the current example we have two regulated fields, for each field a specific strategy is applied. Each strategy may take additional parameters. In our case, the path and strategy parameters are applied, as follows:

  1. The path parameter is a jsonpath string which defines the field in the request body.
  2. The strategy is a tokenization algorithm whish is applied to the field according to the redaction policy.

InCountry Border supports the following tokenization algorithms:

  1. alphaNumeric applies an alpha-numeric string.
  2. alphaNumericLowerCase applies the alpha-numeric string in lower case.
  3. alphaPrepended applies a prefix comprised of a single letter.
  4. email applies an email-valid string, e.g. dsf34fsdf@redactedemail.com.
  5. plain forwards the original value.
  6. one applies '1' ( a single digit).
  7. zero applies '0' (a single digit).
  8. numeric applies a random numeric value of the length equal to the original value.
  9. dateISO applies a random date in the ISO format.
  10. defaultDateISO applies a random date in the default ISO format (1970-01-01T00:00:00Z).
  11. fixed applies any hardcoded value.

Once InCountry Border captures this POST request, it applies strategies and modifies the request, as follows:

{
  "title": "How to follow compliance requirements",
  "author_name": "eifsd42fds",
  "author_email": "nvstwe31ds@incountry.com",
  "created_at": "2000-09-23T08:06:07.217Z"
}

Along with tokenization, InCountry Border also performs encryption of regulated data prior to its saving to the InCountry platform.

The key1 - key10 attributes can be used for record lookup and must be explicitly defined in the Searchable section within the configuration file. These keys may contain non-regulated data too.

{
  "record_key": "UUID",
  "body": "encrypted(PII object)",
  "key1": "PII_field1_token",
  ...,
  "keyN": "non-regulated data field",
}

The key1 and key2 attributes may be empty if the author_name and author_email fields are not marked as searchable.

Upon successful data saving, InCountry Border can further forward a tokenized request to the customer’s backend. At this point the regulated data is stored in the encrypted format in InCountry platform and tokenized data is sent to the customer’s backend. The backend returns an identifier of a newly created record.

InCountry Border intercepts this response and updates the profile_key with the actual value from the customer’s database.

Following up on this example, let’s try to read information about the saved page including the redacted data about it. In our case the page identifier equals to page1, so our request will be as follows:

GET /pages/page1

Data that is stored about this page in InCountry platform is the following:

{
  "record_key": "some UUID",
  "body": "encrypted({author_name, author_email})",
  "key1": "eifsd42fds",
  "key2": "nvstwe31ds@incountry.com"
}

Data that is stored about this page in the customer’s database is the following:

{
  "pageId": "page1",
  "title": "How to follow compliance requirements",
  "author_name": "eifsd42fds",
  "author_email": "nvstwe31ds@incountry.com",
  "created_at": "2000-09-23T08:06:07.217Z"
}

InCountry Border supports the three basic types of backend-frontend interactions:

  1. mutation (POST, PUT)
  2. deletion (DELETE)
  3. reading (GET)

If you need to mutate an entity which includes regulated data, InCountry Border redacts this query and saves regulated data into InCountry platform and forwards the data request with tokenized data.

If you need to get regulated data, InCountry Border unredacts data stored in the customer’s database by using the previously data from the InCountry platform.

Configuration YAML file

note

The configuration YAML file is produced by InCountry team per your request.

The configuration YAML file is used to manage behavior of InCountry Border for data redaction. The file structure looks, as follows:

rules:
    country: SG #Country code, which is used to construct PoPAPI request.
    supported_countries: #The list of countries where PII redaction/unredaction is allowed
    - SG
    features: #Additional features list to switch on
    - geoip #Determining ip address where the request came from
    target: "" #Tenant's API base URL backend where to forward requests
    vaultKeyPath: "/v1/secret/data/incountry" #Secret key path in Vault for encryption/decryption
    endpoint: "https://sg-mt-01.uat.incountry.io" #PoPAPI endpoint
    environmentId: "<env_id>"
    oauth:
    clientId: "<client_id>"
    clientSecret: "<client_secret>"
    authEndpoints:
      default: "https://auth-apac.uat.incountry.com/oauth2/token"
    redactions: #This section describes rules applied to the request on the way from the frontend to the backend.
    - path: "/users" #RegExp to match request Path
      method: POST #Request method to match
      collectionName: "users" #Tenant's collection name. For example users for the users collections. It is used along with Entity ID in order to uniquely identify the document across all the tenant's documents.
      entityIdPath: "$.id" #JSONPath for the field containing Entity ID. Entity ID is an identifier for the document in the tenant's DB.
      entityErrorCorrectionFieldPath: "$.email" #JSONPath for the field that is used for error correction. Error correction mechanism is described in Border Architecture document.
      searchable: #Make the following InCountry storage fields searchable by defined fields values
      key2: "$.name" #JSONPath for the field containing searchable value
      key3: "$.email"
      strategies: #An array of objects, that describe modifications (redactions) applied to request fields
      - strategy: alphaNumeric #A name of tokenization strategy, applied to the matching field
        path: "$.name" #JSONPath for the field. According to this path strategy is applied
      - strategy: email
        path: "$.email"
    - path: "/users/.+"
      method: PATCH
      collectionName: "users"
      entityIdPath: "$.id"
      entityErrorCorrectionFieldPath: "$.email"
      searchable:
      key2: "$.name"
      key3: "$.email"
      strategies:
      - strategy: alphaNumeric
        path: "$.name"
      - strategy: email
        path: "$.email"
    - path: "/users/(.+)"
      method: DELETE
      isDeleteRequest: true #Boolean flag that indicates request as a delete request. Unlike the other requests, for delete request we want to forward request to the customer's backend first.
      collectionName: "users"
    unredactions: #This section describes rules applied to the response from the tenant's backend
    - path: "/users/(.+)"
      method: GET
      collections: #Each response potentially may contain data from multiple collections. For example, when you fetch posts data, it may also include user data (post's author). Each collection item must describe all the needed unredactions for the matching path.
      - name: "users"
        entityIdPath: "$.id"
        entityErrorCorrectionFieldPath: "$.email"
        strategies:
        - path: "$.name"
        - path: "$.email"
          isErrorCorrectionField: true #Means that this field will be used for error correction. Error correction mechanism is described in Border Architecture document.
    - path: "/users"
      method: GET
      collections:
      - name: "users"
        entityIdPath: "$[*].id"
        entityErrorCorrectionFieldPath: "$.email"
        strategies:
        - path: "$.name"
        - path: "$.email"
          isErrorCorrectionField: true
    - path: "/users"
      method: POST
      collections:
      - name: "users"
        entityIdPath: "$.id"
        entityErrorCorrectionFieldPath: "$.email"
        strategies:
        - path: "$.name"
        - path: "$.email"
          isErrorCorrectionField: true

The YAML file is comprised of the three data groups, as follows:

  1. meta information
  2. redactions
  3. unredactions

Meta information

ParameterDescription
countryCountry code which is used to construct a PoPAPI request.
targetAddress of the customer’s backend which requests are forwarded to.
endpointURL address of PoPAPI server.
clientIdClient ID which was issued on the InCountry Portal for a specific environment.
clientSecretClient secret which was issues on the InCountry Portal for a specific environment.
environmentIdIdentifier of the environment for accessing the specified PoPAPI server.

Redactions

This group of parameters defines the rules applied to the data request when passing it from the customer-facing frontend to the application’s backend. Each rule may include the following fields:

ParameterDescription
pathA regular expression to match the request’s path.
methodA request method that is matched by InCountry Border.
entityIdPathJSONPath for the field containing an Entity ID. The Entity ID is an identifier for the document in the customer's database.
entityErrorCorrectionFieldPathJSONPath for the field that is used for error correction.
collectionNameA customer's collection name. For example pages for the pages collection. It is used along with Entity ID in order to uniquely identify a record throughout all the customer's records.
isDeleteRequestA boolean flag that marks a request as a delete request. Unlike the other requests, for running a delete request we need to forward a request to the customer's backend first.
strategiesAn array of objects that define modifications (redactions) applied to the request fields.
strategyA name of a tokenization strategy that is applied to the matched field.
pathJSONPath for the field. According to this path a corresponding strategy is applied.

Unredactions

This group of parameters defines the rules applied to the response from the customer's backend. Each rule may include the following fields:

ParameterDescription
pathA regular expression to match the request’s path.
methodA request method that is matched by InCountry Border.
collectionsEach response may potentially contain data from multiple collections. For example, when you fetch pages data, it may also include authors data (author of a page). Each collection item must describe all the needed unredactions for the matching path.

Request structure and modifications

When integrating InCountry Border into your system, please ensure that the application’s frontend points to InCountry Border instead of the application’s backend, so all the requests are passed through InCountry Border.

An example of URL for the tenant’s application frontend looks as follows:

https://{border_url}/x-inc-{tenant}/{tenant_rest_enpoint}

For a single-tenant deployment, you can specify the tenant identifier. In this case, you do not need to specify the header or postfix.

https://{border_url}/{tenant_rest_enpoint}

The URL is comprised of the following parts:

  1. {border_url}: URL of InCountry Border you want to use.
  2. {tenant}: Name of the tenant (customer).
  3. {tenant_rest_endpoint}: REST endpoint (for example /pages/page1).

Alternatively, you can define a tenant through the X-INC-CLIENT-ID header when performing requests through InCountry Border. This approach will not work when using the CORS policy for handling requests, because custom headers are not allowed in the preflight requests. In this case, the URL to point for the tenant’s application frontend will be as follows:

https://{border_url}/{tenant_rest_enpoint}

Let’s imagine a case when the country of data origin is Singapore. The name of the tenant is 'incountry'. We also want to use InCountry Border deployed in Singapore and its endpoint, as follows:

https://sg-proxy-mt-01.uat.incountry.io

InCountry Border is using Singapore PoPAPI

https://sg-mt-01.uat.incountry.io

The resulting URL for endpoint that should be used by the tenant’s application frontend will be as follows:

https://sg-proxy-mt-01.uat.incountry.io/x-inc-incountry/pages/page1

or

https://sg-proxy-mt-01.uat.incountry.io/pages/page1

or

https://sg-proxy-mt-01.uat.incountry.io/pages/page

For the second URL you need to use the request header X-INC-CLIENT-ID=incountry.

You need to replace all the existing REST endpoints that the application frontend uses with the modified URL’s passing requests through InCountry Border.

Email Gateway

Email Gateway is a part of InCountry Border. It resides between the customer’s application (SaaS platform) that sends outbound emails and the customer’s SMTP server located in the recipient’s country of origin. It captures outbound emails with regulated data placeholders, identifies them according to the pre-defined patterns, and then substitutes these placeholders with clear-text values, such as names and email addresses. Once the data is unredacted, it sends emails via a direct SMTP connection to the customer’s SMTP server that further delivers this email to target recipients.

Email Gateway Architecture

Email handling workflow

Typically, a client application sends an email with regulated data directly to the addressee, violating local data regulations if the application server is located in a country different from the recipient’s country of origin. With the InCountry platform, the client application sends an email with placeholders containing hashed values to Email Gateway that identifies them and retrieves regulated data from the InCountry platform against the specific identifiers. Email Gateway replaces these placeholders with the recipient’s name and email address in the TO, FROM, SUBJECT, and BODY fields of the outbound email. Then it sends the email with clear-text values to the customer’s SMTP server that delivers an email with regulated to the recipient.

Email Gateway works in conjunction with InCountry Border and uses the shared configuration that defines SMTP authentication credentials for the customer’s SMTP server. The customer’s SMTP server must be in the recipient’s country of origin so that no compliance regulations are violated.

This allows the customers' applications to comply with data residency regulations without modifying the underlying codebase and setting up data stores for regulated data in multiple countries.

Email Gateway Data Flow

Email requirements

Email Gateway imposes requirements on emails. as follows:

  1. Only one addressee is in the To field.

  2. The CC and BCC fields are ignored during the email handling.

  3. The From and To fields, as well as the email subject and email body, are unredacted if placeholders match the pre-defined patterns.

  4. The From and To fields should contain redacted email addresses of the specific pattern, like email@profile_key006jkdsa00000oLpo.se.

  5. The email’s subject and body can contain placeholders with redacted data that will be replaced with clear-text values upon unredaction like %profile_key=006jkdsa00000oLpo,price%.

  6. Emails in the HTML and plain-text formats are supported.

  7. Attachments within emails will be forwarded as is without any additional pprocessing.

  8. The customer’s SMTP server should be available in the target country.

Configuration of Email Gateway

Configuration of Email Gateway is a part of InCountry Border configuration. Below you can find a typical configuration of Email Gateway:

# InCountry Border configuration
rules:
 country: US # PoP API country
 vaultKeyPath: "/v1/secret/data/test" # path to the secret in vault
 endpoint: "https://us-mt-01.qa.incountry.io" # PoP API URL
 oauth:
  clientId: "58e5ccf4-d9a5-4715-adda-abf4404ad99d"
  clientSecret: "tXjnUvG5FX7qMFDWAUhzIWJEv2"
  authEndpoints:
    default: "https://auth-emea.qa.incountry.com/oauth2/token"
 environmentId: "2c4890b1-2321-4a81-830c-b71631dce5f4"
 # other props - redaction, unredaction, etc

 # Email Gateway configuration
 email:
  client:
    host: "smtp.company.com"
    port: 25
    username: "username123"
    password: "mTLEY00tQHmy1kprS2HhAg"

Within the Email Gateway configuration you need to define the following parameters:

ParameterTolerated valuesDescription
hostsmtp.company.comAddress of the SMTP server which emails are proxied to.
usernameusername123Client ID that is used for SMTP authentication.
passwordmTLEY00tQHmy1kprS2HhAgClient Secret that is used for SMTP authentication.
port25, 465, 587 or 2525SMTP port that is used for sending emails.

Handling placeholders within emails

Email Gateway receives an email and parses it to the JSON object, as follows:

{
  "from": "john.doe@mail.com",
  "to": "jane.doe@mail.com",
  "subject": "Hello, %profile_key=006jkdsa00123oLpo,name%! Personal discount update notification",
  "text": "%token=test_token_123%Hello, %profile_key=006jkdsa00123oLpo,name%! \n Your current discount is %profile_key=006jkdsa00000oLpo,amount%! test"
}

The email body is placed within the text property that should have a pre-defined structure.

  1. The beginning of an email body should include the authentication token for InCountry Border like %token=<BORDER_AUTH TOKEN>%. This token is provided by InCountry.

  2. For each record, you need to specify a token that will be further used to replace this token with a clear-text value of the record. For example. the following expression is used %profile_key=006jkdsa00123oLpo,name%. In this case, Email Gateway through InCountry Border will look up a record with profile_key=006jkdsa00123oLpo and then use the name field from the payload. In such situation, Email Gateway pulls the record’s data from the InCountry platform and replaces placeholders with their actual values:

{
  "recordKey": <uid>,
  "body": JSON({"name": "John", "amount": 100}),
  "profile_key": "006jkdsa00123oLpo",
  ...
}

HTML Gateway

HTML Gateway is a part of InCountry Border. It resides between the customer’s monolithic web application that generates HTML pages and the user who works with this monolithic application. It captures the generated HTML pages outputted by the monolithic, identifies regulated data placeholders, and swaps them with their clear-text values pulled from the InCountry platform. The HTML structure with clear-text values is passed to the user’s browser for rendering. HTML Gateway is needed when your monolithic application resides in one country and users work with it from countries with stringent data regulations and requirements for handling personal data. In this case, HTML Gateway resides in the user’s country of origin and pulls regulated data from the InCountry platform within the same country, so regulated data does not touch your monolithiс web application backend, which keeps your company compliant with data regulations.

HTML Gateway Architecture

HTML structure handling workflow

Typically, a monolithic application generates an HTML page structure with all the regulated data and passes it to the end-user without considering their actual location. In some cases, this can violate the local or regional data regulations, as the monolithic application is hosted in one country, while end-users can use it from other countries having their own data regulations. The outputted HTML page structure containing regulated data values that we filled out can cause compliance issues that may finally result in fees or unexpected sanctions. All this may have a negative impact on the company brand and deliberately cause customer churn or loyalty decrease.

HTML Gateway Data Flow

HTML Gateway integrates with your monolithic web application and complements the process of generating HTML page structure by replacing regulated data placeholders with their actual values. Your monolithic web application does not directly handle regulated data values but inserts special placeholders containing record identifiers and a field key. HTML Gateway intercepts this HTML page structure and identifies regulated value placeholders within the HTML page code. For each placeholder within this structure, HTML Gateway fetches the clear-text value from the InCountry platform located in the end user’s country of origin. Once clear-text values are inserted into the HTML code, it is passed to the end user’s browser that renders it into a visual form. Here you should consider that your monolithic web application can be hosted in any country, while HTML Gateway will run in the end user’s country, so regulated data stays within the country without touching servers of your monolithic web application.

note

HTML Gateway unredacts the HTML page structure returned within a response and redacts the content of the json/x-www-form-urlencoded type upon request.

HTML page requirements

HTML Gateway imposes the following requirements for your monolithiс web application:

  1. HTML elements used for output of regulated data must have two data attributes that regulate the unredaction of their values;

  2. regulated data fields should contain plain values without nested elements or rich-text data within them;

  3. the application loads the minimal amount of external resources, especially graphics or elements that are passed along in the SVG format;

  4. the application handles HTTP requests in the application/x-www-form-urlencoded or application/json content type;

  5. the application may perform basic database queries if needed without complex validation or aggregation functions;

  6. the application may perform basic AJAX requests with a JSON or HTML response (without nested AJAX data in HTML responses).

Supported HTML elements

You need to modify the outputted HTML page structure generated by your monolithic web application. The current version of HTML Gateway supports the following HTML elements:

  1. text fields

  2. pre-filled input fields

Below you can find an example of how to mark fields storing regulated data values for their correct processing by HTML Gateway.

  1. text elements (e.g. div and span)

    <body>
        <span>Hello, user!</span>
        ...
        <span data-inc-entity-id="id1" data-inc-field-name="name">ID1_NAME_TOKEN</span>
        ...
        <span data-inc-entity-id="id2" data-inc-field-name="name">ID2_NAME_TOKEN</span>
        ...
        <span data-inc-entity-id="id2" data-inc-field-name="email">ID2_EMAIL_TOKEN</span>
        ...
        <span data-inc-entity-id="id1" data-inc-field-name="email">ID1_EMAIL_TOKEN</span>
        ...
        <div>Other content</div>
    </body>
    
  2. pre-filled input fields:

<body>
    <form action="/add_user" method="POST">
      ...
      <input name="name" data-inc-entity-id="id1" data-inc-field-name="name" type="text" value="ID1_NAME_TOKEN">
      ...
      <input name="email" data-inc-entity-id="id1" data-inc-field-name="email" type="text" value="ID1_EMAIL_TOKEN">
      ...
    </form>
    ...
    <form action="/add_user" method="POST">
      ...
      <input name="name" data-inc-entity-id="id2" data-inc-field-name="name" type="text" value="ID2_NAME_TOKEN">
      ...
      <input name="email" data-inc-entity-id="id2" data-inc-field-name="email" type="text" value="ID2_EMAIL_TOKEN">
      ...
    </form>
</body>

In the HTML structure, the fields can be organized in a flat form or organized as nested fields, as follows:

<body>
    <span>Hello, user!</span>
    <div>
      <span data-inc-entity-id="id1" data-inc-field-name="name">ID1_NAME_TOKEN</span>
      <span data-inc-entity-id="id1" data-inc-field-name="email">ID1_EMAIL_TOKEN</span>
    </div>
    <div>
      <span data-inc-entity-id="id2" data-inc-field-name="name">ID2_NAME_TOKEN</span>
      <span data-inc-entity-id="id2" data-inc-field-name="email">ID2_EMAIL_TOKEN</span>
    </div>
    ...
    <div>Other content</div>
</body>

Alternatively, you can organize regulated data fields in other forms while preserving the following data attributes throughout the HTML page structure: *[data-inc-entity-id]*[data-inc-field-name]. HTML Gateway will use the required selectors to fetch such HTML elements from any location in the HTML structure.

note

The element with the data-inc-entity-id and data-inc-field-name data attributes cannot have nested elements and fields other than the redacted value.

Processing regulated data fields

HTML Gateway performs deserialization of HTML page code and fetches redacted data fields with the help of CSS selectors (*[data-inc-entity-id]*[data-inc-field-name]).

[
  {
    "id": "id1",
    "name": ID1_NAME_TOKEN,
    "email": ID1_EMAIL_TOKEN
  },
  {
    "id": "id2",
    "name": ID2_NAME_TOKEN,
    "email": ID2_EMAIL_TOKEN
  }
]

Having extracted the regulated data fields, HTML Gateway processes this structure and swaps redacted values with their clear-text values pulled from the InCountry platform. Once this is done, HTML Gateway passed the unredacted HTML structure to the end user’s browser for rendering.

Configuration and validation

Configuration of the unredaction rule for HTML Gateway looks as follows:

- path: "/add_user"
  type: HTML
  method: POST
  collections:
    - name: "users"
      entityIdPath: "$[*].id"
      entityIdName: "id"
      entityIdAttr: "data-inc-entity-id"
      entityFieldAttr: "data-inc-field-name"
      entityErrorCorrectionFieldPath: "$[*].email"
      strategies:
        - path: "name"
        - path: "email"
          isErrorCorrectionField: true

Here:

  • type is a flag that indicates that a request is sent to the monolithic web app that returns HTML output.

  • entityIdAttr defines a data attribute for record ID.

  • entityFieldAttr defines a field attribute.

  • entityIdName is a flag that defines the name of the field in which this entity ID should be stored within a JSON object. Commonly it should correspond to entityIdPath, for example, if entityIdPath: "$[*].id" so entityIdName should be "id".

note

Note that if HTML error proxying is enabled, the statusCodeAttr and statusMessageAttr flags are still optional: they can be enabled or disabled for each endpoint.

By default, type is equal to REST: this corresponds to the endpoints when the payload is a JSON string and not HTML.

Error handling

Unlike RESTful APIs, monolithic apps may not return an error code (Error 40X) upon an error occurrence. Anyway, you can identify the occurred error by relying on the following response:

<body>
    <div>Content</div>
    <span data-inc-status-code=true>400</span>
    <span data-inc-status-message=true>Bad Request</span>
</body>

Handling errors requires the addition of flags to the YAML configuration that specify the ID values of containers storing a status code and an error message:

- path: "/add_person"
  type: HTML
  method: POST
  statusCodeAttr: "data-inc-status-code"
  statusMessageAttr: "data-inc-status-message"
  collections:
    - name: "users"
      entityIdPath: "$[*].id"
      entityIdName: "id"
      entityIdAttr: "data-inc-entity-id"
      entityFieldAttr: "data-inc-field-name"
      entityErrorCorrectionFieldPath: "$[*].name"
      strategies:
        - path: "$.name"
        - path: "$.email"
          isErrorCorrectionField: true

The following attributes are used:

  • statusCodeAttr is a data attribute name where a status code is stored.

  • statusMessageAttr is a data attribute name where an error status message is stored.

What’s next

To integrate InCountry Border into your application, please follow these steps:

  1. Collect the requests that should be handled by InCountry Border.
  2. Elaborate the data model and regulated data that should undergo redaction/unredaction.
  3. Contact the InCountry team to construct a configuration YAML file.
  4. Wait until the configuration YAML file is deployed on the InCountry Border side.
  5. Replace the addresses of REST endpoints that will be handled through InCountry Border.
  6. Verify data requests in your application.
← Release notesRelease notes →
  • Overview
    • Pre-requisites
    • Requirements for REST requests
    • Data redaction flow
    • Configuration YAML file
    • Request structure and modifications
  • Email Gateway
    • Email handling workflow
    • Email requirements
    • Configuration of Email Gateway
    • Handling placeholders within emails
  • HTML Gateway
    • HTML structure handling workflow
    • HTML page requirements
    • Supported HTML elements
    • Processing regulated data fields
    • Configuration and validation
    • Error handling
  • What’s next
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
      • Platform
        • Overview
        • Compliance and security
        • How it works
        • For SaaS
        • For internal apps
      • Gateways & Vaults
        • Email
        • HTML
        • Payments
        • Web Forms
    • Solutions
      • Energy
      • Financial services
      • Healthcare
      • Retail
      • Technology
  • Column 2
    • Integrations
      • SaaS
        • Cegid
        • Intertrust
        • Mambu
        • PayPal
        • Salesforce
        • Segment
        • ServiceNow
        • Stripe
        • Twilio
        • Veeva Systems
      • IAAS
        • InCountry on Alibaba Cloud
        • InCountry on Yandex.Cloud
  • Column 3
    • Resources
      • Country compliance
      • Documentation
      • Library
      • Partners
      • Pricing
    • About
      • Blog
      • Careers
      • Contact Us
      • FAQ
      • Leadership