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
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
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. |
Field names should be specified in the following format ObjectApiName.FieldName.
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.
✅ 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
- 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.
- 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.
✅ 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
- 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.
- 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.
✅ 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.
✅ 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 | Yes | Salesforce Id (18 characters) |
Response
This method returns a Promise object.
✅ 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'"
}
]
}
}
}