A Developer's Guide to Web Interface Actions

Actions are the engine of your Softyflow web interface. They are the powerful, executable commands that bring your application to life, turning static pages into dynamic, interactive experiences. By linking actions to user interactions (like a button click) or system events (like a page loading), you can orchestrate complex, logic-driven workflows without needing to write extensive code.

This guide provides a comprehensive walkthrough of every action available in the web modeler. We'll explore their parameters, share practical examples, and offer best practices to help you build robust and user-friendly applications.

Action Catalog​

Find the action you need quickly using the links below.

1. UI Manipulation: Crafting a Responsive User Experience​

These actions dynamically alter the appearance and state of UI elements, allowing you to create a fluid and intuitive interface for your users.

1.1. show: Revealing Hidden Elements​

The show action modifies an element's visibility, changing its CSS display property from none to its default value, effectively making it appear on the page.

Use Case​

This action is fundamental for creating responsive and dynamic forms. You can design interfaces that hide complex or conditional sections by default, revealing them only when a user's input makes them relevant. This declutters the UI and guides the user through the workflow.

Configuration​

• Element ID (string): The unique identifier of the DOM element you want to make visible.

Example Scenario​

Imagine a registration form where a checkbox asks, "Are you registering as a business?". If the user checks this box, you want to display a field for their VAT number.

1. Trigger: The onClick event of the "Are you registering as a business?" checkbox.
2. Action: A show action is configured with the Element ID of the container holding the VAT number input field.
3. Result: When the box is checked, the VAT number field instantly appears. When unchecked (using a corresponding hide action), it disappears, keeping the form clean and relevant to the user's context.

1.2. hide: Concealing Elements​

The hide action sets an element's CSS display property to none, effectively removing it from the user's view and the page layout.

Use Case​

This is the direct counterpart to the show action. It's essential for cleaning up the interface by hiding controls, messages, or sections that are no longer relevant to the user's current context. It is frequently used within the else block of an if action to create toggling effects.

Configuration​

• Element ID (string): The unique identifier of the DOM element you want to hide.

Example Scenario​

In the "Ship to a different address" example from the show action, an if action would check the state of the checkbox.

• The if (true) branch would contain the show action for the shipping address form.

• The else branch would contain a hide action targeting the same form, ensuring it is hidden when the user unchecks the box.

1.3. toggleVisibility: Switching Between Visible and Hidden​

The toggleVisibility action provides a convenient way to switch an element's visibility. It automatically checks if an element is currently shown or hidden and applies the opposite state.

Use Case​

This action is perfect for creating interactive UI elements that a user can open and close repeatedly. It simplifies the logic for features like "Read More" expanders, collapsible panels, FAQ accordions, or dropdown menus, as you don't need to manage the state with separate show and hide actions.

Configuration​

• Element ID (string): The unique identifier of the DOM element to toggle.

Example Scenario​

You have a "Show Details" button that reveals an advanced configuration panel. By attaching the toggleVisibility action to the button's onClick event and targeting the panel's ID, you can create the entire show/hide functionality with a single action. The first click shows the panel, the second hides it, the third shows it again, and so on.

1.4. setRequired: Dynamically Enforcing Rules​

The setRequired action programmatically adds or removes the required HTML attribute on a form field. This fully integrates with Softyflow's built-in form validation, allowing you to enforce rules dynamically based on user input.

Use Case​

This action allows you to build intelligent, adaptive forms. Instead of overwhelming users with validation errors for fields that may not apply to them, you can make fields required only when they become relevant, guiding the user to fill out the form correctly.

Configuration​

• Element ID (string): The ID of the target form element (e.g., a text input, dropdown, or checkbox).
• Value (boolean): Set to true to make the field required, or false to make it optional.

Example Scenario​

In a feedback form, if a user selects a rating of "1 Star" or "2 Stars" from a dropdown, you want to require them to leave a comment.

1. Trigger: The onChange event of the star rating dropdown.
2. Action: An if action checks if SF_input.value <= 2.
3. Logic:
   • If true, a setRequired action targets the "Comments" textarea with a Value of true.
   • In the else branch, another setRequired action targets the same textarea with a Value of false, making it optional for higher ratings.

