Setting Up Workflow Triggers

First published on: 08/08/2023/5:59 pm

 

 

 

A workflow's trigger defines how a workflow will receive data. For example, the trigger may fetch data on a schedule, or it may be initiated by an API call or event. The trigger can be configured during setup via the "New Workflow Wizard", or you can edit an existing workflow's trigger as outlined below. 

 

Video: About Workflow Triggers

 

 

 

To open an existing workflow

  • Go to a project's "Assets" page
  • Click on the project name (marker 1)
    • Or select it directly from the "Assets" menu (marker 2)
  • Click "Edit" 

 

 

The Workflow Designer tool will open with a left-hand navigation menu.

 

Press the "Workflow Trigger" icon to open the workflow trigger details. It will look like one of these: 

  

 

On the workflow trigger pane, you can establish every workflow trigger setting, including:

  • Data source
  • Format settings
  • Data source filters
  • Parameters
  • Schedule settings

 

Add a Data Source 

The first workflow trigger configuration fields are located under "Data Source", which specifies the vendor ("Connector"), system ("Connection Config"), and type of data ("Data Type") the workflow will process.  

 

First, select the desired connector from the drop-down menu (marker 1 below).  

 

 

The connection config pick list identifies which system will be accessed, as defined in the project’s settings.

 

  • Select from the available drop-down menu options or press the “+” button to add a new option (marker 2 above).
    • Above, the user created a new configuration called “ServiceLayer.”
    • Each configuration is named by the user. 
  • Choose a data type from the data type drop-down menu (marker 3 above).
    • This determines the type of data to be retrieved from the system.
  • If available, a "Transaction ID" (marker 4 above) will be filled in automatically, but you can update it manually.

 

Data types vary, but examples include: 

  • Get a list of customers 

  • Get a list of orders 

  • Get query results 

  • Get transaction records for enqueued workflow messages (marker 3 above) 

 

Below the transaction ID field are additional message handling and retry settings. You can configure these to define retry behavior. 

Format Settings 

Selecting a data type defines which third-party data to fetch. However, each vendor’s data may exist in a different format (e.g., JSON, CSV, or XML). This section defines the expected format of the selected data type so it can be normalized into a standard Saltbox format.

 

Simply put: This section tells Saltbox how to read the incoming message data.

 

Usually, the "Format Settings" fields will be auto-selected and pre-populated when you choose a data type. Exceptions include general-purpose data types like SFTP/FTP and the "Universal API Connector". In these cases, you must specify format setting details, such as the file format provided by the selected data type. 

 

Specify the formatting to be applied to triggered messages by determining the following: 

  • Is the data in the default format for the selected data type, or does it need to use a special message format handler?

    • The Data Source Format field will auto-populate when the selected data type is in the default format. 

  • Will the system perform well at scale?

    • If not, the data may need to be split into multiple messages.

      • Each line of a CSV file can be split into separate messages.

      • Each result of a query can be processed separately.

    • You'll know the data needs to be split into multiple messages if you need to use a ‘for-each’ loop in the workflow to iterate over a collection in the data generated.

      • To split into multiple messages, set the field called Data Field Path used to Sub-Divide Transactions.

 

The Data Source Format will determine how the initial message is supplied to the workflow.

 

 


To populate the Data Field Path used to Sub-Divide Transactions field, you must run the workflow once to generate a message.

 

This message should be saved as a sample if you need to split the data into multiple messages.   

How to Save a Message as a Sample 

To save a message as a sample:

  • Go to the Workflow Messages page (marker 1 below)
  • Use the Advanced Options “…” menu (marker 2)
  • “View Message Details" (marker 3)

  

 

  • Select the desired message (with the format of “Message”, not “Raw” or “Trigger”)
  • Press the “…” button (marker 2 above) to open the advanced options menu
  • Select "View Message Details" (marker 3 above) to see the screenshot below

 

 

 

On the message details window (above):

  • Click on the drop-down “Details to Display”
  • Select Message Data (marker 1 below)

 

This will display the data. 

 

 

