Skip to main content

Actions

Actions are executable operations that can be triggered by events in the SoftyFlow web interface. They can be attached to UI elements and triggered by events like button clicks or value changes. This documentation provides a comprehensive guide to all available actions, their parameters, and how to use them.

UI Manipulation​

show​

  • Definition: Show an element
  • Description: Makes a DOM element visible.
  • Parameters:
    • Element id (string): The DOM element reference to show.
  • Usage: Use this action to reveal elements that were previously hidden.

hide​

  • Definition: Hide an element
  • Description: Makes a DOM element invisible.
  • Parameters:
    • Element id (string): The DOM element reference to hide.
  • Usage: Use this action to hide elements from the view.

toggleVisibilty​

  • Definition: Toggle an element's visibility
  • Description: Switches the visibility state of a DOM element.
  • Parameters:
    • Element id (string): The DOM element reference to toggle visibility.
  • Usage: Use when you need to switch between showing and hiding an element.

setRequired​

  • Definition: Set Required state
  • Description: Sets the required state of a DOM element.
  • Parameters:
    • Element id (string): The DOM element reference.
    • Value (boolean): Boolean value to set the required state.
  • Usage: Use to make form fields required or optional.

setDisable​

  • Definition: Set Disable state
  • Description: Sets the disabled state of a DOM element.
  • Parameters:
    • Element id (string): The DOM element reference.
    • Value (boolean): Boolean value to set the disable state.
  • Usage: Use to enable or disable form elements.

disableForm​

  • Definition: Set Disable state
  • Description: Sets the disabled state for all elements in a form.
  • Parameters:
    • Attach form (object): The form reference to disable.
  • Usage: Use to disable an entire form, for example while processing a submission.

refreshWidget​

  • Definition: Reload
  • Description: Reloads a widget with dynamic or static data sources.
  • Parameters:
    • Element id (string): The widget element reference to refresh.
  • Usage: Use to update the content of a widget with fresh data.

fillForm​

  • Definition: Fill out form input values
  • Description: Populates a form with specified values.
  • Parameters:
    • Attach form (object): The form reference to fill.
    • Form model (object): JSON object with field values to populate.
  • Usage: Use to pre-populate forms with data from other sources.

clearForm​

  • Definition: Clear out a form
  • Description: Clears all input values in a form.
  • Parameters:
    • Attach form (object): The form reference to clear.
  • Usage: Use to reset a form to its initial empty state.

confirm​

  • Definition: Prompt a confirm box message
  • Description: Shows a confirmation dialog to the user.
  • Parameters:
    • Message (string): The confirmation message to display.
  • Usage: Use to ask for user confirmation before proceeding with an action.

pushToArray​

  • Definition: Push a JSON object to an array
  • Description: Adds an object to a table or array.
  • Parameters:
    • Array Name (string): The variable reference of the array.
    • Json Object (object): The object to add to the array.
  • Usage: Use to add new items to a data collection.

validateForm​

  • Definition: Validate form elements
  • Description: Checks validation rules on all elements in a form.
  • Parameters:
    • Attach form (object): The form reference to validate.
    • Scroll (boolean): Whether to scroll to invalid fields.
    • Error List (boolean): Whether to display an error list.
  • Usage: Use to validate form inputs before submission.

setModel​

  • Definition: Define and update Models
  • Description: Defines or updates process variables to be used in workflows.
  • Parameters:
    • Name (string): The variable reference.
    • Update variable value (any): The new value to set.
  • Usage: Use to update model data in your application.

setVariable​

  • Definition: Set/define variable
  • Description: Defines a global variable value.
  • Parameters:
    • Name (string): The variable name.
    • Value (any): The value to set.
  • Usage: Use to store data for later use in your application.

alertMessage​

  • Definition: Alert box
  • Description: Shows an alert message to the user.
  • Parameters:
    • type (string): The alert type (info, success, warning, error).
    • message (string): The message to display.
  • Usage: Use to notify users about events or errors.

validateHistoryComment​

  • Definition: Validate History Comment
  • Description: Checks if History Comment is filled.
  • Parameters:
    • Attach Widget History (object): The history widget reference.
    • message (string): The error message to display if validation fails.
  • Usage: Use to ensure users provide comments for historical tracking.

Conditional and Loop Actions​

if​

  • Definition: Conditional statement
  • Description: Executes different actions based on conditions.
  • Parameters:
    • condition (boolean): The boolean expression to evaluate.
    • actions (object): Actions to execute in if, else, and elseif branches.
  • Usage: Use to create conditional logic in your application.

