JavaScript in OutSystems: When to Use It and How to Do It Right

JavaScript nodes can only be placed in **Client Actions** — they run in the browser and cannot be used in Server Actions. To add a JavaScript node: 1. Open a Client Action in the Action Flow Editor (right-click a screen → 'Add Client Action', or find one in Logic tab → Client Actions) 2. In the Action Flow Editor, look at the Toolbox on the left 3. Scroll down to find the **JavaScript** element (or search 'JavaScript' in the Toolbox search) 4. Drag the JavaScript element from the Toolbox into the action flow between Start and End Double-click the JavaScript node to open its editor. You see: - A code editor for your JavaScript (top area) - An **Inputs** section (bottom-left) — data you pass INTO the JavaScript node from OutSystems - An **Outputs** section (bottom-right) — data the JavaScript node returns to OutSystems The JavaScript node runs in an isolated scope — it cannot directly access OutSystems screen variables or widgets. All data exchange must go through the Input/Output parameter mechanism.

JavaScript nodes communicate with OutSystems through parameters — not through direct variable access. **Adding Input Parameters (OutSystems → JavaScript):** 1. In the JavaScript node editor, click the **+** icon in the Inputs section 2. Set Name (e.g., `UserName`) and Data Type (Text, Integer, Boolean, etc.) 3. Back in the Action Flow Editor, select the JavaScript node and look at its properties 4. The input parameters appear as fields — set each to an OutSystems expression or variable value **Adding Output Parameters (JavaScript → OutSystems):** 1. Click the **+** icon in the Outputs section 2. Set Name (e.g., `FormattedText`) and Data Type 3. In your JavaScript code, assign the result to the parameter name directly: `$parameters.FormattedText = UserName.toUpperCase();` **Accessing parameters in JavaScript code:** - Inputs: `$parameters.InputParamName` - Outputs: `$parameters.OutputParamName = value;` After the JavaScript node completes, the Output parameter values are available as variables in the action flow — assign them to screen variables or pass them to other nodes.

1// JavaScript node example: Format currency
2// Inputs: Amount (Decimal), CurrencyCode (Text)
3// Outputs: FormattedAmount (Text)
4
5var formatter = new Intl.NumberFormat('en-US', {
6  style: 'currency',
7  currency: $parameters.CurrencyCode || 'USD',
8  minimumFractionDigits: 2
9});
10
11$parameters.FormattedAmount = formatter.format($parameters.Amount);

OutSystems exposes a `$actions` API that lets JavaScript code trigger Client Actions defined in the module. **Calling a Client Action from JavaScript:** `$actions.MyClientActionName(param1, param2);` **With a callback when the action completes:** `$actions.MyClientActionName(param1).then(function(result) { ... });` **OutSystems public APIs available in JavaScript:** - `$public.FeedbackMessage.showFeedbackMessage(message, type, encodeMessage, extraCssClasses)` — show a toast notification - Types: 0=Info, 1=Success, 2=Warning, 3=Error - `$public.Navigation.navigate(url, method)` — navigate to a URL - `$public.Security.getCSRFToken()` — get the CSRF token for custom API calls - `$public.Logger.logError(moduleName, errorMessage, errorDescription)` — write to OutSystems error log - `$public.Validation.validateWidget(widgetId)` — trigger validation on a specific widget **Practical example — triggering a success notification from JS:**

1// In a JavaScript node (no inputs/outputs needed for this example)
2
3// Show a success notification using OutSystems public API
4$public.FeedbackMessage.showFeedbackMessage(
5  "File uploaded successfully!",
6  1,     // 1 = Success (green)
7  true,  // encode message (prevent XSS)
8  ""     // no extra CSS classes
9);
10
11// Call a Client Action to refresh data after an external event
12$actions.RefreshTaskList();
13
14// Navigate programmatically
15$public.Navigation.navigate("/TaskManager/Tasks", "navigate");

For third-party libraries (chart renderers, PDF viewers, QR code generators, etc.), load them as Script resources. **Method A — External URL (CDN):** 1. Interface tab → Scripts → right-click → **Add Script** 2. In the dialog, set Name (e.g., 'QRCodeJS') 3. Set URL to the CDN URL: `https://cdn.jsdelivr.net/npm/qrcode@1.5.3/build/qrcode.min.js` 4. Set Required Script: on the Screen(s) that use it — select the screen in the Interface tab → Properties → Required Scripts → add the script **Method B — Local file:** 1. Interface tab → Scripts → right-click → **Add Script** 2. In the dialog, click 'Import File' → select the .js file from your filesystem 3. Set Required Script on the screen **Using the library in a JavaScript node:** After adding the script, the library is available in the global scope of your JavaScript nodes on that screen. **Example — generating a QR code:**

1// Prerequisites:
2// 1. Script 'QRCodeJS' added pointing to qrcode CDN
3// 2. Script set as Required on this screen
4// 3. A Container widget on screen with Name 'QRCodeContainer'
5//    (add a widget ID expression: "QRCodeContainer")
6
7// JavaScript node:
8// Inputs: QRCodeText (Text), ContainerWidgetId (Text)
9// No outputs needed
10
11var containerElement = document.getElementById($parameters.ContainerWidgetId);
12if (containerElement) {
13  // Clear previous QR code if any
14  containerElement.innerHTML = '';
15
16  // Generate new QR code
17  QRCode.toCanvas(containerElement, $parameters.QRCodeText, {
18    width: 200,
19    margin: 2
20  }, function(error) {
21    if (error) {
22      $public.FeedbackMessage.showFeedbackMessage(
23        "QR code generation failed: " + error.message,
24        3, true, ""
25      );
26    }
27  });
28}

Before adding a JavaScript node, check whether an OutSystems-native solution exists. JavaScript adds maintenance overhead and is harder to debug than visual action flows. **Use JavaScript ONLY when:** - Accessing browser APIs not exposed by OutSystems (geolocation, clipboard, Web Audio, WebSockets, ResizeObserver) - Manipulating the DOM in ways not possible through widget properties - Integrating a third-party library that requires direct DOM access (charting, rich text editors, map renderers) - Performance-critical in-browser calculations (e.g., processing a large local array without server round-trip) - Calling $public APIs (FeedbackMessage, Navigation) for custom trigger patterns **Do NOT use JavaScript when OutSystems can do it:** - String manipulation → use OutSystems expressions: `ToUpper()`, `Replace()`, `Substr()` - Date formatting → `FormatDate(CurrDate(), "yyyy-MM-dd")` - Showing/hiding elements → If widget or Visible property - Form validation → set widget's Valid and ValidationMessage properties in a Client Action - Navigation → Navigate system action in Client Action - Showing notifications → Feedback Message widget or SetFeedbackMessage action - Ajax data fetch → Server Action call from Client Action **Anti-pattern to avoid:** Using JavaScript nodes to call OutSystems REST APIs directly (bypassing OutSystems' security headers, CSRF protection, and error handling). Always make data calls through Server Actions.