UI API Documentation

InCountry UI API provides a library of ready-to-use UI components that work in a fully compliant way with regulated data.

Description

The InCountry Data Residency for Salesforce package provides the record API LWC interface similar to the one available in Salesforce. This library of methods allows you to create, update, and delete records, as well as query single or multiple records. These methods are based on the existing functions used in the package for reading, querying, writing, and deleting regulated records in Salesforce and on the InCountry platform.

Limitations

Warning

For correct operation of the library, LWS must be enabled in the Salesforce org.

A possible error message to indicate that LWS is turned off: Attempting to reference cross-namespace module testIncountry1-recordApi in c-contactDisplayComponent.

Methods

The library provides the following methods:

• getRecord
• getRecords
• createRecord
• updateRecord
• deleteRecord

getRecord

This method allows you to query a specific single record and get its regulated data stored on the InCountry platform. This method is an equivalent to the native getRecord method.

Request parameters

Name	Type	Required	Description
recordId	String	✅	Salesforce Id (18 characters)
fields	String[]	❌ If optional fields are specified.	A field or an array of fields to return. If the context user doesn’t have access to a field, an error is returned. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the optionalFields parameter.
optionalFields	String[]	❌ If mandatory fields are specified.	An optional field name or an array of optional field names. If a field is accessible to the context user, it’s included in the response. If a field isn’t accessible to the context user, it isn’t included in the response, but it doesn’t cause an error.

note

Field names should be specified in the following format ObjectApiName.FieldName.

note

Polymorphic fields aren't supported. Including a polymorphic field in fields can result in an invalid field error.

Response

This method returns a Promise object.

info

✅ If the data is successfully retrieved, then its structure will be as described in the Salesforce documentation.

❌ If the data retrieval has failed, then the error object is returned.

Example

import { LightningElement, api, } from "lwc";

//Import method from the package library
import {
    getRecord,
} from "testIncountry1/recordApi";

export default class ContactDetails extends LightningElement {

    @api recordId;

    //retrieve data from by record id and fields
    getContact() {
        getRecord({
            recordId: this.recordId,
            fields: [
                'Account.Id',
                'Account.Owner.Id',
                'Account.Name',
                'Account.Industry',
                'Account.Site',
                'Account.Parent.Parent.Name',
                'Name',
                'FirstName',
                'Owner.Name',
                'ReportsTo.ReportsTo.Name',
            ]
        }).then(result => {
            // handle success object
        }).catch(error => {
            // handle error object
        })
    }

}

Limitations

1. If the record has no required fields it will throw an exception, but if this field is in the parent record it won't throw an exception.
2. Currently, only Salesforce ids with 18 characters are supported.

getRecords

This method allows you to query multiple records and get their regulated data stored on the InCountry platform. This method is an equivalent to the native getRecords method.

Request parameters

Name	Type	Required	Description
records	Object[]	✅	An array of record data, which can be across multiple objects or record types.
records[].recordIds	String[]	✅	Records identifiers to fetch from supported objects.
records[].fields	String[]	❌ If optional fields are specified.	A field or an array of fields to return. If the context user doesn’t have access to a field, an error is returned. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the optionalFields parameter.
records[].optionalFields	String[]	❌ If mandatory fields are specified.	An optional field name or an array of optional field names. If a field is accessible to the context user, it’s included in the response. If a field isn’t accessible to the context user, it isn’t included in the response, but it doesn’t cause an error.

Response

This method returns a Promise object.

info

✅ If the data is successfully retrieved, then its structure will be as described in the Salesforce documentation.

❌ If the data retrieval has failed, then the error object is returned.

Example

import { LightningElement, api, } from "lwc";

//Import method from the package library
import {
    getRecords,
} from "testIncountry1/recordApi";

export default class ContactTable extends LightningElement {

    getContacts() {
        getRecords({
            records: [{
                recordIds: ['0013h00002CLzeqAAD'],
                fields: [
                    'Name',
                    'FirstName',
                    'Owner.Name',
                ]
            }, {
                recordIds: ['0033h00001GsCDTAA3', '0033h00001FbPBsAAN'],
                fields: [
                    'Account.Id',
                    'Account.Owner.Id',
                    'Account.Name',
                    'Account.Industry',
                    'Account.Site',
                    'Account.Parent.Parent.Name',
                    'Name',
                    'FirstName',
                    'Owner.Name',
                    'ReportsTo.ReportsTo.Name',
                ]
            }]
        }).then(result => {
            // handle success object
        }).catch(error => {
            // handle error object
        })
    }

}

Limitations

1. If the record has no required fields it will throw an exception, but if this field is in the parent record it won't throw an exception.
2. The array must include Salesforce IDs pertaining to the same object only.

createRecord

This method allows you to create single records and save their regulated data to the InCountry platform. This method is an equivalent to the native createRecord method.

Request parameters

Name	Type	Required	Description
apiName	String	yes	Object API name.
fields	Object	yes	Map of field names to field values.
allowSaveOnDuplicate	Boolean	no	Enables the record saving if a record duplication is found.

Response

This method returns a Promise object.

info

✅ If the data is successfully retrieved, then its structure will be as described in the Salesforce documentation.

❌ If the data creation has failed, then the error object is returned.

Example