repeat (loop)​

  • Definition: Loop statement
  • Description: Executes a series of statements for a specified number of repetitions.
  • Parameters:
    • From (number): The starting loop index.
    • To (number): The ending loop index.
    • loopActions (array): Actions to execute in each iteration.
  • Usage: Use to perform actions repeatedly with different index values.

loopArray​

  • Definition: Loop An Array of Data
  • Description: Automatically loops through an array of data.
  • Parameters:
    • arraydata (array): The array to loop through.
    • actions (array): Actions to execute for each array element.
  • Usage: Use to process each item in a data collection.

Process and Workflow​

startProcess​

  • Definition: Workflow
  • Description: Starts a new process/workflow by ID.
  • Parameters:
    • instanceIdVar (string): Variable to store the started instance ID.
    • process (object): The process reference to start.
    • Disable forms (boolean): Whether to disable forms during process execution.
  • Usage: Use to initiate a workflow process.

OpenNextTask​

  • Definition: Workflow
  • Description: Goes to the next step of the current process.
  • Parameters:
    • instanceId (string): The process instance ID.
    • Fallback Redirect url (any): URL to redirect if no next step.
    • Timeout (number): Timeout value in seconds.
  • Usage: Use to advance users to the next task in a workflow.

update​

  • Definition: Move to the next step of your process
  • Description: Pushes your process to the next step of the workflow.
  • Parameters:
    • Task Id (string): The task ID to update.
    • Disable forms (boolean): Whether to disable forms during transition.
    • Measures (object): The data to pass to the next step.
  • Usage: Use to progress through workflow steps with data.

save​

  • Definition: Save process state
  • Description: Saves the current state of a process.
  • Parameters:
    • process (object): The process reference to save.
    • Task Id (string): The task ID to save.
  • Usage: Use to persist process state without advancing to the next step.

openInstance​

  • Definition: Open a new tab
  • Description: Opens a window to view a process instance.
  • Parameters:
    • Instance Id (string): The instance ID to open.
  • Usage: Use to view details of a specific process instance.

redirect​

  • Definition: Redirect to a new URL
  • Description: Loads a specified resource into the existing browsing context.
  • Parameters:
    • Redirect url (any): The URL to redirect to.
    • params (object): Parameters to pass in the URL.
    • New page (boolean): Whether to open in a new page.
  • Usage: Use to navigate users to different parts of the application.

execute​

  • Definition: Call a function to execute
  • Description: Defines a function and attaches it to a component for onClick execution.
  • Parameters:
    • Function (function): The function to execute.
  • Usage: Use to execute custom JavaScript functions.

Collection Operations​

addToCollection​

  • Definition: Insert new data into collection
  • Description: Inserts a document into a collection.
  • Parameters:
    • Collection (object): The collection reference.
    • Attach form (object): Form containing data to insert (optional).
    • Data model (object): JSON object with data to insert.
    • Joi validation schema (object-joi-schema): Schema for validating the data.
  • Usage: Use to create new records in a database collection.

addManyToCollection​

  • Definition: Insert many data into collection
  • Description: Inserts multiple documents into a collection.
  • Parameters:
    • Collection (object): The collection reference.
    • Attach loop (object): Loop reference containing data (optional).
    • Data model (array): Array of objects to insert.
    • Joi validation schema (object-joi-schema): Schema for validating the data.
  • Usage: Use to create multiple records in a database collection.

AggregateCollection​

  • Definition: Mongo Aggregation Query
  • Description: Executes complex aggregation queries to retrieve and format data.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • Collection (object): The collection reference.
    • Aggregation (array): Array of aggregation pipeline stages.
  • Usage: Use for complex data retrieval and transformation.

updateCollection​

  • Definition: Update data collection
  • Description: Updates a document by ID.
  • Parameters:
    • Collection (object): The collection reference.
    • Document id (string): ID of the document to update.
    • Attach form (object): Form containing update data (optional).
    • Data model (object): JSON object with update data.
    • Joi validation schema (object-joi-schema): Schema for validating the data.
  • Usage: Use to modify existing records in a collection.

getCollection​

  • Definition: Retrieve a list of data from collection
  • Description: Selects documents in a collection based on criteria.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • Collection (object): The collection reference.
    • Criteria (json): Query criteria for document selection.
  • Usage: Use to fetch multiple records matching specific criteria.

getDocument​

  • Definition: Retrieve one document from collection
  • Description: Selects a single document by ID and loads it to a form.
  • Parameters:
    • Collection (object): The collection reference.
    • Document id (string): ID of the document to retrieve.
    • Attach form (object): Form to load the document into (optional).
    • Dump var (string): Variable to store the result (optional).
  • Usage: Use to fetch a specific record by its identifier.