1.5. setDisable: Controlling User Interaction​

The setDisable action gives you programmatic control over the disabled state of a form element, allowing you to enable or disable it on the fly. A disabled element is visible but read-only and cannot be interacted with.

Use Case​

Use this to prevent users from editing certain fields based on their permissions, the application's state, or a choice they've made elsewhere on the form. It provides a clear visual indicator that a field's value is fixed and not open for modification.

Configuration​

• Element ID (string): The ID of the form element to control.
• Value (boolean): Set to true to disable the element, or false to enable it.

Example Scenario​

On an "Edit Profile" form, the user's email address is displayed but should not be editable. On page load, a setDisable action is triggered with a Value of true, targeting the email input field. This locks the field, preventing accidental changes while still showing the user their current email address.

1.6. disableForm: Safeguarding Form Integrity​

The disableForm action is a powerful utility that disables all interactive elements—including inputs, buttons, and dropdowns—within a specified form container in a single step.

Use Case​

This is a crucial action for maintaining data integrity and providing clear user feedback during submission events. By disabling the form, you prevent users from accidentally clicking the "Submit" button multiple times or changing data while a background operation (like an API call or process update) is in progress.

Configuration​

• Attach form (object): A reference to the form container that holds all the elements to be disabled.

Example Scenario​

When a user clicks the "Save and Continue" button on a multi-page wizard:

1. The very first action triggered is disableForm, which instantly locks the current page's form.
2. Subsequent actions, such as updateCollection or startProcess, can now run without the risk of the user altering the data.
3. Once the background operations are complete, you can either redirect the user or re-enable the form if necessary.

1.7. refreshWidget: Displaying Up-to-the-Minute Data​

The refreshWidget action forces a specific widget (such as a List, Table, Chart, or Data Grid) to re-execute its data query and render itself with the most current information from its data source.

Use Case​

This action is essential for creating a real-time, dynamic user experience. After any action that creates, updates, or deletes data displayed in a widget, you must call refreshWidget to ensure the user immediately sees the result of their action without needing to manually reload the page.

Configuration​

• Element ID (string): The ID of the widget you want to refresh.

Example Scenario​

A user is managing a task list. They add a new task using a form in a modal window.

1. The modal's "Add Task" button triggers an addToCollection action to save the new task.
2. Immediately following, a hide action closes the modal.
3. The final action in the chain is refreshWidget, targeting the main task list widget in the background. When the modal closes, the user sees their new task instantly appear in the list.

1.8. fillForm: Populating Forms with Data​

The fillForm action efficiently populates an entire form's fields with data from a single JSON object. It works by matching the keys in the object to the id attributes of the corresponding form fields.

Use Case​

This is a massive time-saver for any "edit" or "view details" functionality. When a user selects an item from a list to edit, you can use getDocument to fetch the item's complete data object, then pass it directly to fillForm to instantly and completely populate the editing form.

Configuration​

• Attach form (object): The form container to be filled.
• Form model (object): A JSON object containing the key-value pairs to populate the form with.

Example Scenario​

In a CRM application, a user clicks the "Edit" icon next to a contact's name in a table.

1. The onClick event on the icon triggers a getDocument action, using the contact's ID to fetch their full record from the database and storing it in a variable called selected_contact.
2. The next action is fillForm, which targets the "Edit Contact" form and uses the selected_contact variable as its Form model.
3. A final show action reveals the "Edit Contact" form, which is now fully populated with the contact's data, ready for modification.

1.9. clearForm: Resetting User Input​

The clearForm action provides a simple way to reset all fields within a specified form container to their original, empty state.

Use Case​

This is a quality-of-life feature for improving user experience on complex forms. It's typically attached to a "Reset" or "Clear" button, giving users a one-click method to start over without the tedious task of manually clearing each input field.

Configuration​

• Attach form (object): The form container whose fields are to be cleared.

Example Scenario​

A user is filling out a search form with many filter options (date ranges, categories, keywords). If their search yields no results and they want to try a different query, they can click a "Reset Filters" button that triggers a single clearForm action, instantly emptying all fields so they can begin again.

1.10. confirm: Asking for User Confirmation​

