JavaScript API documentation

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

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);
  });