Skip to main content

Managing the Package

About​

The InCountry Data Residency for Salesforce package is installed as a common package by following the standard procedure.

Package Installation Guide​

Packages older than version 1.262 of the InCountry Data Residency package require the following steps to grant access. This ensures the package can create metadata and retrieve data via APIs.

Install the package​

You have two ways to obtain the package:

  • Install the package directly from the AppExchange.
  • Request an installation link from the InCountry Team by reaching out to our support team at support@incountry.com.

info

It is strongly advised to install the package for administrators only by selecting the Admins Only option. This approach allows you to later use permission sets to control and grant access to the InCountry Data Residency package for specific Salesforce users as needed.

Warning

Avoid selecting the Install for All Users option, as it grants all Salesforce users access to the InCountry Data Residency package, preventing regulation of individual user access.

Create Authentication Components​

Create an Auth. Provider​

Go to Setup → Quick Find Auth. Providers → Click New.

  1. Set the following parameters:
    • Provider Type: Salesforce
    • Name: Salesforce API requests (You can change this descriptive label).
    • URL Suffix: Salesforce_API_requests (This is automatically generated based on the Name. It should be unique).
    • Consumer Key: - (Use this placeholder since the field cannot be blank. It will be updated later).
    • Consumer Secret: - (Use this placeholder since the field cannot be blank. It will be updated later).
    • Default Scopes: api refresh_token offline_access
  2. Click Save.
  3. Once the Auth. Provider is created, a set of new parameters will appear. Copy the Callback URL; you will need to use it in the Connected App setup.

Create a Connected App​

Salesforce has moved the location for creating Connected Apps. While you may have previously found this in App Manager, please use the following new path:

Go to Setup → Quick Find External Client App → Select Settings → Enable Connected Apps → Click New Connected App.

  1. Set the following parameters:

    • Connected App Name: Salesforce API requests (You can change this descriptive label).
    • API Name: Salesforce_API_requests (This is automatically generated based on the Name. It should be unique).
    • Contact Email: Enter the admin email address.

  2. Enable OAuth Settings.

  3. Set the following OAuth parameters:

    • Callback URL: (Paste the Callback URL value from the Auth. Provider).
    • Selected OAuth Scopes:
      • Manage user data via APIs (api).
      • Perform requests at any time (refresh\_token, offline\_access).

  4. Configure the remaining parameters (such as session timeout) to align with your company's security policies and requirements.

  5. Click Save.

  6. Once Connected App created, click Manage Consumer Details.

  7. Copy Consumer Key and Consumer Secret, you will need to use it in the Auth. Provider setup.

Update the Auth. Provider​

Go to Setup → Quick Find Auth. Providers → Click Edit on Salesforce API requests.

  1. Set the following parameters:
    • Consumer Key: (Paste the Consumer Key value from the Connected App).
    • Consumer Secret: (Paste the Consumer Secret value from the Connected App)
  2. Click Save.

Create an External Credential​

Go to Setup → Quick Find Named Credentials → Click External Credentials tab → Click New.

  1. Set the following parameters:
    • Label: Salesforce API requests
    • Name: Salesforce_API_requests
    • Authentication Protocol: OAuth 2.0
    • Authentication Flow Type: Browser Flow
    • Identity Provider: Auth Provider - Salesforce API requests
  2. Click Save.
  3. Once the External Credential is created, navigate into it and set up a new Principal with these parameters:
    1. Parameter Name: user (You can change this descriptive label)
    2. Sequence Number: 1
    3. Identity Type: Per User Principal
  4. Click Save.

Create a Named Credential​

Go to Setup → Quick Find Named Credentials → Click Named Credentials tab → Click New.

  1. Set the following parameters:
    • Label: InCountry_Named_Credentials_API_Call
    • Name: InCountry_Named_Credentials_API_Call (Do not change this name. The package relies on this exact name to execute its callouts to Salesforce).
    • URL: Enter your Salesforce org domain. (You can find it in Setup → My Domain).
    • Authentication -> External Credential: Salesforce API requests
    • Callout Options:
      • Enable Generate Authorization Header.
      • Enable Allow Formulas in HTTP Body.
    • Managed Package Access → Allowed Namespaces for Callouts: testIncountry1
  2. Click Save.

Configure Permissions and Access​

Create a Permission Set​