A new button called ‘Save to Samples’ (marker 1 below) will display at the top right, allowing you to save the message as a sample. 

 

 

Click the ‘+’ sign next to the data field path on the workflow trigger format settings:

 

 

 

You'll see this workflow trigger data field path configuration:

 

 

 

Select ‘Sample File’ and choose the sample file you just saved. 

 

 

 

  • Scroll down to the "Select Data Path" screen.
  • If you have a collection of data, select the path to the collection.
  • Select "Apply" to populate the field “Data Path….” to split the raw format message into multiple main messages. (see images below)

 

  

 

 

 

After you set the data field path, future messages will be split apart based on the configured path.  

 

Adding Data Source Filters 

The user can apply filters and settings to each data source.

 

When the trigger is fired, the results will be filtered to generate a message batch or a list of individual messages. 

 

Filters for some connectors have basic and advanced settings. Basic settings are generally required; advanced settings have defaults or are optional.

 

Other connectors group all settings together.

 

Where possible, tool tips and hints are provided next to each filter.  

 

 

Some filters are date-based and can use specific values to filter dates.

 

For example, to include objects created or updated within certain time frames, manually input values into the “Created After”, “Created Before”, “Updated After”, or “Updated Before” fields.

 

Valid filters include {StartOfPreviousMonth}, {EndOfPreviousMonth}, {Today+n}, {Today-n} (where "n" is a number).

 

 

 

Parameters 

Parameters define values that are extracted directly from the triggered data. This extraction happens automatically and will save steps in the workflow.

 

Parameters can be used the same way as variables within the workflow. Configuring parameters instead of variables allows validation rules to be applied before running the workflow. Parameters are also a way to define the expected data format if the workflow is being used to support Saltbox API Gateway functionality.  

 

Define which parameters will be available to the workflow based on the incoming data.

  • Using a message sample, determine the data path you wish to extract.
  • Press the add button (+) to add a new parameter.
  • Configure all fields in the "Add a Parameter" form: 

    • Name: Can be referenced in the workflow the same way as a variable.  

    • Source:  

  • Embedded Parameters Node – Select this option if you're using an event-based data type formatted in a specific manner. (Sample code is provided on help.saltbox.io.)  

  • A Specified Path within the Data – Select this option to select a data path based on a sample message. This will allow the trigger to extract the parameter from the specified message data path.  

  • Data Type: Specify this data type to ensure that extracted data is in the expected format. If you don't know or don't need to validate the format, select “String”.  

  • Allow parameter to be missing, empty or null: If checked, the extracted data is valid even if this parameter is missing from the data (there but empty or there but null).  

  • Default Value: When “Allow parameter to be missing, empty or null” is checked, this value will define a default for this parameter. If blank, the parameter will be created and will itself be blank.  

  • Error Message when Missing, Empty or Null: When “Allow parameter to be missing, empty or null” is unchecked, this provides an error message that will be displayed on the workflow messages page if the specified parameter cannot be extracted.  

  • Validation Rule (Regex): This validation rule applies the provided regular expressions (Regex) to the parameter data to ensure it meets the specified criteria.  

  • Failed Validation Error Message: If the "Validation Rule (Regex)" is specified and the extracted parameter data fails validation, this message will be displayed as an error on the workflow messages page. 

 

Schedule Settings 

Scheduling a workflow enables it to run automatically.

 

Until the workflow is complete, the schedule should be set to "Manual" so the user can initiate all workflow trigger executions.

 

When a schedule is ready to be defined, the image below depicts the available options: 

 

 

 

Make sure you save your changes, or they won't take effect.  

 

Save all changes by clicking the Save icon located in the upper-right of the blue header bar (marker 1 below): 

 

 

 

If you don't save your changes, a warning message will appear. Select Cancel and save your changes before proceeding. 

 

 

 

Congratulations! Your trigger is configured, and you can run the workflow to generate messages from the trigger. 

 

 

 

Previous

Next

  

Last modified: 03/25/2025/12:52 pm

On this page

-