deleteDocument​

  • Definition: Remove one document from collection
  • Description: Deletes a document from a collection.
  • Parameters:
    • Collection (object): The collection reference.
    • Document id (string): ID of the document to delete.
  • Usage: Use to remove records from a collection.

External Data Source Operations​

insertTable (EDS)​

  • Definition: Insert object in the external data source
  • Description: Adds data to a table in an external database.
  • Parameters:
    • clientDatabase (object): The database connection reference.
    • Table (string): The table name.
    • Attach form (object): Form containing data to insert (optional).
    • Statement (object): JSON object with data to insert.
    • Joi validation schema (object-joi-schema): Schema for validating the data.
    • Options (any): Additional options for the operation.
  • Usage: Use to create records in external databases.

insertMany (EDS)​

  • Definition: Insert Many objects in the external data source
  • Description: Adds multiple objects to a table in an external database.
  • Parameters:
    • clientDatabase (object): The database connection reference.
    • Table (string): The table name.
    • data (array): Array of objects to insert.
    • Options (any): Additional options for the operation.
  • Usage: Use to create multiple records in external databases.

updateTables (EDS)​

  • Definition: Update Object in the external data source
  • Description: Modifies existing records in an external data source.
  • Parameters:
    • clientDatabase (object): The database connection reference.
    • Table (string): The table name.
    • Attach form (object): Form containing update data (optional).
    • Find Table (any): Criteria to find records to update.
    • Updated Table (object): JSON object with update data.
    • Joi validation schema (object-joi-schema): Schema for validating the data.
  • Usage: Use to modify existing records in external databases.

findOne (EDS)​

  • Definition: Get one element form the external data source
  • Description: Selects one row from a table in an external database.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • clientDatabase (object): The database connection reference.
    • Table (string): The table name.
    • Find (any): Criteria to find the record.
  • Usage: Use to fetch a specific record from an external database.

findMany (EDS)​

  • Definition: Get Many elements form the external data source
  • Description: Selects multiple rows from a table in an external database.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • clientDatabase (object): The database connection reference.
    • Table (string): The table name.
    • Find (any): Criteria to find the records.
  • Usage: Use to fetch multiple records from an external database.

countTables (EDS)​

  • Definition: Count elements from your databases
  • Description: Counts the number of rows matching criteria in an external database.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • clientDatabase (object): The database connection reference.
    • Table (string): The table name.
    • Find (any): Criteria for counting records.
  • Usage: Use to get the number of records matching specific criteria.

delete (EDS)​

  • Definition: Delete element on your databases
  • Description: Deletes records from a table in an external database.
  • Parameters:
    • clientDatabase (object): The database connection reference.
    • Table (string): The table name.
    • Find (any): Criteria to find records to delete.
  • Usage: Use to remove records from external databases.

exectuteStatement (EDS)​

  • Definition: Execute SQL statements on your databases
  • Description: Runs custom SQL statements on external databases.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • clientDatabase (object): The database connection reference.
    • Statement (string): The SQL statement to execute.
  • Usage: Use for custom database operations not covered by other actions.

User Management​

findUserById​

  • Definition: Retrieve a user by id
  • Description: Finds a user with their user ID.
  • Parameters:
    • userId (string): The ID of the user to find.
    • Attach form (object): Form to load the user data into (optional).
    • Dump var (string): Variable to store the result (optional).
  • Usage: Use to retrieve specific user information.

findUsers​

  • Definition: Retrieve a list of users
  • Description: Finds users matching specific criteria.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • Criteria (json): Query criteria for user selection.
  • Usage: Use to search for users based on various attributes.

userMetadata​

  • Definition: Update user metadata
  • Description: Updates metadata for a specific user.
  • Parameters:
    • userId (string): The ID of the user.
    • Metadata object (object): The metadata to update.
  • Usage: Use to store additional information about users.

getUserPendingTasks​

  • Definition: Retrieve user tasks
  • Description: Returns a list of connected user's pending/incomplete tasks.
  • Parameters:
    • Dump var (string): Variable to store the result.
  • Usage: Use to display task lists for the current user.

API and Integration​

invokeApi​

  • Definition: Invoke API endpoint
  • Description: Calls an API endpoint.
  • Parameters:
    • Dump variable (string): Variable to store the result.
    • Api endpoint (object): The API endpoint reference.
    • params (object): Parameters to pass to the API.
  • Usage: Use to integrate with other systems via APIs.

