Introduction

Forsta HX Platform - API Scripting Guide

Introduction

Forsta HX Platform provides a powerful native API for survey scripting. This guide teaches you the Forsta-specific methods as the standardized approach, with jQuery as an alternative for DOM manipulation.

🇪🇺 Euro SaaS Platform Compatibility

This guide has been optimized for the Forsta HX Euro SaaS Platform. Key considerations:

Data Storage: Use platform-native data collection; avoid localStorage/sessionStorage (GDPR)
Quotas & Routing: Configure through platform settings, not custom JavaScript redirects
Submission: Platform handles data submission automatically; no custom AJAX needed
API Methods: Use Forsta API methods (with quotes: f('Qid')) for data operations

⭐ Recommended: Forsta API Methods

Use Forsta's native methods for all survey logic:

f(Qid) - Access any question (e.g., f('AQ1'), f('BQ2a'))
.domainValues() - Get all possible option codes
.item(code) - Access specific option by code
.toBoolean() - Check if field has value OR if option is selected
.toNumber() - Get numeric value from option
.toString() - Convert field value to string
.set(value) - Set question value
.get() - Get question value

Your First Script - Standard Approach:

// Calculate total from selected checkboxes
var totalSpend = 0; // Initialize total to zero

// Get array of all possible option codes for this question
var codes = f('BQ4c').domainValues();

// Loop through each option code
for (var i = 0; i < codes.length; i++) {
    // Check if this specific option is selected
    if (f('BQ4c').item(codes[i]).toBoolean()) {
        // If selected, get its numeric value and add to total
        totalSpend = totalSpend + f('BQ4c').item(codes[i]).toNumber();
    }
}

// Set the calculated total to the TotalSpend question
f('TotalSpend').set(totalSpend);

What it does: Loops through all checkbox options, checks which are selected, sums their numeric values, and sets the total.

✨ Quick Start Template (Forsta Methods)

// Standard template using Forsta API
$(document).ready(function() {
    
    // 1. Check if field exists before using
    if (f('userid').toBoolean()) { // Returns true if field has a value
        // Convert field value to string and make lowercase
        var userID = f('userid').toString().toLowerCase();
        console.log('User ID: ' + userID);
    }
    
    // 2. Calculate sum from selected checkboxes
    var total = 0; // Initialize sum
    var spendCodes = f('BQ4').domainValues(); // Get all option codes
    
    // Loop through each option code
    for (var i = 0; i < spendCodes.length; i++) {
        // Check if this option is selected
        if (f('BQ4').item(spendCodes[i]).toBoolean()) {
            // Add the numeric value of this option to total
            total += f('BQ4').item(spendCodes[i]).toNumber();
        }
    }
    f('Total').set(total); // Set the calculated total
    
    // 3. Check specific option and show follow-up
    if (f('CQ1').item('3').toBoolean()) { // If option "3" is selected
        f('CQ1a').show(); // Show follow-up question (jQuery for DOM)
    }
    
    // 4. Only set value if not already set
    if (!f('ProcessedID').toBoolean()) { // If ProcessedID is empty
        var result = total * 1.2; // Calculate result
        f('ProcessedID').set(result); // Set the value
    }
    
    // 5. Production-only logic
    if (IsInProductionMode()) { // Check if in production environment
        // Run production-specific code here
    }
    
});

💡 When to Use jQuery

Use jQuery methods only for:

DOM manipulation (show/hide with .show(), .hide())
CSS styling (.addClass(), .css())
Event handling (.on('change'), .on('blur'))
Finding elements (.find(), .parent())

For all data access and value operations, use Forsta methods.

Question Format