Go to Setup → Quick Find Permission Sets → Click New.

  1. Set the following parameters:

    1. Label: Granting InCountry Access to Salesforce APIs
    2. API Name: Granting_InCountry_Access_to_Salesforce_APIs

  2. Click Save.

  3. You will be redirected to the Permission Set details page. From there, click External Credential Principal Access.

  4. Click Edit.

  5. Add Salesforce_API_requests - user to Enabled External Credential Principals.

  6. Click Save.

Assign the Permission Set to the necessary users​

Go to Setup → Quick Find Permission Sets → Open Granting InCountry Access to Salesforce APIs.

  1. Click Manage Assignments.
  2. Click Add Assignment.
  3. Select the users who need access to the InCountry package.
  4. Click Next.
  5. Set the expiration settings to align with your company's security policies.
  6. Click Assign.

Grant Access to the External Credential​

Once you assign the Permission Set, the user must complete the authorization flow. This step grants the necessary permission for the External Credential to make API calls and is required for every user who needs to use the InCountry package.

  1. Go to the user settings.

  2. Open External Credentials.

  3. Click Allow Access for Salesforce API requests.

  4. Log In to the Salesforce org.

  5. Click Confirm.

  6. Once the flow is complete, look for the Configured tag displayed above the External Credential.

Configure Resident Function Access for the Salesforce API​

Customers have the ability to create their own Resident Functions to execute custom calculations or complex logic. These functions are triggered by package events (like save, update, or lead conversion) and can send data back to Salesforce.

To enable this communication, we use a Connected App and the Client Credentials Flow. Therefore, all changes pushed from the Resident Function back to Salesforce will be recorded as being made by the single "Run As" user assigned in the Connected App.

Create the Connected App​

Go to Setup → Quick Find External Client App → Select Settings → Enable Connected Apps → Click New Connected App.

  1. Set the following parameters:

    • Connected App Name: Resident Function Requests (You can change this descriptive label)
    • API Name: Resident_Function_Requests (This is automatically generated based on the Name. It should be unique)
    • Contact Email: Enter the admin email address

  2. Enable OAuth Settings.

  3. Set the following OAuth parameters:

    • Callback URL: (Enter any value here; for example {your org}/services/oauth2/success)
    • Selected OAuth Scopes:
      • Manage user data via APIs (api).

  4. Enable Client Credentials Flow.

  5. Configure the remaining parameters (such as session timeout) to align with your company's security policies and requirements.

  6. Click Save.

  7. Once Connected App created, click Manage Consumer Details.

  8. Copy Consumer Key and Consumer Secret, you will need to use it in the Auth. Provider setup.

  9. Click Manage.

  10. Click Edit Policies.

  11. Scroll to the Client Credentials Flow section, find Run As, and assign a user who has the API Enabled permission.

  12. Click Save.

Create the Resident Function​

Customers can still use this documentation to create their custom Resident Functions. However, if a function needs to send a request back to Salesforce, it must first obtain an access token via a separate API request.

Example: Resident Function to Obtain an Access Token and Send an Update Request to Salesforce​

module.exports.handler = async (storage, country, params, modules) => {
    const result = {
        data: '',
        error: false,
        errorMsg: null
    };
    const getSalesforceAccessToken = async () => {
        // --- IMPORTANT: Replace these placeholder values with your actual credentials ---
        const clientId = 'XXXXX'; // Your Connected App's Consumer Key
        const clientSecret = 'XXXXXX'; // Your Connected App's Consumer Secret
        // ---
        const tokenUrl = `${params.sfdcBaseUrl}/services/oauth2/token`;
        const requestData = {
            grant_type: 'client_credentials',
            client_id: clientId,
            client_secret: clientSecret,
        };
        const requestHeaders = {
            'Content-Type': 'application/x-www-form-urlencoded',
        };
        try {
            const postData = Object.entries(requestData)
                .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
                .join('&');
            const response = await modules.axios.post(
                tokenUrl,
                postData, {
                    headers: requestHeaders,
                },
            );
            return response.data;
        } catch (error) {
            result.error = true;
            result.errorMsg = `Error getting Salesforce access token: ${error.message}`;
            return null;
        }
    }
    const authData = await getSalesforceAccessToken();
    if (authData) {
        const endpoint = `${authData?.instance_url}/services/data/v64.0/sobjects/Lead/${params.id}`;
        const body = {
            Phone: '222-22-22'
        };
        const headers = {
            headers: {
                "Authorization": "Bearer " + authData?.access_token,
                "Content-Type": "application/json",
            }
        };
        await modules.axios.patch(
            endpoint,
            body,
            headers,
        );
        result.data = 'Record successful updated'
    }
    return result;
}

