Skip to main content

JavaScript API documentation

Table of сontents

About JavaScript API​

note

The JavaScript API is supported in the redaction and restriction data regulation models only.

note

To use JavaScript API from your LWC, you need to enable Lightning Web Security in your org. This is a Salesforce security requirement.

Source diagram​

Source diagram

Configuring the storage​

To access your data on the InCountry platform by using the JavaScript API, you need to create an instance of the InCountryStorage class using the create method.

init(): InCountryStorage

Below you can find an example of how to set up the storage:

/<your\_aura\_component>/<your\_aura\_component>.cmp

<aura:component implements="force:appHostable,flexipage:availableForAllPageTypes,flexipage:availableForRecordHome,force:hasRecordId" access="global" >
  <aura:attribute name="storage" type="Object"/>
  <aura:handler name="init" value="{!this}" action="{!c.init}"/>

    <testIncountry1:inCountry aura:id="InCountry"></testIncountry1:inCountry>
    <c:your_lwc_component storage="{!v.storage}" aura:id="your_lwc_component"></c:your_lwc_component>
</aura:component>

/<your\_aura\_component>/<your\_aura\_component>Controller.js

({
  init : function(component, event, helper) {
        let InCountry = component.find('InCountry');
        let storage = InCountry.create();
        component.set('v.storage', storage);
        // custom code ...
  },

  yourAction : function(component, event, helper) {
    let storage = component.get('v.storage');
        // custom code for the action
    },

    anotherAction : function(cmp, event, helper) {
        let storage = component.get('v.storage');
        // custom code for the action
    }
})

Searching for data records​

You can use the find method to search for specific data records by their fields.

find(
    profile_keys: array,
    fields: array,
    limit: number
): Promise<Object[]>

Below you can find an example of how to search for data records:

storage
  .find(
      ['003P000001TJl6uIAD'],
      ["FirstName","LastName"],
      1
  )
  .then(records => {
      console.log(records);
  })
  .catch(error => {
      console.error(error);
  });

Sample response from the JavaScript API:

[
  {
    "payload": {
      "FirstName": "Mark",
      "LastName": "Taylor"
    },
    "key": "003P000001TJl6uIAD",
    "range_key": null,
    "profile_key": "003P000001TJl6uIAD",
    "service_key5": "Contact",
    "key2": null,
    "key1": null
  }
]

Creating and updating data records​

note

Be careful when updating the existing data records and ensure that you have specified all the fields for the record you want to update. You may accidentally overwrite field values with empty values.

You can use the write method to create a new or replace the existing data records by the recordKey field.

write(
    profile_key: string,
    payload: Object
): Promise<Object>

Below you can find an example of how to create a new or replace the existing data record:

storage
  .write(
      '003P000001TJl6uIAD',
      {
          FirstName: "Mark",
          LastName: "Taylor",
          Salutation: "Mr."
      }
  )
  .then(record => {
      console.log(record)
  })
  .catch(error => {
      console.error(error);
  });

Sample response from the JavaScript API for the create operation:

{
  "country": "sa",
  "key": "003P000001TJl6uIAD",
  "record_key": "003P000001TJl6uIAD",
  "parent_key": null,
  "profile_key": "003P000001TJl6uIAD",
  "range_key": null,
  "range_key1": null,
  "range_key2": null,
  "range_key3": null,
  "range_key4": null,
  "range_key5": null,
  "range_key6": null,
  "range_key7": null,
  "range_key8": null,
  "range_key9": null,
  "range_key10": null,
  "body": "{\"FirstName\":\"Mark\",\"LastName\":\"Taylor\",\"Salutation\":\"Mr.\"}",
  "precommit_body": null,
  "key1": null,
  "key2": null,
  "key3": null,
  "key4": null,
  "key5": null,
  "key6": null,
  "key7": null,
  "key8": null,
  "key9": null,
  "key10": null,
  "key11": null,
  "key12": null,
  "key13": null,
  "key14": null,
  "key15": null,
  "key16": null,
  "key17": null,
  "key18": null,
  "key19": null,
  "key20": null,
  "service_key1": null,
  "service_key2": null,
  "service_key5": "Contact"
}

Sample response from the JavaScript API for the replace operation:

