Using the JavaScript API in Logic

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 

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

– Updating Field State in Related List Items

You can programmatically control whether fields in related list items are editable or required using the updateLinkedListItemFieldState method. This is useful when field behaviour needs to change dynamically based on user input, business rules, or item values within a related list.

updateLinkedListItemFieldState(
linkedListNameOrId,
predicate,
states
);

When to Use This

Use this method when you need to dynamically control field behaviour inside related list items, for example:

• Make certain fields read-only after submission
• Require fields only when specific conditions are met
• Apply rules to multiple items at once (e.g. all “Active” items)
• Enforce conditional validation across sublist rows

Parameters

• linkedListNameOrId – The name or ID of the related list
• predicate – A function used to identify which item(s) to update
• states – An array of field state objects:
  • fieldName – The field to update
  • isEditable – (Optional) Whether the field is editable
  • isRequired – (Optional) Whether the field is required

Example

const relatedListId = "0aea6212-d8df-46a6-bafd-6e64621bdb8a";

updateLinkedListItemFieldState(
relatedListId,
item => item.ID == 5,
[
{ fieldName: "Title", isEditable: true, isRequired: true },
{ fieldName: "Date", isEditable: true, isRequired: true }
]
);

Notes

• The predicate allows you to target one or multiple items
• Multiple fields can be updated in a single call
• This method replaces the deprecated updateLinkedListItemFieldStateLegacy

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.