We are looking forward to your feedback as well as enhancement ideas. Please contact our Customer Success Management team or support@advendio.com to share feedback with us.
Challenge
For performing custom calculations in our Campaign Builder in-built features like Salesforce formulas and the campaign builder layout settings may not suffice in certain use cases.
Solution
You can add additional behaviour and calculations by creating a JavaScript static resource that can be loaded into the campaign builder. A custom script allows you to react to field changes and to interact with the data in the campaign builder.
This feature is currently only triggered on user events and can not set fields by default.
Please take note that you will need technical knowledge to implement this in your ADvendio instance.
When do I need to extend the campaign builder with a custom script?
Problem | Pre-Installed Campaign Builder | Custom JavaScript |
|---|---|---|
Fast and configurable campaign item editing | ✅ | ✅ |
Conditional tab and field visibilities | ✅ | ✅ |
✅ | ✅ | |
Performing SOQL queries to fetch data | ❌ | ✅ |
Complex calculations in JavaScript | ❌ | ✅ |
Creating your custom javascript file
Please follow the instructions below to build your custom javascript file.
Static resource skeleton
Any custom JavaScript for the campaign builder starts out as the following skeleton.
window.advendioCampaignBuilder = campaignBuilder => {
// TODO
};
The skeleton is a method named advendioCampaignBuilder. The method will be called by the campaign builder and pass a CampaignBuilder object to your method.
The campaignBuilder is the API to interact with the campaign builder. You can listen on field changes, get field values, and set field values.
Available methods
updateFieldFromRecord(record, fieldpath, value)
Set a specific value directly in the record object based on the field path.
getFieldFromRecord(record, fieldpath)
Get a specific value from the record object based on the field path.
async query({objectName,fields,limit,offset,conditions = [],orderByField,orderByDirection}
Run a SOQL query by parameters.
Discount limiting example
Consider this case where the maximum discount for a campaign item is 10%. The following script will:
Listen to any changes on a specific
discount__cfieldInside the listener, if the new discount value is over 10%
Set the
discount__cfield for the item to10or the valuefromif it is less
window.advendioCampaignBuilder = campaignBuilder => {
// 1. Listen on changes on discount__c field
campaignBuilder.on("advendio__rate_discount_4__c", async ({ recordId, from, to, record }) => {
if (Number(to) > 10) {
campaignBuilder.updateFieldFromRecord(record, "advendio__rate_discount_4__c", Math.min(to, 10));
}
});
};
Querying additional data
To query data from records that are not included in the campaign builder, you can use the campaignBuilder.query method.
To prevent security vulnerabilities, the query method is invoked with an object instead of a plain SOQL string.
window.advendioCampaignBuilder = async (campaignBuilder) => {
const result = await campaignBuilder.query({
objectName: 'Account',
fields: 'Name',
limit: 5,
offset: 0,
conditions: [{
fieldName: "Name",
condition: "!=",
value: "Acme",
scapeQuotes: true
}]
});
console.log(result); // array of accounts
};
Editing Children Records
In the following example, every time you modify the advendio__quantity__c field in a record with subItems, it will multiply the value of every children frequency by 2.
If the record doesn’t have children records, it will not modify the frequency value.
window.advendioCampaignBuilder = campaignBuilder => {
campaignBuilder.on("advendio__quantity__c", ({ recordId, from, to, record }) =>
{
if (campaignBuilder.hasChildRecord(record)) {
let childrenRecord = campaignBuilder.getChildRecords(record);
for (let child of childrenRecord) {
campaignBuilder.updateFieldFromRecord(child,
"advendio__frequency__c",
campaignBuilder.getFieldFromRecord(child, "advendio__frequency__c") * 2);
}
console.log('All children modified');
}
});
};
Editing Parent Records
In the following example, every time you modify the advendio__linedescription__c field in a child record, it will change the value on the parent field and will add a (modified from children) text.
window.advendioCampaignBuilder = campaignBuilder => {
campaignBuilder.on("advendio__linedescription__c", ({ recordId, from, to, record, parent }) => {
if (parent != null) {
campaignBuilder.updateFieldFromRecord(parent, "advendio__linedescription__c", to + " (modified from children)");
}
});
};
On Document Ready
The following example will showcase the onDocumentReady method, that allows the user to execute code right after all the records are loaded into the Campaign Builder, allowing to modify data, execute queries, copy values, etc.
Editing Values
window.advendioCampaignBuilder = campaignBuilder => {
campaignBuilder.onDocumentReady(({ records }) => {
console.log('On Document ready');
campaignBuilder.updateFieldFromRecord(records[0], "advendio__from_date__c", "2022-01-04");
campaignBuilder.updateFieldFromRecord(records[0], "advendio__until_date__c", "2022-01-23");
campaignBuilder.updateFieldFromRecord(records[0], "advendio__quantity__c", 10);
campaignBuilder.updateRecords(records);
console.log(records);
});
};
Important: You should always call the method updateRecords when modifying records inside the onDocumentReady method otherwise it will not be reflected on the rendered page.
Available methods
onDocumentReady(callback)
Allows to create a function that will be called when every record is loaded in the campaign builder.
updateRecords(records)
Update records values
updateFieldFromRecord(record, fieldpath, value)
If you update a field that is involved in the amount calculation process, the field value can be changed after this operation because amount calculation process has highest priority over custom javascript methods.
Set a specific value directly in the record object based on the field path.
getFieldFromRecord(record, fieldpath)
Set a specific value directly in the record object based on the field path.
setFieldError(recordId, fieldpath, message)
Set a custom message for an specific field based on the fieldpath and the recordId.
async query({objectName,fields,limit,offset,conditions = [],orderByField,orderByDirection}
Run a SOQL query by parameters.
hasChildRecord(record)
Return true if the record has sub items otherwise return false
getChildRecords(record)
Return all the child record (sub items) of a record, if the record doesn’t have child records it will return an empty array
isRelatedField(record, fieldpath)
Return true if the field has isRelated true
getRecordsFromRelatedFields(record, fieldpath)
Return all records of a related field inside a children record, if the fields inside are not a related field it will return an empty array
getRecordsFromRelatedField(record, fieldpath)
Return all the records of a related field if it’s not a related field it will return an empty array
getAllRelatedFieldsFromRecord(record)
Return an array with all the fields that has isRelated true in the record
setFieldAsRequired(recordId, field, value)
Will set the indicated field as required or not depending on the value (true or false)
setFieldAsReadOnly(recordId, field, value)
Will set the indicated field as read only or not depending on the value (true or false)
setFieldAsHidden(recordId, field, value)
Will set the indicated field as hidden or not depending on the value (true or false)
Important: In order to update the current selection, the method updateFieldFromRecord must be used in the listener instead of setField because it will avoid any wrong assignment with our Amount Calculation logic.
Use your custom script
Once you have created your static resource js, you can upload it to your org via Setup > Static Resources > New.
After the successful upload please go to the uploaded file by hitting the “View file” link for your static resource.
Copy the latter part of the URL starting from “/resource”, e.g.
/resource/1610556603123/ADvendio__CampaignBuilderCJS?
and then an administrator can enable it in the ADvendio Administration Settings.
Open the App Launcher.
Search for Administration Settings and open them.
Switch to the Administration Settings tab.
Next to Custom JavaScript (Campaign Builder), enter the link you copied from the URL in the step at the top of this section.
Click the Save button at the top of the page.
Now, the next time you start the campaign builder, your custom logic will be loaded.