The confirm action displays a native browser confirmation dialog with a custom message. It is a modal action that halts the execution of subsequent actions until the user clicks "OK" or "Cancel".

Use Case​

This is a critical safety mechanism that should always be used before any destructive or irreversible operation. Use it to prevent accidental data loss when a user tries to delete a record, abandon unsaved changes, or submit a final application.

Returns​

• Output (boolean): The most important feature of this action is its boolean output. It returns true if the user clicks "OK" and false if they click "Cancel". This output should be used as the condition for a subsequent if action to control the workflow.

Configuration​

• Message (string): The question or warning to display in the confirmation box (e.g., "Are you sure you want to permanently delete this invoice?").

1.11. alertMessage: Providing Clear User Feedback​

The alertMessage action displays a small, non-blocking notification pop-up (often called a "toast") to provide immediate and contextual feedback to the user.

Use Case​

This is the standard and best way to communicate the result of a background operation. It informs the user about the success or failure of their action without interrupting their workflow, unlike a standard browser alert.

Configuration​

• Type : Defines the style and color of the alert. Valid options are info, success, warning, and error.
• Message (string): The text content to display in the notification. This can be static text or include dynamic values from variables.

Example Scenario​

After a user successfully saves changes to their profile, an alertMessage with a Type of success appears in the corner of the screen with the Message: "Profile updated successfully!". If the save operation failed due to a network issue, an alertMessage with a Type of error would appear instead, with a message like "Error: Could not save profile. Please try again later."

2. Data and Variable Management​

These actions are the building blocks for managing state, handling data, and controlling the information that powers your application.

2.1. setModel: Managing Process Variables​

The setModel action is used to define or update a process variable (also known as a model). These variables are the core data state of your application, are persistent within a given process instance, and can be passed to back-end processes.

Use Case​

Use setModel to store and manipulate any data that is essential to your workflow's logic, such as a customer's ID, a calculated total, or the current status of an application. This data acts as the "memory" of your process from one step to the next.

Configuration​

• Name (string): The name of the model variable (e.g., invoice_data).
• Update variable value (any): The new value for the variable. This can be a static value, the result of a formula ({{ ... }}), or data from another element or variable.

Example Scenario​

In a multi-page application wizard, a user fills out their personal information on page one. On clicking "Next", a setModel action saves the entire form's data into a single object model named applicant_data. This model can then be accessed on subsequent pages to pre-fill information or guide the workflow.

2.2. setVariable: Handling Page-Level Variables​

The setVariable action defines or updates a global, temporary variable that is accessible anywhere on the current page. Unlike models, these variables are non-persistent and are reset if the page is reloaded.

Use Case​

setVariable is perfect for storing temporary UI state that doesn't need to be saved with the process instance data. This is useful for tracking UI-specific information like flags, counters, temporary user selections, or whether an animation has already played.

Configuration​

• Name (string): The name of the global page variable (e.g., is_details_panel_visible).
• Value (any): The value to assign to the variable.

Example Scenario​

You want to show a "Welcome" popup to a user only the first time they click a certain button on a page.

1. The button's action is wrapped in an if condition that checks a page variable: {{ variables.popup_has_been_shown !== true }}.
2. Inside the if (true) branch, you use a show action to display the popup.
3. Immediately after, you use setVariable to set the Name popup_has_been_shown to a boolean Value of true.
4. Subsequent clicks on the button will fail the if condition, preventing the popup from appearing again.

2.3. pushToArray: Dynamically Building Lists​

The pushToArray action adds a new element (typically a JSON object) to an array stored in a model or a page variable. If the specified array doesn't exist, this action will create it first before adding the element.

Use Case​

This action is invaluable for any feature where a user needs to dynamically build a list of items. It is the core mechanism behind shopping carts, adding line items to an invoice, attaching multiple files, or adding invitees to an event list.

Configuration​

• Array Name (string): The name of the model or variable array you want to add to (e.g., invoice_items).
• Json Object (object): The object to be added as a new element to the array.

Example Scenario​

In an invoice creation form, there is a sub-form for adding a single line item (with fields for description, quantity, and price). When the user clicks an "Add Item" button:

