API Reference

Forsta HX Platform - API Scripting Guide

API Reference

Two API Approaches

Forsta HX supports both jQuery methods and Forsta-specific methods. Use whichever fits your needs.

Forsta HX Specific Methods

Method Description Example
.domainValues() Get all possible values/codes for a question f('BQ4c').domainValues()
.item(code) Access specific item by its code f('BQ4c').item('1')
.toBoolean() Check if value exists or item is selected f('userid').toBoolean()
f('AQ1').item('2').toBoolean()
.toNumber() Get numeric value of item f('BQ4c').item('1').toNumber()
.toString() Convert question value to string f('userid').toString()
.set(value) Set question value or item value f('TotalSpend').set(100)
f('Grid').item('1').set('Value')
.get() Get question value f('AQ1').get()

💡 Important: .item() for Grid/Loop Questions

When working with grid or loop questions, use .item(code) to access specific rows:

  • Get row value: f('GridQ').item('1').get()
  • Set row value: f('GridQ').item('1').set('Value')
  • Check if row selected: f('GridQ').item('1').toBoolean()
  • Get all rows: f('GridQ').domainValues() returns array of row codes

Environment & Validation Functions

Function Description Example
IsInProductionMode() Check if survey is in production (not test) if(IsInProductionMode()) { }
isTestID() Check if current session is a test ID if(isTestID()) { }
isFieldValueTaken(field, value) Check server if field value already exists isFieldValueTaken('uidPatnum', 'user001')

Setting Values on Loop/Grid Items

Use .item(code).set(value) to set values for specific items in loops or grids:

// Set value for specific row in a loop question
f('ePatId').item('1').set('USER001P001');

// Loop through and set all row values
var rows = f('ePatId').domainValues();
for (var i = 0; i < rows.length; i++) {
    var value = 'Generated-' + rows[i];
    f('ePatId').item(rows[i]).set(value);
}

Real Example: Calculate Total Spend

// Sum selected checkbox values
var totalSpend = 0;
var q4codes = f('BQ4c').domainValues();

for (var i = 0; i < q4codes.length; i++) {
    if (f('BQ4c').item(q4codes[i]).toBoolean()) {
        totalSpend = totalSpend + f('BQ4c').item(q4codes[i]).toNumber();
    }
}

f('TotalSpend').set(totalSpend);

Loop Through Selected Items:

// Get all codes and process selected ones
var codes = f('BQ2').domainValues();

codes.forEach(function(code) {
    if (f('BQ2').item(code).toBoolean()) {
        console.log('Selected: ' + code);
        var value = f('BQ2').item(code).toNumber();
        console.log('Value: ' + value);
    }
});

Check Specific Item Selection:

// Check if option "3" is selected
if (f('AQ1').item('3').toBoolean()) {
    f('AQ1a').show();
} else {
    f('AQ1a').hide();
}

jQuery Methods

Function Description Example
f(Qid) Get question element f(AQ1)
.val() Get/set value (jQuery) f(BQ2).val("1")
.show() Show question f(CQ3).show()
.hide() Hide question f(DQ4).hide()
.on('change') Listen for changes f(EQ5).on('change', fn)
.find() Find child elements f(FQ6).find('input')
.addClass() Add CSS class f(AQ1).addClass('error')
.removeClass() Remove CSS class f(BQ2).removeClass('error')

When to Use Each Approach:

// Use Forsta methods for:
// - Looping through all possible values
// - Checking individual item selection
// - Getting numeric values from items
var codes = f('BQ4c').domainValues();
var total = 0;
codes.forEach(function(code) {
    if (f('BQ4c').item(code).toBoolean()) {
        total += f('BQ4c').item(code).toNumber();
    }
});

// Use jQuery methods for:
// - Simple get/set operations
// - DOM manipulation
// - Show/hide logic
f(AQ1).on('change', function() {
    var val = $(this).val();
    if (val == '1') {
        f(BQ1).show();
    } else {
        f(BQ1).hide().val('');
    }
});