{
  "country": "sa",
  "key": "003P000001TJl6uIAD",
  "record_key": "003P000001TJl6uIAD",
  "profile_key": "003P000001TJl6uIAD",
  "body": "{\"FirstName\":\"Mark\",\"LastName\":\"Taylor\",\"Salutation\":\"Mr.\"}",
  "service_key5": "Contact"
}

Deleting data records​

You can use the delete method to delete data records by the recordKey field from the InCountry platform.

delete(
    profile_key: string
): Promise<boolean>

Below you can find an example of how to delete a data record:

storage
  .delete('0030x00000xDVD6AAO')
  .then(response => {
      console.log(response)
  })
  .catch(error => {
      console.error(error);
  });

Creating and updating multiple data records​

note

Be careful when updating the existing data records and ensure that you have specified all the fields for the records you want to update. You may accidentally overwrite field values with empty values.

You can use the batchWrite method to create or replace multiple data records.

batchWrite(
    records: Object {{id: string, payload: Object}[]}
): Promise<Object[]>

Below you can find an example of how to create or replace multiple data records:

storage
  .batchWrite([
      {
          recordId: '003P000001TJl6uIAD',
          payload: {
              FirstName: "Mark",
              LastName: "Taylor",
              Salutation: "Mr."
          }
      }
  ])
  .then(({records, errors}) => {
      console.log(records, errors);
  })
  .catch(error => {
      console.error(error);
  });

Sample response from the JavaScript API for the create operation:

{
  "data": [
    {
      "country": "sa",
      "key": "003P000001TJl6uIAD",
      "record_key": "003P000001TJl6uIAD",
      "parent_key": null,
      "profile_key": "003P000001TJl6uIAD",
      "range_key": null,
      "range_key1": null,
      "range_key2": null,
      "range_key3": null,
      "range_key4": null,
      "range_key5": null,
      "range_key6": null,
      "range_key7": null,
      "range_key8": null,
      "range_key9": null,
      "range_key10": null,
      "body": "{\"FirstName\":\"Mark\",\"LastName\":\"Taylor\",\"Salutation\":\"Mr.\"}",
      "precommit_body": null,
      "key1": null,
      "key2": null,
      "key3": null,
      "key4": null,
      "key5": null,
      "key6": null,
      "key7": null,
      "key8": null,
      "key9": null,
      "key10": null,
      "key11": null,
      "key12": null,
      "key13": null,
      "key14": null,
      "key15": null,
      "key16": null,
      "key17": null,
      "key18": null,
      "key19": null,
      "key20": null,
      "service_key1": null,
      "service_key2": null,
      "service_key5": "Contact"
    }
  ],
  "errors": null
}

Sample response from the JavaScript API for the replace operation:

{
  "data": [
    {
      "country": "sa",
      "key": "003P000001TJl6uIAD",
      "record_key": "003P000001TJl6uIAD",
      "profile_key": "003P000001TJl6uIAD",
      "body": "{\"FirstName\":\"Mark\",\"LastName\":\"Taylor\",\"Salutation\":\"Mr.\"}",
      "service_key5": "Contact"
    }
  ],
  "errors": null
}

Sample response from the JavaScript API for the create/replace operation with errors:

{
  "data": null,
  "errors": [
    {
      "recordId": "003P000001TJl6uIAD",
      "message": "<MESSAGE_TEXT>",
      "type": "<ERROR_TYPE>"
    }
  ]
}

Deleting multiple data records​

You can use the batchDelete method to delete multiple records of data.

batchDelete(
  recordIds: array
): {Promise<{data: string[], errors: {recordId: !string, message: !string}[]}>[]}

Below you can find an example of how to delete multiple data records:

storage
  .batchDelete(['003P000001TJl6uIAD', '003P000001TJl6uIAA'])
  .then(({ data, errors }) => {
    console.log(data, errors);
  })
  .catch(error => {
    console.error(error);
  });

Attaching files to data records​

You can use the addAttachment method to add or replace attachments for data records.

addAttachment(
    recordId: string,
    attachment: Blob
): Promise<Object>

Below you can find an example of how to attach files to data records:

const canvas = document.createElement('canvas');
canvas.width = 10;
canvas.height = 10;

const context = canvas.getContext('2d');
context.beginPath();
context.rect(0, 0, 10, 10);
context.fillStyle = "red";
context.fill();

