Client Actions vs Server Actions: When to Use Which in OutSystems

Before writing any code, internalize this mental model: Client Actions = JavaScript running in the user's browser. - Can see: screen widgets and their properties, Local Variables on the current screen, Client Variables (localStorage), navigate between screens, call JavaScript nodes, call other Client Actions. - Cannot see: database tables, Site Properties, Session Variables (O11 Traditional only), external APIs (CORS blocks direct browser calls). Server Actions = .NET code running on OutSystems Platform Server. - Can see: all entities (database), Site Properties, server-side sessions, external REST/SOAP APIs, email sending, file I/O. - Cannot see: screen widgets, Client Variables, browser state. This boundary is enforced by OutSystems — TrueChange will show a red error if you try to access a database entity from a Client Action.

Client Actions are the right home for logic that reads or writes to screen widgets, validates user input before sending to the server, toggles visibility, or navigates. To create: right-click the screen name in the Widget Tree → 'Add Client Action'. Name it 'ValidateAndSubmitForm'. Or: right-click a Button widget → 'Add OnClick Client Action' — Service Studio creates it automatically. Example Client Action flow for a form submit: Start → If: Length(Trim(FullName)) < 2 → [True] Assign FullNameInput.Valid=False → End → [False continues] → If: Form.Valid → [True] calls SaveEmployee Server Action → [False] End Note: 'SaveEmployee' is a Server Action call node — you drag it from Logic tab → Server Actions into the Client Action flow.

1/* Client Action: ValidateAndSubmitForm */
2Start
3  --> If: Length(Trim(FullName)) < 2
4       [True] --> Assign: FullNameInput.Valid = False
5                          FullNameInput.ValidationMessage = "Name too short"
6               --> End
7  --> If: Form.Valid
8       [True] --> SaveEmployee  /* Server Action call */
9                    Input: FullName, DepartmentId
10               --> Message: "Saved!" (Success)
11               --> End
12       [False]--> End

Server Actions belong to the module-level logic layer. They run on the server and can call entity actions (Create, Update, Delete, Get) and Aggregates. To create: Logic tab → Server Actions → right-click → 'Add Server Action'. Name it 'SaveEmployee'. Add Input Parameters: right-click the Server Action → Add Input Parameter: - FullName: Text - DepartmentId: Department Identifier Add Output Parameter: - EmployeeId: Employee Identifier Action flow: Start → CreateEmployee: Employee.FullName=FullName, Employee.DepartmentId=DepartmentId, Employee.CreatedAt=CurrDateTime() → Assign: EmployeeId = CreateEmployee.Id → End The CreateEmployee entity action is auto-generated when the Employee entity exists. Drag it from the Logic tab or Toolbox.

1/* Server Action: SaveEmployee
2   Input:  FullName (Text), DepartmentId (Department Identifier)
3   Output: EmployeeId (Employee Identifier) */
4Start
5  --> CreateEmployee:
6        Employee.FullName     = FullName
7        Employee.DepartmentId = DepartmentId
8        Employee.CreatedAt    = CurrDateTime()
9  --> Assign: EmployeeId = CreateEmployee.Id
10  --> End

To connect Client and Server Actions, drag the Server Action into the Client Action flow. Service Studio creates a call node with input and output mapping. In ValidateAndSubmitForm (Client Action), after the Form.Valid True branch: - Drag SaveEmployee from Logic tab → Server Actions onto the flow - The call node shows input mappings: FullName → FullName, DepartmentId → DepartmentId - To use the output: after the call node, add an Assign: NewEmployeeId = SaveEmployee.EmployeeId - Then navigate: Destination node → EmployeeDetailScreen (pass NewEmployeeId as input) Every Server Action call crosses the network — minimize them by batching operations and avoiding calls inside loops.

1/* Client Action: ValidateAndSubmitForm - full flow */
2Start
3  --> (validation logic from Step 2)
4  --> If: Form.Valid
5       [True] --> SaveEmployee: FullName=FullName, DepartmentId=DepartmentId
6               --> Assign: NewEmployeeId = SaveEmployee.EmployeeId
7               --> Destination: EmployeeDetailScreen (EmployeeId=NewEmployeeId)
8       [False]--> End

Reactive Web and Mobile apps have a third action type: Data Actions. A Data Action is a server-side action that runs asynchronously when the screen loads, separate from the main render cycle. Create: right-click screen → 'Fetch data from Other Sources' → creates a Data Action. Data Actions are best for: - Fetching data that does not come from a single Aggregate (e.g., calling an API, running multiple aggregates and combining results) - Loading data that depends on complex server-side logic Data Actions are NOT for: - Simple database queries — use a Screen Aggregate instead (lighter weight) - Anything triggered by user interaction — use a Client Action that calls a Server Action Key behavior: Data Actions run in parallel with other screen data fetches and do not block the screen render. They provide a .Data output you bind to widgets.