Package Upgrade Guide​

Upgrade the package using the same method as installation. To upgrade the InCountry Data Residency for Salesforce package to beta releases, contact the InCountry team beforehand.

If upgrading from version 1.262 or earlier, you must take the following steps to retain your current InCountry credentials. This is required because we revised the credentials usage and storage flow, removing direct user access.

Warning

If you have not yet provided access to the required Salesforce APIs, please review the instructions in this installation guide: Package Installation Guide.

Before upgrade​

Go to App Launcher → InCountry Setup → Settings page → open Endpoints tab.

For each previously configured country endpoint:

  1. Find the endpoint row and click Edit in the row actions.

  2. The resulting modal will display your InCountry credentials for that country.

    Warning

    IMPORTANT: Copy and securely save these parameters according to your company's security policies. You will need them after the package upgrade.

  3. Close this modal.

Upgrade​

Use the provided link or upgrade the package directly from AppExchange.

We recommend you upgrade the package for admins only, then use a permission set to grant access to other users later.

After Upgrade​

After upgrading the package, you will need to update configuration:

Go to App Launcher → InCountry Setup → Settings page → open Endpoints tab.

For each previously configured country endpoint:

  1. Find the endpoint row and click Edit in the row actions.

  2. The resulting modal will display your InCountry credentials for that country. Here, you will see the difference from the previous credentials: the Client ID and Client Secret will be blank. Each time you update this credential, you will need to enter it from scratch.

  3. Click Update endpoint.

  4. Wait.

  5. Click Acknowledge.

  6. Complete all steps:

    1. Authenticate named credentials.
    2. (Optional) Generate certificate.
    3. (Optional) Upload public key.

  7. Click Next.

  8. Select the self-signed certificate you uploaded to the portal.

  9. Click Confirm.

  10. Click Reset encryption key in the row actions. If the uploaded certificate is incorrect, you will see an error message.

Post-Upgrade Validation​

Select any record that you regulate (in this example account record 001fJ000024rTf8QAE).

Go to App Launcher → InCountry Setup → Find InCountry page.

Backend (Named Credential)​

Use the following steps to verify that the backend Named Credential is configured correctly and can retrieve data:

  1. Select the Request Type: Backend.
  2. Enable the Display record structure toggle.
  3. Expand the Filters section.
  4. Select the desired Country.
  5. Paste the Record ID of a test record into the corresponding field.
  6. Click Find Records.

Verification​

  • Success: If the credential is correct, the record data will display under the Matching Records section. Click on the Record ID in the displayed list to view the full record data and confirm successful retrieval.

  • Failure: If the credential is incorrect or invalid, the component will not display record data, or you will see an error message indicating a connection failure or unauthorized access.

Frontend (JWT)​

Use the following steps to verify that the JWT-based frontend authorization is working and can correctly retrieve protected InCountry record data:

  1. Select the Request Type: Frontend.
  2. Enable the Display record structure toggle.
  3. Expand the Filters section.
  4. Select the desired Country.
  5. Paste the Record ID of a test record into the corresponding field.
  6. Click Find Records.

Verification​

  • Success: If the certificate is correct, the record data will display under the Matching Records section. Click on the Record ID in the displayed list to view the full record data and confirm successful retrieval.
  • Failure: If the certificate is incorrect or invalid, the component will not display record data, or you will see an error message indicating a connection failure or unauthorized access.

Package Uninstallation​

The package uninstallation is comprised of two steps:

Removing User Assignments​

  1. Log in to Salesforce as a system administrator.
  2. From Setup, click User Permissions and then select Permission Sets.
  3. On the list, locate the InCountry User and InCountry Admin sets and click them to open.
  4. Select all users and click Remove Assignment.

Uninstalling the InCountry Data Residency for Salesforce package​

  1. From Setup, click Apps, then Packaging and select Installed Packages.
  2. On the Installed Packages page, locate the InCountry Data Residency for Salesforce package.
  3. Click Uninstall.
  4. On the confirmation page, select Do not save a copy of this package's data after uninstall.
  5. Select the Yes, I want to uninstall this package and permanently delete all associated components box.
  6. Click Uninstall.
Warning

The package may not uninstall immediately if your organization has modifications after installation, such as:

  • new layouts in App Builder
  • new pages in App Builder
  • references in Apex Classes
  • references to LWC/Aura components or modules

If this occurs, a list of modified items appears. Remove these dependencies before uninstalling the package from your Salesforce instance.