canvas.toBlob(function(blob) {

    storage
        .addAttachment('003P000001TJl6uIAD', blob)
        .then(attachment => {
            console.log(attachment); // "26db07ad-81da-457a-9d57-35d9a14ca23d"
        })
        .catch(error => {
            console.error(error);
        });

}, 'image/png');

Sample response from the JavaScript SDK:

{
  "file_id": "76348832-ce4d-421f-9698-c7a08ae40968",
  "filename": "blob",
  "hash": "fd467fe16bf9c674bcaf472605ec10aeabbe190aa9a9feeae64dc1ad19ec7260",
  "mime_type": "application/octet-stream",
  "size": 81,
  "created_at": "2021-03-20T16:49:40.000Z",
  "updated_at": "2021-03-20T16:49:40.000Z",
  "download_link": "https://sa-mt-01.uat.incountry.io/v2/storage/records/sa/90cd5dcb46d73714feb0bb2d0484a6d403458c47e8318e836c0aaf94fc8a6f0a/attachments/76348832-ce4d-421f-9698-c7a08ae40968"
}

Downloading attached files​

You can use the getAttachmentFile method to download files attached to data records.

getAttachmentFile(
    recordId: string,
    fileId: string
): Promise<Blob>

Below you can find an example of how to download files attached to data records:

storage
  .getAttachmentFile('003P000001TJl6uIAD', '26db07ad-81da-457a-9d57-35d9a14ca23d')
  .then(blob => {
      const canvas = document.createElement('canvas');
      canvas.width = 10;
      canvas.height = 10;

      const context = canvas.getContext('2d');

      const image = new Image();
      image.onload = () => context.drawImage(image, 0, 0);
      image.src = URL.createObjectURL(blob);

      document.body.appendChild(canvas);
  })
  .catch(error => {
      console.error(error);
  });

Getting all attachments metadata​

You can use the getAllAttachmentsMeta method to get metadata for all attachments related to a Salesforce record.

getAllAttachmentsMeta(
    recordId: string
): Promise<Object[]>

Below you can find an example of how to get metadata for all attachments related to a Salesforce record:

storage
  .getAllAttachmentsMeta('003P000001TJl6uIAD')
  .then(result => {
     console.log(result);
  })
  .catch(error => {
      console.error(error);
  });

Sample response from the JavaScript SDK:

[
  {
    "file_id": "76348832-ce4d-421f-9698-c7a08ae40968",
    "filename": "blob",
    "hash": "fd467fe16bf9c674bcaf472605ec10aeabbe190aa9a9feeae64dc1ad19ec7260",
    "mime_type": "application/octet-stream",
    "size": 81,
    "created_at": "2021-03-20T16:49:40.000Z",
    "updated_at": "2021-03-20T16:49:40.000Z",
    "download_link": "https://sa-mt-01.uat.incountry.io/v2/storage/records/sa/90cd5dcb46d73714feb0bb2d0484a6d403458c47e8318e836c0aaf94fc8a6f0a/attachments/76348832-ce4d-421f-9698-c7a08ae40968"
  },
  {
    "file_id": "76348832-ce4d-421f-9698-c7a08ae40968",
    "filename": "blob",
    "hash": "fd467fe16bf9c674bcaf472605ec10aeabbe190aa9a9feeae64dc1ad19ec7260",
    "mime_type": "application/octet-stream",
    "size": 81,
    "created_at": "2021-03-20T16:49:40.000Z",
    "updated_at": "2021-03-20T16:49:40.000Z",
    "download_link": "https://sa-mt-01.uat.incountry.io/v2/storage/records/sa/90cd5dcb46d73714feb0bb2d0484a6d403458c47e8318e836c0aaf94fc8a6f0a/attachments/76348832-ce4d-421f-9698-c7a08ae40968"
  },
  {
    "file_id": "76348832-ce4d-421f-9698-c7a08ae40968",
    "filename": "blob",
    "hash": "fd467fe16bf9c674bcaf472605ec10aeabbe190aa9a9feeae64dc1ad19ec7260",
    "mime_type": "application/octet-stream",
    "size": 81,
    "created_at": "2021-03-20T16:49:40.000Z",
    "updated_at": "2021-03-20T16:49:40.000Z",
    "download_link": "https://sa-mt-01.uat.incountry.io/v2/storage/records/sa/90cd5dcb46d73714feb0bb2d0484a6d403458c47e8318e836c0aaf94fc8a6f0a/attachments/76348832-ce4d-421f-9698-c7a08ae40968"
  }
]