1. A pushToArray action is triggered.
2. The Array Name is set to models.invoice_items.
3. The Json Object is constructed from the sub-form's fields: { "desc": "{{ item_description.value }}", "qty": {{ item_quantity.value }}, "price": {{ item_price.value }} }.
4. Finally, a refreshWidget action updates the invoice line items list to display the newly added item.

3. Logic and Flow Control​

Control the execution flow of your actions with conditional logic and loops, enabling you to build complex and responsive behaviors.

3.1. if: Making Decisions in Your Logic​

The if action is the cornerstone of decision-making in Softyflow. It allows you to execute different sets of nested actions based on whether a given condition evaluates to true or false. It supports if, else if, and else branches for building out complex logic.

Use Case​

This action is fundamental for almost any non-trivial workflow. It's used for validating form inputs, checking user roles and permissions, responding to user selections, handling different API responses, and creating any kind of conditional logic path.

Configuration​

• condition (boolean): An expression that must resolve to a boolean true or false. You can write complex conditions using JavaScript within {{ }}.
• actions: Separate nested action blocks for the if, else if, and else branches.

Example Scenario​

A "Submit" button's onClick event first triggers a confirm action with the message "Are you sure you want to submit?". The result of this action is stored in a variable called user_confirmed.

1. The next action is an if statement with the condition {{ variables.user_confirmed }}.
2. In the if (true) branch, you place the actions to save the data (e.g., updateCollection, startProcess).
3. In the else (false) branch, you can place an alertMessage that says "Submission cancelled."

3.2. repeat (loop): Executing Actions Multiple Times​

The repeat action creates a simple loop that executes a set of nested actions a specified number of times. It provides a special SF_loop.currentIndex variable that you can access within the loop to know the current iteration number (starting from the "From" value).

Use Case​

This is useful for performing repetitive tasks that are not based on iterating over a data collection. Examples include creating a set number of default records, running a calculation several times with incremental changes, or generating placeholder data for testing.

Configuration​

• From (number): The starting index of the loop (inclusive).
• To (number): The ending index of the loop (inclusive).
• loopActions (array): The block of actions to execute in each iteration.

Example Scenario​

When a user creates a new "Project", you want to automatically generate three standard tasks for them.

1. A repeat action is configured with From 1 and To 3.
2. Inside the loop, you use the addToCollection action to create a new document in the "Tasks" collection.
3. The task document could be: { "project_id": "{{ models.new_project_id }}", "task_name": "Default Task #{{ SF_loop.currentIndex }}" }.
4. This will result in three new tasks being created, named "Default Task #1", "Default Task #2", and "Default Task #3".

3.3. loopArray: Iterating Over Data Collections​

The loopArray action iterates over a given array of data (from a model, variable, or API response), executing a block of nested actions for each element in that array. It is the equivalent of a forEach or for...of loop in programming.

Use Case​

This is one of the most powerful actions for batch data processing. It is essential for updating multiple database records, calling an API for each item in a list, performing calculations on each row of a shopping cart, or sending customized emails to a list of users.

Contextual Variables​

Inside the loop, you gain access to two special, context-aware variables:

• SF_loop.currentItem: The full object or value for the current iteration.
• SF_loop.currentIndex: The zero-based index of the current item in the array.

Configuration​

• arraydata (array): The array you want to iterate over.
• actions (array): The block of actions to execute for each element.

Example Scenario​

You have a list of products in a shopping cart, stored in an array called models.cart_items. You need to update the inventory level for each product in the database.

1. You use loopArray and set its arraydata to {{ models.cart_items }}.
2. Inside the loop, you add an updateCollection action for the "Products" collection.
3. The Document id would be {{ SF_loop.currentItem.product_id }}.
4. The Data model to update would be { "inventory": {{ SF_loop.currentItem.new_inventory_level }} }.

4. Process and Workflow Actions​

Manage business processes, control task progression, and handle user navigation within your application.

4.1. startProcess: Initiating a New Workflow​

The startProcess action formally initiates a new instance of a Softyflow process model. This is the starting point for any structured business process in your application.

Use Case​

This action is triggered when a user takes an action that should kick off a workflow, such as clicking "Submit Application," "Create New Order," or "Begin Onboarding." It creates a new entry in the process engine that can then be tracked, monitored, and progressed.

