Page Comparison

Info
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 built-in 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.

...

Table of Contents

minLevel	3
maxLevel	6
outline	false
type	list
printable	false

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	✅	✅
Salesforce Formulas	✅	✅
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.

...

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

Methode name

Description

Example

on (fieldpath,({ recordId, from, to, record, parent }) )

Listen on changes on a specific field. You can retrieve the record where the change happened as well as the old (from) and the new value (to) and if this is a parent record (package header).

Editing Children Records

updateFieldFromRecord(record, fieldpath, value)

Set a specific value directly in the record object based on the field path.

Note
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.

Discount limiting example

getFieldFromRecord(record, fieldpath)

Get a specific value from the record object based on the field path.

Editing Children Records

async query({objectName,fields,limit,offset,conditions = [],orderByField,orderByDirection}

Run a SOQL query by parameters to query data from records that are not included in the Campaign Builder.

To prevent security vulnerabilities, the query method is invoked with an object instead of a plain SOQL string.

Querying Accounts

hasChildRecord(record)

Ask if the record has child records as package components. If yes, you can react and perform other actions.

Editing Children Records

getChildRecords(record)

Use this method to iterate through children records of a parent item.

Editing Children Records

onDocumentReady (callback)

Allows to create a function that will be called when every record is loaded in the campaign builder. After that it 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

updateRecords(records)

Allows to apply changes to a list of previously queried Campaign Builder items.

Note
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.

Editing Values

setFieldError(recordId, fieldpath, message)

Set a custom message for an specific field based on the fieldpath and the recordId.

-

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)

-

...

Making fields available for custom logic

If there are certain fields which you need to reference in your custom logic but don’t want to add them to the shown fields then you can add them to a field in the Item Configuration Settings called “Logic Fields“. The format in which you would use this field is the following:

Code Block
["advendio__billing_category__c"]

...

Examples

Discount limiting example

Consider this case where the maximum discount for a campaign item is 10%. The following script will:

...

Code Block

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 Accounts

Imagine a case where you would like to request the id of an Account based on a name search.

Code Block

language	js

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 child frequency by 2.

...

Code Block

language	js

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.

Code Block

language	js

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

Editing Values

The following example will showcase the onDocumentReady method, which will update certain fields in the Campaign Builders items.

Code Block

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

  };

...

Use your custom script

Once you have created your static resource js, you can upload it to your org via Setup > Static Resources > New.

...

Versions Compared

Old Version 12

New Version Current

Key

Challenge

Solution

When do I need to extend the campaign builder with a custom script?

Creating your custom javascript file

Static resource skeleton

Available methods

Making fields available for custom logic

Examples

Discount limiting example

Querying Accounts

Editing Children Records

Editing Parent Records

Editing Values

Use your custom script