import { LightningElement, api, } from "lwc";

//Import method from the package library
import {
    createRecord,
} from "testIncountry1/recordApi";

export default class ContactForm extends LightningElement {

    createContact() {
        createRecord({
            apiName: 'Contact',
            fields: {
                LastName: 'Example',
                FirstName: 'XXX',
                AccountId: '001XXXXXXXXXXXXXXX'
            },
            allowSaveOnDuplicate: true,
        }).then(result => {
            // handle success object
        }).catch(error => {
            // handle error object
        })
    }

}

Restrictions

After the saving, the returned record does not include all the fields from the page layout (as Salesforce provides). Only the provided values will be supplied in the resulting structure.

Error Handling

Below you can find the example of error handling:

createRecord() {
    // It's UI API create method
    createRecord({
        apiName: this.sobjectName,
        fields: {
            LastName: 'Karl',
            FirstName: 'Bart',
            Email: 'karl.bart@test.com'
        },
        allowSaveOnDuplicate: true,
    }).then(result => {
        // handle success result
    })
    .catch(error => {
        // An error is a Promise. So, we need to parse it as object.
        // An example below shows how to handle CUSTOM_VALIDATION_EXCEPTION message.
        this.dispatchEvent(
            new ShowToastEvent({
                title: error.output.fieldErrors.Email[0].errorCode,
                message: error.output.fieldErrors.Email[0].message,
                variant: "error",
            }),
        );
    })
}

Please see the example of the error structure.

updateRecord

This method allows you to update a specific record and save its updated regulated data to the InCountry platform. This method is an equivalent to the native updateRecord method.

Request parameters

Name	Type	Required	Description
apiName	String	❌	Object API name
fields	Object	✅ Fields must include the record id.	Map of field names to field values.
allowSaveOnDuplicate	Boolean	❌	Enables the record saving if a record duplication is found.

Response

This method returns a Promise object.

info

✅ If the data is successfully retrieved, then its structure will be as described in the Salesforce documentation.

❌ If the data update has failed, then the error object is returned.

Example

import { LightningElement, api, } from "lwc";

//Import method from the package library
import {
    updateRecord,
} from "testIncountry1/recordApi";

export default class ContactForm extends LightningElement {

    @recordId;

    updateContact() {
        updateRecord({
            apiName: 'Contact',
            fields: {
                Id: this.recordId,
                FirstName: 'Updated',
            },
            allowSaveOnDuplicate: true,
        }).then(result => {
            // handle success object
        }).catch(error => {
            // handle error object
        })
    }

}

Restrictions

After the saving, the returned record does not include all the fields from the page layout (as Salesforce provides). Only the provided values will be supplied in the resulting structure.

Error Handling

Below you can find the example of error handling:

updateRecord() {
    // It's UI API update method
    updateRecord({
        apiName: this.sobjectName,
        fields: {
            Id: this.recordId,
            FirstName: 'Karl',
            LastName: 'Bart',
            Email: 'karl.bart@test.com'
        },
        allowSaveOnDuplicate: true,
    }).then(result => {
        // handle success result
    })
    .catch(error => {
        // An error is a Promise. So, we need to parse it as object.
        // An example below shows how to handle CUSTOM_VALIDATION_EXCEPTION message.
        this.dispatchEvent(
            new ShowToastEvent({
                title: error.output.fieldErrors.Email[0].errorCode,
                message: error.output.fieldErrors.Email[0].message,
                variant: "error",
            }),
        );
    })
}

Please see the example of the error structure.

deleteRecord

This method allows you to delete a specific record from the InCountry platform. This method is an equivalent to the native deleteRecord method.

Request params

Name	Type	Required	Description
recordId	String	✅	Salesforce Id (18 characters)

Response

This method returns a Promise object.

info

✅ If the record is successfully deleted, it returns nothing.

❌if the record removal has failed, then an error message is returned.

Example

import { LightningElement, api, } from "lwc";

//Import method from the package library
import {
    deleteRecord,
} from "testIncountry1/recordApi";

export default class DeleteAction extends LightningElement {

    @recordId;

    deleteContact() {
        deleteRecord(this.recordId)
        .then(result => {
            // handle success object
        }).catch(error => {
            // handle error object
        })
    }

}

Structure of Errors

The system may return errors when you perform invalid requests or the application is temporarily unavailable. Below you can find the structure of returned errors:

{
    "message": "An error occurred while trying to update the record. Please try again.",
    "statusCode": 400,
    "enhancedErrorType": "RecordError",
    "output": {
        "errors": [
            {
                "constituentField": null,
                "duplicateRecordError": null,
                "errorCode": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
                "field": null,
                "fieldLabel": null,
                "message": "Illegal LastName field value. Please, use another one."
            }
        ],
        "fieldErrors": {
            "Email": [
                {
                    "constituentField": null,
                    "duplicateRecordError": null,
                    "errorCode": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
                    "field": "Email",
                    "fieldLabel": "Email",
                    "message": "Invalid Email field value."
                },
                {
                    "constituentField": null,
                    "duplicateRecordError": null,
                    "errorCode": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
                    "field": "Email",
                    "fieldLabel": "Email",
                    "message": "Invalid Email - 'inc.test@test.com'"
                }
            ]
        }
    }
}