Returns​

• This action can optionally store the instanceId of the newly created process into a model or page variable. This ID is the unique identifier for this specific workflow instance and is crucial for tracking or navigating to it later.

Configuration​

• instanceIdVar (string, optional): The name of a variable to store the ID of the new process instance.
• process : A reference to the process model you want to start.

4.2. OpenNextTask: Guiding Users Through Workflows​

The OpenNextTask action is a smart navigation utility that improves user experience by automatically guiding them to their next piece of work. It inspects a process instance for the next available human task and immediately redirects the user to the correct form.

Use Case​

Use this to create a seamless, guided workflow. For example, after a manager approves one request, OpenNextTask can check if another approval is pending in their queue and take them there directly, saving them from having to return to a dashboard and manually find their next task.

Configuration​

• instanceId (string): The ID of the process instance to check for a next task.
• Fallback Redirect url (string): A URL to redirect the user to if no subsequent task is found (e.g., because the process has ended or the next step is an automated task).

Example Scenario​

An HR manager is working through a queue of leave requests. After clicking "Approve" on one request:

1. An update action completes the current task.
2. The next action is OpenNextTask. It finds that there is another leave request from a different employee pending their approval.
3. It immediately redirects the manager to that new task form, allowing them to process requests back-to-back efficiently. If no tasks were left, it would redirect them to the specified fallback URL, like /dashboard.

4.3. update: Completing a Task and Advancing the Process​

The update action signals to the Softyflow process engine that the current human task is complete. This is the primary mechanism for advancing a workflow from one step to the next as defined in your process model.

Use Case​

This action should be attached to the main concluding action on a task form, such as an "Approve," "Reject," "Submit," or "Complete" button. Triggering it completes the task and allows the process to evaluate the next step in the flow.

Configuration​

• Task Id (string): The ID of the current task being completed. This is often available in the page context.
• Measures (object, optional): An object of key-value data that you want to pass from this task to the subsequent steps of the workflow. This is how you pass decisions (e.g., { "approval_status": "rejected" }) or data downstream.

4.4. save: Saving a Draft​

The save action saves the current data and state of a task form without completing the task or advancing the process.

Use Case​

This is a crucial user experience feature for long or complex forms where a user might need to gather information over time. It allows them to save a draft of their work and return to it later. The task remains assigned to them, and the workflow does not progress.

Configuration​

• Task Id (string): The ID of the current task whose data you want to save. This is typically available in the page context.

4.5. openInstance: Viewing Process Details​

The openInstance action navigates the user to the detailed "Instance View" for a given process instance, typically opening it in a new browser tab. This view provides a complete audit trail, showing the process history, current status, associated data, and any errors.

Use Case​

This is perfect for providing "drill-down" capabilities from dashboards, reports, or list views. When a user sees a summary of many process instances, this action lets them click on a specific one to investigate its full history and details.

Configuration​

• Instance Id (string): The unique ID of the process instance you want to open.

4.6. redirect: Navigating Through Your Application​

The redirect action programmatically navigates the user's browser to a new URL, either within your application or to an external site.

Use Case​

This is a fundamental action for controlling application flow and navigation. It is used to send users to a "Thank You" page after a submission, to a login page if they are not authenticated, or to a specific dashboard based on their role.

Configuration​