sendEmail​

  • Definition: Send a user email
  • Description: Sends an email using a template.
  • Parameters:
    • Provider (object): The email provider reference.
    • Template (object): The email template reference.
    • variables (object): Variables to use in the template.
    • From (string): Sender email address.
    • To (string): Recipient email address.
    • Cc (string): Carbon copy recipients.
    • Reply-To (string): Reply-to email address.
    • attachments (array): Files to attach to the email.
    • Subject (string): Email subject line.
  • Usage: Use to send notifications and communications to users.

nextValue​

  • Definition: Generate next value
  • Description: Generates the next numeric value using a unique identifier.
  • Parameters:
    • Dump variable (string): Variable to store the result.
    • Label (string): Unique identifier for the sequence.
    • Padding (number): Number of digits to pad the value to.
  • Usage: Use to generate sequential identifiers.

API (P)​

  • Definition: Call an API
  • Description: Makes HTTP requests to external APIs.
  • Parameters:
    • Method (string): HTTP method (GET, POST, PUT, DELETE).
    • Url (string): The endpoint URL.
    • header (object): HTTP headers to include.
    • body (object): Request body data.
  • Usage: Use for more general API integrations not covered by other actions.

previewPDF​

  • Definition: Generate PDF
  • Description: Generates a PDF from a template with provided context data.
  • Parameters:
    • Dump var (string): Variable to store the result.
    • Template (object): The PDF template reference.
    • Context (object): Data to use in rendering the PDF.
  • Usage: Use to create documents from templates.

editPDFTemplate​

  • Definition: Edit a PDF template
  • Description: Opens a document in the PDF editor for editing.
  • Parameters:
    • Template (object): The PDF template reference to edit.
  • Usage: Use to customize PDF templates directly in the interface.

Process-Specific Actions (P)​

These actions are specifically designed for use within process definitions.

launchProcess (P)​

  • Definition: Workflow
  • Description: Starts a new process/workflow by ID within a process context.
  • Parameters:
    • process (object): The process reference to start.
    • body (object): Data to pass to the new process.
  • Usage: Use to start sub-processes from within a process.

nextTask (P)​

  • Definition: Get Next Task
  • Description: Returns the next task ID for an instance.
  • Parameters:
    • instanceId (string): The process instance ID.
  • Usage: Use to determine the next step in a workflow.

measures (P)​

  • Definition: Retrieve instance measures
  • Description: Returns instance measures.
  • Parameters:
    • instanceId (string): The process instance ID.
  • Usage: Use to access process metrics and variables.

if (P)​

  • Definition: Conditional statement
  • Description: Process-specific conditional logic.
  • Parameters:
    • condition (boolean): The boolean expression to evaluate.
  • Usage: Use for conditional branching within processes.

validateTask​

  • Definition: Move to the next step of your process
  • Description: Pushes a process to the next step with provided measures.
  • Parameters:
    • Task Id (string): The task ID to validate.
    • Measures (object): Data to pass to the next step.
  • Usage: Use to advance process execution with data.

saveTask (P)​

  • Definition: Save Task
  • Description: Saves a task using its ID.
  • Parameters:
    • Task Id (string): The task ID to save.
    • body (object): Data to save with the task.
  • Usage: Use to persist task state without advancing.

UpdateInstanceVariables​

  • Definition: Update the instance variables
  • Description: Updates instance variables and recalculates measures.
  • Parameters:
    • instanceId (string): The process instance ID.
    • Variables (object): New variable values to set.
  • Usage: Use to modify process variables during execution.

Best Practices​

  1. Event Selection: Choose appropriate events to trigger actions (onClick, onChange, onLoad, etc.).
  2. Action Chaining: Multiple actions can be chained together to create complex workflows.
  3. Error Handling: Use conditional actions to handle potential errors in your flows.
  4. Performance: Be mindful of performance implications when using actions that fetch data or make API calls.
  5. Security: Validate user input before performing database operations or API calls.
  6. User Experience: Use visual feedback actions (like alertMessage) to keep users informed about process status.

Working with Events​

Actions can be triggered by various events in the SoftyFlow interface:

  • onClick: Triggered when a user clicks on an element.
  • onChange: Triggered when a value changes (for input fields, dropdowns, etc.).
  • onLoad: Triggered when a page or component loads.
  • onSubmit: Triggered when a form is submitted.
  • onBlur: Triggered when an element loses focus.
  • onFocus: Triggered when an element receives focus.

To attach an action to an event:

  1. Select the element in the interface builder.
  2. Navigate to the Events tab in the properties panel.
  3. Choose the event type.
  4. Add the desired action from the action palette.
  5. Configure the action parameters as needed.