Try it
How can we help?

Search for answers or browse articles about Sintel Apps

< All Topics
You are here:

Using the JavaScript API in Logic

Posted
Updated
ByAmy Dermody
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%

 

 

Using the JavaScript API in Logic  

 

The Custom JavaScript option inside the Logic tab allows you to go beyond standard visibility and validation rules. 

It gives you access to the Sintel Apps Public JS API, enabling: 

  • Advanced calculations 
  • Dynamic field manipulation 
  • SharePoint data retrieval 
  • External API calls 
  • Workflow automation 
  • Complex validation scenarios 

This article explains how to use the JavaScript API safely and effectively within Logic. 

 

 

Where Custom JavaScript Runs 

 

Custom JavaScript can be used in two places: 

  1. Custom JS Step – Executes when a rule runs 
  2. Custom JS Condition – Returns true or false to determine whether the rule applies 

 

To add JavaScript: 

  1. Open your form in the Logic tab. 
  2. Add a rule. 
  3. Drag Custom JS into either: Conditions (for evaluation logic), or  Steps when conditions are met 

 

Always choose the correct Execution Behaviour: 

  • Use Continuous for dynamic behaviour. 
  • Use Run Once for setting default values or one-time actions. 

 

 

 

Understanding the API Structure 

 

The Public JS API provides methods for: 

  • Getting field values 
  • Setting field values 
  • Working with lookups and users 
  • Related list manipulation 
  • Saving forms 
  • Executing workflow actions 
  • SharePoint integration 
  • External HTTP calls 
  • Date handling 
  • Validation messaging 
  • Calculations 

 

API Version: 1.0.3.250 

Getting and Setting Field Values

 

– Get a Field Value 

const requestType = getTextFieldValue(“RequestType”); 

If the field is in a sublist: 

const value = getValue(“FieldInternalName”, “ListId”); 

Available Get Methods 

Method  Use For 
getTextFieldValue()  Single line / multi-line text 
getNumberFieldValue()  Number fields 
getBooleanFieldValue()  Yes/No fields 
getValue()  Generic fallback 

 

 

– Set a Field Value 

setTextFieldValue("Comments", "Auto-filled by logic");

 

setNumberFieldValue("TotalCost", 1250);

 

 

setBooleanFieldValue("Approved", true);

 

 

Example: Simple Auto Calculation 

const amount = getNumberFieldValue("Amount") || 0;
const vat = amount * 0.2;

setNumberFieldValue("VAT", vat);
setNumberFieldValue("Total", amount + vat);

 

Best practice: 

  • Use || 0 to prevent undefined errors. 
  • Prefer number-specific methods where possible. 

 

 

Using Built-in Calculation Helpers 

Instead of manual maths: 

const total = sum(
  getNumberFieldValue(“Line1”),
  getNumberFieldValue(“Line2”),
  getNumberFieldValue(“Line3”)
);

setNumberFieldValue(“Total”, total); 

Other helpers: 

average(10, 20, 30);
min(5, 8, 2);
max(100, 250, 175); 

 

Working with Lookup Fields

Lookup fields must always be set using arrays. 

– Set Single Lookup Value 

setLookupFieldValue("Department", [
  { id: 5, value: "Finance" }
]);

 

– Set by ID Only 

setLookupFieldValue("Department", [5]);

 

 

 

– Dynamically Update Lookup Options 

updateLookupOptions("Project", [
  { ID: 1, value: "Project A" },
  { ID: 2, value: "Project B" }
]);

 

This overrides existing dropdown options. 

 

 

Cascading Dropdowns 

Instead of writing manual filtering: 

cascadingDropdowns(
  "Country",
  "City",
  "CountryLookup"
);

This automatically filters the child lookup when the parent changes 

 

 

–  Working with User Fields 

Set user fields using email or object format: 

setUserFieldValue("Approver", [
  { email: "approver@company.co.uk", displayName: "Jane Smith" }
]);

 