Getting attachment metadata​

You can use the getAttachmentMeta method to get attachment metadata related to a Salesforce record by file_id.

getAttachmentMeta(
    recordId: string,
    fileId: string
): Promise<Object>

Below you can find an example of how to get attachment metadata related to a Salesforce record by file_id:

storage
  .getAttachmentMeta('003P000001TJl6uIAD', '26db07ad-81da-457a-9d57-35d9a14ca23d')
  .then(result => {
     console.log(result);
  })
  .catch(error => {
      console.error(error);
  });

Sample response from the JavaScript SDK:

{
  "file_id": "76348832-ce4d-421f-9698-c7a08ae40968",
  "filename": "blob",
  "hash": "fd467fe16bf9c674bcaf472605ec10aeabbe190aa9a9feeae64dc1ad19ec7260",
  "mime_type": "application/octet-stream",
  "size": 81,
  "created_at": "2021-03-20T16:49:40.000Z",
  "updated_at": "2021-03-20T16:49:40.000Z",
  "download_link": "https://sa-mt-01.uat.incountry.io/v2/storage/records/sa/90cd5dcb46d73714feb0bb2d0484a6d403458c47e8318e836c0aaf94fc8a6f0a/attachments/76348832-ce4d-421f-9698-c7a08ae40968"
}

Deleting attached files​

You can use the deleteAttachment method to delete files attached to data records by their file_id.

deleteAttachment(
    recordId: string,
    fileId: string
): Promise<boolean>

Below you can find an example of how to delete a file attached to a data record:

storage
  .deleteAttachment('003P000001TJl6uIAD', "26db07ad-81da-457a-9d57-35d9a14ca23d")
  .then(response => {
      console.log(response); //true
  })
  .catch(error => {
      console.error(error);
  });

Hashing records​

You can use the hash method to hash records with the redaction method matching the configuration of protected fields for a specific Salesforce object.

Records must contain record identifiers or Salesforce object API names.

For a record having an identifier:

hash(
    record: object
): Promise<Object>

For a list of records with identifiers:

hash(
    records: object[]
): Promise<Object[]>

For a record having no identifier:

hash(
    record: object {apiName: string, recordInput: object}
): Promise<Object>

For a list of records without identifiers:

hash(
    records: Object {apiName: string, recordInput: Object}[]
): Promise<Object[]>

Below you can find an example of how to hash records:

single record:

storage
  .hash({
      Id: "0038H00000GLDH2QAP",
      FirstName: "Mark",
      LastName: "Taylor",
      Email: "someemail@test.test"
  })
  .then(response => {
      console.log(response); //reord with hashed data
  })
  .catch(error => {
      console.error(error);
  });
  
 storage
  .hash({apiName: 'Contact', recordInput: {
      FirstName: "Mark",
      LastName: "Taylor",
      Email: "someemail@test.test"
  }})
  .then(response => {
      console.log(response); //reord with hashed data
  })
  .catch(error => {
      console.error(error);
  });
  
  array of records:
  
  storage
  .hash([
      {
        Id: "0038H00000GLDH2QAP",
        FirstName: "Mark",
        LastName: "Taylor",
        Email: "someemail@test.test"
    },
    {
        Id: "0038H00000GLDH2DFA",
        FirstName: "Tim",
        LastName: "Bar",
        Email: "someemail@test.test"
    },
  ])
  .then(response => {
      console.log(response); //array of reords with hashed data
  })
  .catch(error => {
      console.error(error);
  });
  
 storage
  .hash([
      {apiName: 'Contact', recordInput: {
        FirstName: "Mark",
        LastName: "Taylor",
        Email: "someemail@test.test"
      }},
      {apiName: 'Lead', recordInput: {
        FirstName: "Tim",
        LastName: "Bar",
        Email: "someemail@test.test"
      }},
  ])
  .then(response => {
      console.log(response); //array of reords with hashed data
  })
  .catch(error => {
      console.error(error);
  });