• Redirect url (string): The destination URL (e.g., /dashboard or https://example.com).
• params (object, optional): An object of key-value pairs that will be appended to the URL as query string parameters (e.g., { "id": 123 } becomes ?id=123).
• New page (boolean, optional): If set to true, the URL will open in a new browser tab. Defaults to false.

5. Collection (Database) Operations​

Perform CRUD (Create, Read, Update, Delete) operations directly on your Softyflow database collections.

5.1. addToCollection: Creating New Database Records​

The addToCollection action inserts a single new document into a specified database collection.

Use Case​

This is the primary action for creating new records in your application's database. It's used whenever a user saves a new entity, such as creating a new contact, submitting a new form, or logging a new event.

Returns​

• Output (object): The action can output the newly created document—including its database-generated _id—into a variable for immediate use in subsequent actions (e.g., to redirect to the new record's detail page).

Configuration​

• Collection (object): A reference to the target database collection.
• Data model (object): A JSON object representing the document to be inserted.

5.2. addManyToCollection: Bulk-Inserting Data​

The addManyToCollection action inserts an entire array of documents into a collection in a single, high-performance database operation.

Use Case​

This is the most efficient way to perform bulk data imports or create multiple records at once. It's ideal for scenarios like uploading and processing a CSV file of contacts, migrating data from another system, or generating a large set of default data.

Configuration​

• Collection : The target collection.
• Data model (array): An array of JSON objects, where each object represents a new document to be inserted.

5.3. updateCollection: Modifying Existing Records​

The updateCollection action finds an existing document in a collection by its unique _id and updates it with new data.

Use Case​

This is the standard action for any "edit" or "update" functionality. It's used when a user saves changes to their profile, modifies an existing order, or changes the status of a project.

Configuration​

• Collection : The target collection.
• Document id (string): The _id of the document you want to update.
• Data model (object): An object containing only the fields you want to change and their new values.

5.4. getCollection: Querying for Multiple Documents​

The getCollection action retrieves a list of documents from a collection that match a given query. It supports powerful filtering, sorting, and pagination capabilities using MongoDB's query syntax.

Use Case​

This is the most common way to fetch the data needed to populate your application's UI. It is used for filling lists, data grids, dropdown selections, and chart data.

Returns​

• Output (array): The action dumps the resulting array of matching documents into a specified variable for use in widgets or other actions.

Configuration​

• Dump var (string): The name of the variable where the array of results will be stored.
• Collection : The collection to query.
• Criteria (json, optional): A MongoDB-style query object to filter ({ "status": "active" }), sort ({ "sort": { "createdAt": -1 } }), and limit the results.

5.5. getDocument: Fetching a Single Document​

The getDocument action retrieves one single, complete document from a collection by its unique _id.

Use Case​

This action is used whenever you need to fetch the full details of a specific item. It is typically triggered when a user clicks on an item in a list, which then prepares the data for an "edit" form or a "details" view.

Returns​

• Output (object): The action dumps the complete document object into a specified variable.

Configuration​

• Collection : The collection to query.
• Document id (string): The _id of the document to retrieve.
• Dump var (string): The name of the variable where the resulting document will be stored.

5.6. deleteDocument: Removing Data​

The deleteDocument action permanently deletes a single document from a collection, identified by its unique _id.

Use Case​

This action is used to remove records from the. Because it is a destructive and irreversible action, it should always be protected by a confirm action to prevent accidental data loss.

Configuration​

• Collection (object): The collection to delete from.
• Document id (string): The _id of the document to be deleted.

5.7. AggregateCollection: Performing Advanced Database Queries​

The AggregateCollection action executes a powerful MongoDB aggregation pipeline, which allows for multi-stage data processing, transformation, and analysis directly within the database for maximum efficiency.

Use Case​

Use this for advanced reporting and data analysis that goes beyond simple filtering. It's perfect for grouping data, calculating sums and averages (e.g., for a dashboard), reshaping document structures, joining data from related collections, and performing complex multi-stage queries.

Returns​

• Output (array): The action dumps the results of the final stage of the aggregation pipeline into a specified variable.

Configuration​

• Dump var (string): The variable to store the aggregation result.
• Collection (object): The collection to run the aggregation on.
• Aggregation (array): An array of MongoDB aggregation pipeline stages (e.g., $match, $group, $sort, $lookup).

Example Scenario​

You want to build a sales dashboard that shows total sales per region. You can use an aggregation pipeline to:

1. $match all sales within the last quarter.
2. $group the results by the sales_region field and use the $sum accumulator to calculate the total sale_amount for each region.
3. $sort the results in descending order to show the top-performing regions first.

6. External Data Source (EDS) Actions​

Integrate and interact with external databases (like SQL Server, PostgreSQL, MySQL) that you have configured as External Data Sources.

6.1. insertTable: Creating Records in External Systems​

The insertTable action inserts a new row into a specified table in a configured external database.

Use Case​

Use this to create records in external or legacy systems, ensuring data is synchronized between your Softyflow application and other parts of your company's IT infrastructure.

Configuration​

• clientDatabase (object): The configured EDS connection to use.
• Table (string): The name of the target table in the external database.
• Statement (object): An object where keys are the column names and values are the data to be inserted for the new row.

6.2. updateTables: Modifying Records in External Systems​

The updateTables action updates one or more existing rows in an external database table that match a given where clause.

Use Case​

Use this to modify data in your external systems when a corresponding event happens in your Softyflow application, keeping all your disparate systems in sync without manual intervention.

Configuration​

• clientDatabase (object): The EDS connection to use.
• Table (string): The name of the target table.
• Find Table (object): The where clause to identify the row(s) to update (e.g., { "user_id": 123 }).
• Updated Table (object): An object containing the new column values to set.

6.3. findMany: Querying External Data​

The findMany action retrieves multiple rows from an external table that match a given query, similar to a SELECT ... WHERE statement in SQL.

Use Case​

This action allows you to fetch and display data from external and legacy systems directly within your Softyflow application's UI, providing a unified, comprehensive view of all your relevant business data to the user.

Returns​

• Output (array): The action dumps an array of matching rows into a specified variable.

Configuration​

• Dump var (string): The variable to store the array of results.
• clientDatabase (object): The EDS connection to use.
• Table (string): The table name.
• Find (object, optional): The where clause for the query.

6.4. exectuteStatement: Unleashing the Power of Raw SQL​

The exectuteStatement action provides a powerful but potentially dangerous ability to execute a raw SQL query string directly on an external database.

Use Case​

This is your tool of last resort for ultimate flexibility. Use it for complex queries that involve multiple JOINs, calling stored procedures, or any other advanced SQL operation that is not easily covered by the standard, structured EDS actions.

Returns​

• Output (array): The action dumps the results of the query into a specified variable.

Configuration​

• Dump var (string): The variable to store the results of the query.
• clientDatabase (object): The EDS connection.
• Statement (string): The raw SQL query to execute.

7. API and Integration Actions​

Connect your Softyflow application to the world by integrating with external APIs and services.

7.1. invokeApi: Connecting to Any API​

The invokeApi action calls a pre-configured API endpoint and returns the full response.

Use Case​

This action is your gateway to the outside world. Use it to integrate with any third-party service (e.g., payment gateways like Stripe, address validation services, currency converters) or to communicate with your own company's custom microservices.

Returns​

• Output (any): The action dumps the entire response from the API—including the body, headers, and status code—into a specified variable for you to process and use in your application.

Configuration​

• Dump variable (string): The variable to store the API's full response object.
• Api endpoint (object): The configured API endpoint to call.
• params (object, optional): Parameters to send with the API request, which can be mapped to the request body, query string, or headers depending on the endpoint's configuration.

7.2. sendEmail: Communicating with Users​

The sendEmail action sends an email to a recipient using a configured email provider (such as SendGrid or Mailgun) and a pre-defined, dynamic email template.

Use Case​

This is essential for all automated user communication. It should be used for all transactional emails, such as welcome messages, password resets, order confirmations, and workflow status notifications.

Configuration​

• Provider (object): The email service provider to use for sending.
• Template (object): The pre-designed email template to use.
• To (string): The recipient's email address.
• variables (object, optional): An object of data used to populate the dynamic fields in your email template (e.g., providing a value for {{name}} or {{order_id}}).

7.3. previewPDF: Generating Documents on the Fly​

The previewPDF action dynamically generates a PDF document by merging a JSON data object with a pre-defined PDF template.

Use Case​

Use this to create professional, printable documents on demand. This is perfect for generating invoices, reports, certificates of completion, shipping labels, contracts, and any other formatted document based on your application's data.

Returns​

• Output (object): The action dumps the generated PDF data (typically as a base64 string or a file object) into a specified variable. This can then be used to show a preview of the PDF to the user, allow them to download it, or attach it to an email.

Configuration​

• Dump var (string): A variable to store the generated PDF data.
• Template (object): The PDF template to use for generation.
• Context (object): The JSON data object containing the information to populate the template with.

8. Best Practices for Building with Actions​

By mastering these actions and adhering to these best practices, you can move beyond simple forms and build sophisticated, high-performance, and user-friendly web applications with Softyflow's powerful low-code platform.