Or: 

setUserFieldValue("Approver", ["approver@company.co.uk"]);

 

 

– Date Handling (Using Luxon) 

 moment() is deprecated. 

Use Luxon instead: 

const now = DateTime.now();
const nextWeek = now.plus({ days: 7 });

setTextFieldValue("DueDate", nextWeek.toISODate());

 

 

– Working with Related Lists (Sub Lists) 

Get Related List Data 

const items = getRelatedListFieldValue("LineItems");

 

Insert Items 

insertSublistItems("LineItems", [
  { Title: "Item 1", Amount: 100 },
  { Title: "Item 2", Amount: 250 }
]);

 

 

 

Saving the Form 

await saveForm();

 

With options: 

await saveForm({
  exit: false,
  ignoreValidation: true
});

 

Use carefully — bypassing validation should be controlled. 

 

 

Executing Workflow Actions 

await executeAction("ApproveActionId");

 

With validation bypass: 

await executeAction("ApproveActionId", {
  ignoreValidation: true
});

 

 

Retrieving SharePoint List Data 

– Using Built-In getListItems 

const results = await getListItems({
  listTitle: "Projects",
  search: {
    value: "Active",
    fieldInternalName: "Status",
    operator: "equals"
  },
  itemsLimit: 10
});

console.log(results);

 

 

 

– Using PnP API 

PnPApi.sp.web.lists
  .getByTitle("Projects")
  .items.select("Title", "ID")
  .top(5)()
  .then(data => console.log(data));

 

 

 

 

– Using SharePoint JSOM 

SPApi.context.load(SPApi.hostWeb, "Title");
SPApi.context.executeQueryAsync(
  () => console.log("Loaded"),
  (sender, args) => console.error(args.get_message())
);

 

 

 

 Calling External APIs 

Axios is available via api. 

api.get("https://api.example.com/data")
  .then(response => {
    setTextFieldValue("ExternalData", response.data.value);
  })
  .catch(error => {
    showMessage("Failed to retrieve data", "error");
  });

 

 

 

 

 Displaying Messages & Validation 

– Show Form Message 

showMessage("Data saved successfully", "success");

 

Severity options: 

  • “info” 
  • “warning” 
  • “error” 
  • “success” 

 

 

– Set Field Error (Continuous Only) 

setErrorMessage("EndDate", 
  "End Date must be on or after Start Date."
);

 

 Only works in rules set to Continuous Execution. 

 

 

Navigation & UI Control 

– Open Tabs 

openTab("DetailsSection", 1);

 

 

openNextTab("DetailsSection");

 

 

openPreviousTab("DetailsSection");

 

 

 

Add Custom Top Bar Button 

addTopBarButton(
  "Open Policy",
  "Document",
  "https://company.co.uk/policy"
);

 

Or with custom logic: 

addTopBarButton(
  "Validate",
  "CheckMark",
  () => {
    showMessage("Validation triggered", "info");
  }
);

 

 

 

Best Practices 

✔ Prefer specific getters (getNumberFieldValue) over generic getValue
✔ Always handle undefined values
✔ Use Continuous only when needed
✔ Document complex scripts
✔ Avoid infinite save loops
✔ Test thoroughly in all form modes (New/Edit/View)
✔ Avoid heavy external API calls in Continuous rules 

 

 

When Should You Use Custom JS? 

Use Custom JS when: 

  • Standard Logic steps cannot achieve the requirement 
  • You need complex calculations 
  • You need cross-list validation 
  • You need to call external systems 
  • You need dynamic dropdown manipulation 
  • You need workflow automation beyond built-in options 

 

Avoid it when: 

  • A simple visibility rule would work 
  • A built-in step already exists 
  • Perform calculations 
  • Integrate external systems 
  • Build advanced validation scenarios 

Used correctly, it transforms forms from static data entry screens into intelligent, responsive business applications. 

 

Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
Please Share Your Feedback
How Can We Improve This Article?
Table of Contents