Action Reference for Saltbox Core Connector

Actions are used by a workflow to to download, upload, inspect or manipulate data from a system.

Refer to the table below for action details.

Action Name	Description	Version
Add an Item to a List	Add the selected input message as a new list item in the indicated list message. The message will be added to the end of the list.	11.13+
Add Content to a Message	Add information to the specified message. Content is injected into a section called AdditionalInfo by default, or a specified section. This action was renamed in version 11.13.0. Older versions still use the action name Add Content To Message.	10.1+
AppendMessage	DEPRECATED. Append the output message to the RelatedInformation section of the selected input message and overwrite the output message with the result.	10.0+
Assert	DEPRECATED. Assert that one or more conditions are true.	10.0+
Convert a Message into Another Format	Convert the selected message data from one format into another.	11.14+
Convert an Array to an Object	Convert an array of name & value pairs to an object. This action was renamed in version 11.13.0. Older versions still use the action name Convert Array to Object.	10.1+
Create a List	Create an empty message that will support other List object actions.	11.13+
Create a Raw Message	Create a new message which contains a raw message section.	11.13+
Create a Variable	Create a variable whose data does not originate from a message. ex: a counter.	11.13+
Delay the Workflow	Without ending the workflow, delay the next workflow step by the specified time.	11.13+
Delay the Workflow Conditionally	Without ending the workflow, delay the next workflow step by the specified time, but only if supplied conditions are met.	11.13+
End the Workflow	Successfully end a workflow early. This action was renamed in version 11.13.0. Older versions still use the action name End Workflow.	11.4+
End the Workflow Conditionally	If the specified conditions are met, successfully end a workflow early. This action was renamed in version 11.13.0. Older versions still use the action name End Workflow Conditionally.	11.4+
Evaluate	Apply an evaluation to a given array	11.1+
Extract a Variable from a Message	Use XPath to extract a variable from a message. This variable may be used in subsequent workflow steps. This action was renamed in version 11.13.0. Older versions still use the action name Extract Variable from Message.	10.0+
Extract Content From a Message	Extract data from the input message at the specified section. This action was renamed in version 11.13.0. Older versions still use the action name Extract Content From Message.	10.1+
Fail the Workflow	Fail the workflow immediately and skip retries. This action was renamed in version 11.13.0. Older versions still use the action name Fail Workflow.	11.4+
Fail the Workflow Conditionally	Fail the workflow only if specified conditions are met, and skip retries. This action was renamed in version 11.13.0. Older versions still use the action name Fail Workflow Conditionally.	11.4+
Format DateTime	Format the provided date, as defined in configuration.	11.0+
Generate a CSV Message	Convert the provided input message from XML to CVS format. The Output message XML contains CSV data in the node ‘/rawContent’. This action was renamed in version 11.13.0. Older versions still use the action name GenerateCSV.	10.0+
Generate an Empty Message	Generate an empty XML or JSON message with a specified root node. This action was renamed in version 11.13.0. Older versions still use the action name Generate Empty Message.	11.6+
Generate Fixed Width Flat File Contents	Generate a message whose contents are a fixed-width flat file, encoded in a base64 string. The contents of this message may be uploaded to SFTP/FTP, or handled as an attachment.	11.16+
Get a List's Item Count	Get a count of how many messages are contained in the list.	11.13+
Get the Current DateTime	Get the current date/time as provided by the Saltbox project host. This action was renamed in version 11.13.0. Older versions still use the action name Get Current DateTime.	10.1+
Group and Process Message Contents	Use the input message to group related data and process each group’s contents.	11.3+
Group Message Contents	Use the input message to group related data.	11.23+
Modify a Variable (RegEx)	Apply a RegEx (regular expression) to the input string to extract the matching value. This action was renamed in version 11.13.0. Older versions still use the action name ModifyVariable (RegEx).	10.0+
Parse a Delimited String	Parse a delimited string and return output as XML, Json or CSV. This action was renamed in version 11.13.0. Older versions still use the action name Parse Delimited String.	10.0+
Pause the Workflow Conditionally	DEPRECATED. Conditionally end the workflow and allow it to be retried at a later time. Conditions are exclusionary (inverse of other conditional actions).	11.5+
Placeholder	This action does not perform any work. It is a placeholder only.	10.1+
Replace a String in a Message	Find and replace a string within the selected message. This action may be used to replace XML nodes.	11.10+
Retry the Workflow	End the workflow and allow it to be retried at a later time. This action was renamed in version 11.13.0. Older versions still use the action name Pause Workflow. “Retry” more accurately reflects the behavior of this action than “Pause”.	11.5+
Retry the Workflow Conditionally	Conditionally end the workflow and allow it to be retried at a later time. This action replaces the deprecated action Pause the Workflow Conditionally.	11.14.1+
Route a Message	Route the configured In Message to another workflow. Continue through the workflow. This action was renamed in version 11.13.0. Older versions still use the action name Route Message.	10.0+
Route a Message Synchronously	Route the configured In Message to another workflow, and wait for a response before proceeding through this workflow. This action was renamed in version 11.13.0. Older versions still use the action name Route Message Synchronously.	11.7+
Skip the Workflow	End the workflow with the skipped status.	11.17+
Skip the Workflow Conditionally	End the workflow with the skipped status, but only when specified conditions are met.	11.17+
Test that an XPath Exists	Inspect the indicated XPath. If it exists, the result will be true. If an exception occurs or the XPath doesn’t exist, the result will be false.	11.9+
Transform a Message	Apply a transform map to the selected input message. Enable Apply Map to configure transform details. Enable Save Action Output to Workflow Messages to configure output details. This action was renamed in version 11.13.0. Older versions still use the action name Transform.	10.0+
Update a Variable	Update the specified variable with data extracted from the input message.	11.13+
Wait	DEPRECATED. Stop the workflow execution (with or without an exception, as configured) and re-queue the message for re-try.	11.1+

Action Names

Add an Item to a List

Action Name	Description	Version
Add an Item to a List	Add the selected input message as a new list item in the indicated list message. The message will be added to the end of the list.	11.13+

Use this action to add items to an existing list.

Configuration

To add an item to a list:

• Select the list that will be added to using the Input Message to Use field (marker 1 above). If a message has not yet been created, add the Create a List action prior to this action and select that action’s output as the input for this message.

• Enable the option Save Action Output to Workflow Messages (marker 2 above).

• Select the list that will be saved using the Message to Write To field (marker 3 above). In most cases this will be the same as the Input Message.

• Configure the Data to Append to List (marker 4 above). This may be variable data or a defined string.

Once the workflow executes, after items have been added to the list, the resulting message will be in a structure below:

<?xml version="1.0" encoding="utf-8"?>
<ListMessagesSummary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ListMessages>
    <ListMessage>
      <Message>OEM1432</Message>
    </ListMessage>
    <ListMessage>
      <Message>PRG9044</Message>
    </ListMessage>
    <ListMessage>
      <Message>LFG0849</Message>
    </ListMessage>
    <ListMessage>
      <Message>ARM5086</Message>
    </ListMessage>
    <ListMessage>
      <Message>STS4121</Message>
    </ListMessage>
  </ListMessages>
</ListMessagesSummary>

Add Content to a Message

Action Name	Description	Version
Add Content to a Message	Add information to the specified message. Content is injected into a section called AdditionalInfo by default, or a specified section. This action was renamed in version 11.13.0. Older versions still use the action name Add Content To Message.	10.1+

Add content to a message, at a specified location within that message. Configuration options allow for replacing or appending data.

Configuration

This action requires both Input and Output messages. This action handles input/output messages differently from other actions, in that both are processed by the action itself.

• The specified input message (Input Message to Use) is used to supply this action with data.

  If Apply Map option is enabled, the specified input message will first be transformed as specified in the map.

  Data to include is defined through advanced options (outlined below).

• The specified output message (Message to Write To) is the target of this action, i.e. this is where content is added.

  Configuration options are outlined below.

• Data to Extract from Input Message section options can be configured as follows.

  • XPath to Extract Data defines the XPath in the input message to the data that will be captured.

  • XPath Action While Extracting specifies how the data is extracted from the input message.

    In versions 11.11 and lower, this setting was labeled XPath Action.

  • Action Result When XPath Not Found may be configured to handle empty data (“Use an Empty String” option) or fail the action (“Raise an Exception”).

  • Include parent node in extracted data set - when disabled, only the contents of the specified XPath will be extracted. This option is only available in versions 11.13 and higher.

• Data to Add to Output Message section options can be configured as follows.

  • Child Section Name specifies the node name that will wrap around added content. If blank, the default node name ChildInfo will be used.

    In versions 11.11 and lower, this setting was labeled Section Name.

  • XPath to Add Data is an optional setting that specifies a specific XPath where data will be added into the selected output message.

    This option was added in version 11.13 and is not found in earlier versions. In earlier versions the data is always added to the default node AdditionalInfo.

  • Action when Adding New Content options are as follows. In versions 11.11 and lower, this setting was labeled Add Content Action.

    • Append New Content as a Child - Data will be added to the specified XPath to Add Data / Child Section Name as a child node.

    • Append New Content as a Sibling - Data will be added to the specified XPath to Add Data / Child Section Name as a sibling node.

    • Replace Content - If the XPath to Add Data / Child Section Name node already exists, its contents will be overwritten.

    • Add Content as a Single Instance - If the XPath to Add Data / Child Section Name node already exists, this action will fail.

    • Wrap data in CDATA tag - If enabled, this option will wrap content of the extracted section in a CDATA tag. This supports advanced processing of sections which themselves contain data.

AppendMessage

Action Name	Description	Version
AppendMessage	DEPRECATED. Append the output message to the RelatedInformation section of the selected input message and overwrite the output message with the result.	10.0+

This action is deprecated. Instead, use the action Add Content to a Message, which provides more flexible configuration options for adding content to an existing message.

Assert

Action Name	Description	Version
Assert	DEPRECATED. Assert that one or more conditions are true.	10.0+

This action is deprecated. Instead, use one of the following flow control actions to assert and execute behavior based on that assertion.

• Delay the Workflow Conditionally - when the condition is met, wait the specified duration before proceeding to the next action.
• End the Workflow Conditionally - when the condition is met, end the workflow successfully.
• Fail the Workflow Conditionally - when the condition is met, fail the workflow, bypassing any retries.
• Retry the Workflow Conditionally - when the condition is met, fail the workflow and allow it to be retried if retries are enabled.

Alternatively, assertions may be made directly in branch conditions, such as the If or If/Else branch types.

Convert a Message into Another Format

Action Name	Description	Version
Convert a Message into Another Format	Convert the selected message data from one format into another.	11.14+

The Input Message to Use setting indicates which message will be transformed. A copy of this message will be transformed, then saved to a new message using the option Save Action Output to Workflow Messages. See a walkthrough of this setting for more details.

Convert an Array to an Object

Action Name	Description	Version
Convert an Array to an Object	Convert an array of name & value pairs to an object. This action was renamed in version 11.13.0. Older versions still use the action name Convert Array to Object.	10.1+

Create a List

Action Name	Description	Version
Create a List	Create an empty message that will support other List object actions.	11.13+

Create a Raw Message

Action Name	Description	Version
Create a Raw Message	Create a new message which contains a raw message section.	11.13+

Configuration

Enable the option Save Action Output to Workflow Messages. This will generate a “blank” raw message. That is, the message will be generated in the proper structure to handle raw data, but will not contain any raw data.

<?xml version="1.0" encoding="utf-8"?>
<RawMessageWrapper xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <rawContent><![CDATA[]]></rawContent>
</RawMessageWrapper>

Once this message is created, another action in the workflow may populate this message’s rawContent section with raw data:

• Add Content to a Message action may be used to supply the rawContent section with XML raw data.

• Transform a Message action may be used to populate the CDATA block with data using the calculated field or function mapping types. This action may also be used to map source data from another action’s data, such as an attachment action.

  

Create a Variable

Action Name	Description	Version
Create a Variable	Create a variable whose data does not originate from a message. ex: a counter.	11.13+

Delay the Workflow

Action Name	Description	Version
Delay the Workflow	Without ending the workflow, delay the next workflow step by the specified time.	11.13+

Use this action to delay the workflow before proceeding to the next action. This action will keep the workflow active while it’s being delayed.

Configuration

• Delay (in milliseconds) (marker 1 above) specifies how long the workflow will wait before proceeding to the next action.

Best practices

• Avoid large delays. Instead, consider using the “Route a Message” action to forward data to another workflow.

• If using this action in a “for each” iterator branch, consider the size of your data set before using this action. For example, a 1-second delay on a thousand records will result in a half-hour workflow execution time. Instead consider using the “Route a Message” action to forward data to another workflow, thus ensuring that one workflow execution doesn’t block available engine threads.

Delay the Workflow Conditionally

Action Name	Description	Version
Delay the Workflow Conditionally	Without ending the workflow, delay the next workflow step by the specified time, but only if supplied conditions are met.	11.13+

Use this action to delay the workflow before proceeding to the next action, but only if the specified conditions are met. This action will keep the workflow active while it’s being delayed.

Configuration

For each condition that will be assessed, configure the Actual Value, Condition, and if comparing two values, the Expected Value.

• Actual Value (marker 1 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Condition (marker 2 above) may compare two values or inspect the Actual Value only.

• Expected Value (marker 3 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Log Comments (marker 4 above) are added to the workflow execution log when the condition is met.

• Add Conditions (marker 5 above) may be used to add more than one condition. At least one condition is required.

• Condition Operation (marker 6 above) specifies whether to match any condition (logical “or”) or all conditions (logical “and”).

• Delay (in milliseconds) (marker 7 above) specifies how long the workflow will wait before proceeding to the next action.

Best practices

• Avoid large delays. Instead, consider using the “Route a Message” action to forward data to another workflow.

• If using this action in a “for each” iterator branch, consider the size of your data set before using this action. For example, a 1-second delay on a thousand records will result in a half-hour workflow execution time. Instead consider using the “Route a Message” action to forward data to another workflow, thus ensuring that one workflow execution doesn’t block available engine threads.

End the Workflow

Action Name	Description	Version
End the Workflow	Successfully end a workflow early. This action was renamed in version 11.13.0. Older versions still use the action name End Workflow.	11.4+

Use this action to end a workflow early. This action is not required during normal workflow execution, and is instead a way to successfully end a workflow without performing any further actions.

For example, this action may be useful at the end of an if/else branch whose other execution path has further actions to perform.

Configuration

• Log Comments (marker 1 above) are added to the workflow execution log when this action is executed.

End the Workflow Conditionally

Action Name	Description	Version
End the Workflow Conditionally	If the specified conditions are met, successfully end a workflow early. This action was renamed in version 11.13.0. Older versions still use the action name End Workflow Conditionally.	11.4+

Use this action to end a workflow early, but only when specified conditions are met. This action is not required during normal workflow execution, and is instead a way to successfully end a workflow without performing any further actions.

For example, this action may be useful at the end of an if/else branch whose other execution path has further actions to perform.

Configuration

For each condition that will be assessed, configure the Actual Value, Condition, and if comparing two values, the Expected Value.

• Actual Value (marker 1 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Condition (marker 2 above) may compare two values or inspect the Actual Value only.

• Expected Value (marker 3 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Log Comments (marker 4 above) are added to the workflow execution log when the condition is met.

• Add Conditions (marker 5 above) may be used to add more than one condition. At least one condition is required.

• Condition Operation (marker 6 above) specifies whether to match any condition (logical “or”) or all conditions (logical “and”).

Evaluate

Action Name	Description	Version
Evaluate	Apply an evaluation to a given array	11.1+

Use this action to apply mathematical evaluations of the specified XPath data.

Configuration

1. Select the Input Message To Use supplies this action with the data that will be evaluated.

2. XPath specifies the XPath to the data that will be evaluated, using the Input Message. Typically, this data is an array or collection of data (e.g. Document Lines)

3. Evaluation Action determines how the data will be evaluated.

   The following operations may be applied:

   • Sum
   • Average (AVG)
   • Minimum (MIN)
   • Maximum (MAX)
   • Count

   For all but the Count operation, evaluated data is expected to be numeric; data elements which are not numeric are ignored.

   For the Count operation, data elements of any type (numeric or non-numeric) are counted.

4. Allow data to be missing. This option is supported in versions 11.14.2 and higher.

   When enabled: If the specified XPath is missing, the specified Default when missing will be used instead.

   When disabled: An exception will be generated if the specified XPath does not exist.

5. Default when missing will only be applied when the specified XPath is not included in the Input Message. This option is supported in versions 11.14.2 and higher.

6. Allow Data to be empty or null. This option is supported in versions 11.14.2 and higher.

   When enabled: If the specified XPath contains empty/null data, the specified default will be used instead.

   When disabled: An exception will be generated and the workflow will fail if the specified XPath is empty (e.g. <emptyDataItem></emptyDataItem>) or null (e.g. <nullDataItem />).

7. Default when empty or null will only be applied in place of data elements which are empty or null. This option is supported in versions 11.14.2 and higher.

8. Count Empty and null data (not shown above). This option only applies to the “Count” Evaluation Action. This option is supported in versions 11.14.2 and higher.

   When enabled: All instances of the specified XPath will be counted, even if the instance is empty or null.

   When disabled: Only instances of the specified XPath which contain data will be counted. Non-numeric data will be counted.

Extract a Variable from a Message

Action Name	Description	Version
Extract a Variable from a Message	Use XPath to extract a variable from a message. This variable may be used in subsequent workflow steps. This action was renamed in version 11.13.0. Older versions still use the action name Extract Variable from Message.	10.0+

This action creates a variable whose value is extracted from a message. Use XPath to define which data to extract. Data must be a terminating node, as opposed to data with child elements.

In the sample data below two valid XPaths that can be extracted are //course/reg_num and /course/subj. An example that yields an invalid result is /course/time as there are child elements within time.

<course>
  <reg_num>20557</reg_num>
  <subj>CHEM</subj>
  <crse>212</crse>
  <sect>S</sect>
  <title>Intro Inorganic Chemistry</title>
  <units>1.0</units>
  <instructor>Geselbracht</instructor>
  <days>M-W-F</days>
  <time>
    <start_time>11:00AM</start_time>
    <end_time>11:50</end_time>
  </time>
  <place>
    <building>CHEM</building>
    <room>301</room>
  </place>
</course>

Configuration

• Select the desired message (1). See Select the Input Message to Use for details.

• Set the desired XPath (2). The format of the actions’ input message can be determined by running the workflow and using message trace to inspect the action’s InMessage.xml data.

Usage

Once the AddOutPutVariable action has been added to the workflow, subsequent actions and visual data mappings can consume the variable’s value.

• When editing an action, use the plus button next to most text fields to add a variable.

  

• In the “Actions” section, select the Action ID for your variable. In the screenshot below, this is Action_extractVar1

  

  

• Press the Insert button to add the variable to the field (with proper syntax for that field). Some XPath fields exclude the wrapping double-pipe syntax, so in some cases the XPath will be added as raw string instead of a formatted variable. This is done automatically depending on the action’s requirements.

  

Extract Content From a Message

Action Name	Description	Version
Extract Content From a Message	Extract data from the input message at the specified section. This action was renamed in version 11.13.0. Older versions still use the action name Extract Content From Message.	10.1+

Fail the Workflow

Action Name	Description	Version
Fail the Workflow	Fail the workflow immediately and skip retries. This action was renamed in version 11.13.0. Older versions still use the action name Fail Workflow.	11.4+

Use this action to fail a workflow at a specific point. Retry logic (if enabled) will not be applied.

For example, this action may be useful at the end of an if/else branch.

Configuration

• Log Comments (marker 1 above) are added to the workflow execution log when this action is executed.

Fail the Workflow Conditionally

Action Name	Description	Version
Fail the Workflow Conditionally	Fail the workflow only if specified conditions are met, and skip retries. This action was renamed in version 11.13.0. Older versions still use the action name Fail Workflow Conditionally.	11.4+

Use this action to fail a workflow at a specific point, but only when specified conditions are met. Retry logic (if enabled) will not be applied.

For example, this action may be useful if following actions depend on certain data (or other conditions).

Configuration

For each condition that will be assessed, configure the Actual Value, Condition, and if comparing two values, the Expected Value.

• Actual Value (marker 1 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Condition (marker 2 above) may compare two values or inspect the Actual Value only.

• Expected Value (marker 3 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Log Comments (marker 4 above) are added to the workflow execution log when the condition is met.

• Add Conditions (marker 5 above) may be used to add more than one condition. At least one condition is required.

• Condition Operation (marker 6 above) specifies whether to match any condition (logical “or”) or all conditions (logical “and”).

Format DateTime

Action Name	Description	Version
Format DateTime	Format the provided date, as defined in configuration.	11.0+

Create a variable or output message in the target date/time format.

Configuration

When formatting a date, datetime or time string, the following settings and defaults are used:

• DateTime - (required) This value may be supplied by a variable or XPath (extracted from the action’s input message), or a string. See marker 3 above.
• Source Format - (required) This string defines the structure of the source DateTime. See format options below. See marker 4 above.
• Source Culture - This is an optional setting. If not supplied, this value uses the “Culture Invariant” option. See marker 5 above.
• Target DateTime Format - (required) This string defines how the end result will be formatted. See format options below. See marker 6 above.
• Target DateTime Culture - This is an optional setting. If not supplied, this value uses the “Culture Invariant” option. See marker 7 above.

The output of this action is available as an action variable. If configured, this value may also be saved to the action’s output message (markers 1 and 2 above).

Format Options

In general, format options follow the Microsoft date standards defined here: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings

Format strings in Saltbox functions don’t require quotes. Single-character formats (such as s sortable, M month-day pattern, etc.) are supported, as well as long formats (such as yyyy-MM-dd or MM/dd/yyyy).

Some common examples include:

• s - Sortable date (used by Shopify). For example: 2009-06-15T13:45:30
• yyyyMMdd - year, month, day with no spaces (used by SAP Business One). For example: 20200224
• F - Full (long) date/time pattern. For example: 2009-06-15T13:45:30 -> Monday, June 15, 2009 1:45:30 PM

Shown below, a DateTime (2009-06-15T13:45:30) is given to the function in the short format (Source DateTime Format = s) will be formatted into yyyyMMdd format (Target DateTime Format = yyyyMMdd):

Using the same formatting, the date can be supplied from a source data field. Shown below, the source field $created_at is mapped from the source to the target, then dragged to the field from the top into the DateTime parameter.

Culture Options

Culture may be specified by providing a locale short code, such as en-US, en-GB, fr-FR, etc. If not provided, or if the provided culture can’t be resolved, “Culture Invariant” will be used instead.

Generate a CSV Message

Action Name	Description	Version
Generate a CSV Message	Convert the provided input message from XML to CVS format. The Output message XML contains CSV data in the node ‘/rawContent’. This action was renamed in version 11.13.0. Older versions still use the action name GenerateCSV.	10.0+

Generate an Empty Message

Action Name	Description	Version
Generate an Empty Message	Generate an empty XML or JSON message with a specified root node. This action was renamed in version 11.13.0. Older versions still use the action name Generate Empty Message.	11.6+

Create an empty message, which may be appended to in future actions. Set the root node name through configuration.

Configuration

• Enable the option “Save Action Output to Workflow Message” (marker 1 above).

• Add or select a “Message to Write To” (marker 2 above).

  Note: If an existing message is selected, the message’s contents will be replaced with this new empty message.

• Define the “Root Node Name” (marker 3 above), which will set the root node.

• Set the “output response type” to JSON or XML (by default XML). See marker 4 above.

Troubleshooting

• If the workflow generates no message, ensure the option Save Action Output to Workflow Message is configured.

Generate Fixed Width Flat File Contents

Action Name	Description	Version
Generate Fixed Width Flat File Contents	Generate a message whose contents are a fixed-width flat file, encoded in a base64 string. The contents of this message may be uploaded to SFTP/FTP, or handled as an attachment.	11.16+

Get a List’s Item Count

Action Name	Description	Version
Get a List's Item Count	Get a count of how many messages are contained in the list.	11.13+

Get the Current DateTime

Action Name	Description	Version
Get the Current DateTime	Get the current date/time as provided by the Saltbox project host. This action was renamed in version 11.13.0. Older versions still use the action name Get Current DateTime.	10.1+

Create a variable or output message with the current date/time.

Date/time values are provided by the Cloud Container in UTC or by the Application Server which hosts the Saltbox project. In the case of an Application Server host, the time zone is as configured on the server. Values can be standardized to UTC by setting TimezoneOffset to +0.

Configuration

When formatting a date, datetime or time string, the following settings and defaults are used:

• Format - This is an optional setting. This string defines the structure of the source DateTime. See format options [in the “Format DateTime” action description above]. See marker 2 above.
• Culture - This is an optional setting. If not supplied, this value uses the “Culture Invariant” option. See marker 3 above.

• TimezoneOffset - This is an optional setting. Specify a time zone offset relative to Coordinated Universal Time (UTC). See marker 4 above.

  When using a Cloud Container to host this Saltbox project, default values are in UTC. Use Convert DateTime to Given Offset to display in a different time zone, as specified by this TimezoneOffset.

  When using an Application Server to host this Saltbox project, default values depend on the host server. Set this TimezoneOffset to +0 to standardize to UTC, or omit this setting to use the time zone specified by the server.

  • Examples include:

    • +0 - UTC

    • -3 - EDT

    • -8 - PT

    • -2:30 - NDT

• Convert DateTime to Given Offset - When checked, this option will apply the provided time zone offset to all variables. When disabled, the provided TimezoneOffset will be applied to only the CustomDateTime variable.

Usage

The output of this action is available in several formats:

• As an action variable:

  • 

  • CustomDateTime applies the provided format to the generated date/time. Using the short code o, a time zone offset of 2:30 would be displayed as: 2021-04-08T06:50:06.2046513-02:30

    This variable is shown above in context as ||VAR:Action_GetDateTime.CustomDateTime||, or more generally ||VAR:Action_ID.CustomDateTime|| where Action_ID is defined in the workflow.

  • Other date/time variables are listed below. Examples use the following date/time as a point of reference: 2021-04-08T09:02:47

    • Date - ex: 04/08/2021
    • FullDate - ex: Thursday, 08 April 2021
    • FullDateTime - ex: Thursday, 08 April 2021 09:02:47
    • FullTime - ex: 09:02:47
    • ShortDateTime - ex: 04/08/2021 09:02
    • SortableDateTime - ex: 2021-04-08T09:02:47
    • Time - ex: 09:02

• If configured, this value may also be saved to the action’s output message, which can be used as an input message for other actions.

Culture Options

Culture may be specified by providing a locale short code, such as en-US, en-GB, fr-FR, etc. If not provided, or if the provided culture can’t be resolved, “Culture Invariant” will be used instead.

Group and Process Message Contents

Action Name	Description	Version
Group and Process Message Contents	Use the input message to group related data and process each group’s contents.	11.3+

Group Message Contents

Action Name	Description	Version
Group Message Contents	Use the input message to group related data.	11.23+

Modify a Variable (RegEx)

Action Name	Description	Version
Modify a Variable (RegEx)	Apply a RegEx (regular expression) to the input string to extract the matching value. This action was renamed in version 11.13.0. Older versions still use the action name ModifyVariable (RegEx).	10.0+

Parse a Delimited String

Action Name	Description	Version
Parse a Delimited String	Parse a delimited string and return output as XML, Json or CSV. This action was renamed in version 11.13.0. Older versions still use the action name Parse Delimited String.	10.0+

Parse the provided string into a collection of the specified type.

Configuration

• Save results to the action output message (markers 1 and 2 above). This will be saved as a collection that can be iterated through in ForEach loops. Use the action variable XPathSplitter to iterate over a collection using ForEach loops.

• Input String - this can be a string value (as shown) or may be provided by a project/workflow variable (for example, as a project-level configuration variable), or provided by other variables generated within the workflow.

• Delimiter - the characters used to split the data, for example CSV uses , (comma).

• Output Type - set the output type of the resulting data, for example, CSV, JSON or XML.

Usage

Results are available in the action’s output message. Metadata about the data is found in action variables Count and XPathSplitter.

Pause the Workflow Conditionally

Action Name	Description	Version
Pause the Workflow Conditionally	DEPRECATED. Conditionally end the workflow and allow it to be retried at a later time. Conditions are exclusionary (inverse of other conditional actions).	11.5+

Deprecation Warning: This action is deprecated due to inconsistency in how conditions are applied. Use the Retry the Workflow Conditionally action for improved functionality. Note that this action’s conditions are exclusionary. That is, conditions will be applied if they are not met. Retry the Workflow Conditionally correctly applies inclusive logic and should be used instead.

Use this action to end a workflow early, and flag the workflow for retry (as per configured workflow retry settings).

For example, this action may be useful if following actions depend on certain data (or other conditions), which would be available after a delay (for example, an order whose payment is pending approval, or an inventory update for an item which hasn’t been added to the system yet).

Configuration

For each condition that will be assessed, configure the Actual Value, Condition, and if comparing two values, the Expected Value.

• Actual Value (marker 1 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Condition (marker 2 above) may compare two values or inspect the Actual Value only. Note that conditions are exclusionary, conditions act as a filter to exclude data. For example, the action will end the workflow only if the conditions have not been met.

• Expected Value (marker 3 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Log Comments (marker 4 above) are added to the workflow execution log when the condition fails.

• Add Conditions (marker 5 above) may be used to add more than one condition. At least one condition is required.

• Condition Operation (marker 6 above) specifies whether to match any condition (logical “or”) or all conditions (logical “and”).

Requirement

Note: This action will only function if retries are enabled for the workflow. To confirm this setting is enabled:

• On the Workflow Settings page, expand the Message Processing Settings section.

• Scroll down to the option “Enable Retry settings for failed messages” and ensure this is checked.

• Set the “Max Retries” to a value greater than 0 (3 or 4 is typical, depending on the system).

• Set the “Retry Interval (minutes)” to a reasonable value. In some systems this can be as little as 1 minute, in other systems with high volume transactions it may make more sense to wait 5-10 minutes between retries.

Placeholder

Action Name	Description	Version
Placeholder	This action does not perform any work. It is a placeholder only.	10.1+

No configuration is necessary to use this action.

Add this action to empty branches or in place of unknown steps in a workflow.

No work is performed by this action, but when this action is executed in a workflow, a warning-level log entry will be added to the workflow message log. This action’s logging is suppressed when the workflow’s log level is set to Error.

Replace a String in a Message

Action Name	Description	Version
Replace a String in a Message	Find and replace a string within the selected message. This action may be used to replace XML nodes.	11.10+

String replacement can be used to modify data strings, or to modify XML/JSON. Use caution when using string replacement to overwrite XML nodes or JSON - this can result in corrupted data.

Common usage of this action to replace XML or JSON includes removing tags which contain certain data (using Regular Expressions - RegEx).

Alternatively, XML or JSON can be removed using Visual Data Mapper, including the advanced Calculated mapping type.

Configuring the action: Replace a String in a Message

This action includes the following options, with examples of different configurations and usage below. Regular Expressions are a topic of their own, and are explained in RegEx in Workflow Config.

General action config:

• Select the Input Message to Use - this is the source data that will be assessed for replacement, for ex: Current Message assesses the triggered workflow message.
• Save Action Output to Workflow Messages: Enabled/Checked
  • Message to Write Output To: Configure a new message where the results will be written/output.
• Suppress Error: If enabled, failures to replace matching string, or errors in the output message will be ignored, and will not be raised through workflow exception handlers.

Action-specific config:

• Search By:
  • Exact String: Strings which exactly match the specified value will be replaced.
  • Regex Pattern: Strings which match the Regular Expression pattern will be replaced. For more details about Regular Expressions, see RegEx in Workflow Config.
• Exact String: All matching occurrences of this string will be replaced.
• Rexex Option: Advanced options, like multi-line support, case insensitivity etc. are explained in RegEx in Workflow Config. This setting is only configurable when searching by Regex Pattern.
• Replacement String: This will overwrite/replace matching strings (whether by RexEx or exact string match).

Matching String Example - Obscure Sensitive Data

This example replaces a string with asterisks to obscure the details.

Configuration:

• Select the Input Message to Use: Current Message
• Save Action Output to Workflow Messages: Checked/Enabled
• Message to Write Output To: result
• Search By: Exact String
• Exact String: Proprietary Info
• Replacement String: ****

Starting data (Input Message):

<BOM>
    <BO>
        <AdmInfo>
            <Object>17</Object>
            <Version>2</Version>
        </AdmInfo>
        <Documents>
            <row>
                <DocDate>20190116</DocDate>
                <DocDueDate>20190116</DocDueDate>
                <CardCode>C20000</CardCode>
                <NumAtCard>Proprietary Info</NumAtCard>
                <U_Temp></U_Temp>
            </row>
        </Documents>
        <Document_Lines>
            <row>
                <LineNum>0</LineNum>
                <ItemCode>A00001</ItemCode>
                <ItemName>Acme Widget A1</ItemName>
                <Quantity>1.000000</Quantity>
                <Price>600.000000</Price>
            </row>
            <row>
                <LineNum>1</LineNum>
                <ItemCode>A00002</ItemCode>
                <ItemName>Acme Proprietary Info Item</ItemName>
                <Quantity>1.000000</Quantity>
                <Price>350.000000</Price>
            </row>
        </Document_Lines>
    </BO>
</BOM>

This will result in the output message below. Note that all instances of the matched string are replaced.

<BOM>
    <BO>
        <AdmInfo>
            <Object>17</Object>
            <Version>2</Version>
        </AdmInfo>
        <Documents>
            <row>
                <DocDate>20190116</DocDate>
                <DocDueDate>20190116</DocDueDate>
                <CardCode>C20000</CardCode>
                <NumAtCard>****</NumAtCard>
                <U_Temp></U_Temp>
            </row>
        </Documents>
        <Document_Lines>
            <row>
                <LineNum>0</LineNum>
                <ItemCode>A00001</ItemCode>
                <ItemName>Acme Widget A1</ItemName>
                <Quantity>1.000000</Quantity>
                <Price>600.000000</Price>
            </row>
            <row>
                <LineNum>1</LineNum>
                <ItemCode>A00002</ItemCode>
                <ItemName>Acme **** Item</ItemName>
                <Quantity>1.000000</Quantity>
                <Price>350.000000</Price>
            </row>
        </Document_Lines>
    </BO>
</BOM>

Matching ReEx Example - Remove Data Nodes Containing Dates

This example strips out data in a particular xml node which is a formatted date. For example, this may be used to filter out known “irrelevant data” from a collection which will be handed into another action.

Configuration:

• Select the Input Message to Use: Current Message
• Save Action Output to Workflow Messages: Checked/Enabled
• Message to Write Output To: ProcessedResults
• Search By: Regex Pattern
• Regex Pattern: <data_ext>[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}<\/data_ext> - see RegEx in Workflow Config for more info about Regular Expression in Saltbox.
• Rexex Option: None
• Replacement String: (empty) - This “replaces” all matching instances with nothing, effectively removing them.

Starting data (Input Message):

<supplimentary>
    <data_ext>2022-02-20</data_ext>
    <data_ext>Acme Express</data_ext>
    <data_ext>1999-11-29</data_ext>
    <data_ext>Proton Ltd.</data_ext>
</supplimentary>

This will result in the output message:

<supplimentary>
    <data_ext>Acme Express</data_ext>
    <data_ext>Proton Ltd.</data_ext>
</supplimentary>

Retry the Workflow

Action Name	Description	Version
Retry the Workflow	End the workflow and allow it to be retried at a later time. This action was renamed in version 11.13.0. Older versions still use the action name Pause Workflow. “Retry” more accurately reflects the behavior of this action than “Pause”.	11.5+

Use this action to end a workflow early, and flag the workflow for retry (as per configured workflow retry settings).

For example, this action may be useful at the end of an if/else branch where certain data has not been found.

Configuration

• Log Comments (marker 1 above) are added to the workflow execution log when this action is executed.

Requirement

Note: This action will only function if retries are enabled for the workflow. To confirm this setting is enabled:

• On the Workflow Settings page, expand the Message Processing Settings section.

• Scroll down to the option “Enable Retry settings for failed messages” and ensure this is checked.

• Set the “Max Retries” to a value greater than 0 (3 or 4 is typical, depending on the system).

• Set the “Retry Interval (minutes)” to a reasonable value. In some systems this can be as little as 1 minute, in other systems with high volume transactions it may make more sense to wait 5-10 minutes between retries.

Retry the Workflow Conditionally

Action Name	Description	Version
Retry the Workflow Conditionally	Conditionally end the workflow and allow it to be retried at a later time. This action replaces the deprecated action Pause the Workflow Conditionally.	11.14.1+

Use this action to end a workflow early, and flag the workflow for retry (as per configured workflow retry settings).

For example, this action may be useful if following actions depend on certain data (or other conditions), which would be available after a delay (for example, an order whose payment is pending approval, or an inventory update for an item which hasn’t been added to the system yet).

Note: This action replaces “Pause the Worfklow Conditionally” which has been deprecated.

Configuration

For each condition that will be assessed, configure the Actual Value, Condition, and if comparing two values, the Expected Value.

• Actual Value (marker 1 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Condition (marker 2 above) may compare two values or inspect the Actual Value only.

• Expected Value (marker 3 above) may be pulled from the input message (using XPath), from a variable, or a text value.

• Log Comments (marker 4 above) are added to the workflow execution log when the condition is met.

• Add Conditions (marker 5 above) may be used to add more than one condition. At least one condition is required.

• Condition Operation (marker 6 above) specifies whether to match any condition (logical “or”) or all conditions (logical “and”).

Requirement

Note: This action will only function if retries are enabled for the workflow. To confirm this setting is enabled:

• On the Workflow Settings page, expand the Message Processing Settings section.

• Scroll down to the option “Enable Retry settings for failed messages” and ensure this is checked.

• Set the “Max Retries” to a value greater than 0 (3 or 4 is typical, depending on the system).

• Set the “Retry Interval (minutes)” to a reasonable value. In some systems this can be as little as 1 minute, in other systems with high volume transactions it may make more sense to wait 5-10 minutes between retries.

Route a Message

Action Name	Description	Version
Route a Message	Route the configured In Message to another workflow. Continue through the workflow. This action was renamed in version 11.13.0. Older versions still use the action name Route Message.	10.0+

Trigger another event-based workflow using this action, and continue through this workflow. The routed message will be processed separately.

Route a Message Synchronously

Action Name	Description	Version
Route a Message Synchronously	Route the configured In Message to another workflow, and wait for a response before proceeding through this workflow. This action was renamed in version 11.13.0. Older versions still use the action name Route Message Synchronously.	11.7+

Trigger another event-based workflow using this action. This workflow will wait for a response before continuing.

Skip the Workflow

Action Name	Description	Version
Skip the Workflow	End the workflow with the skipped status.	11.17+

Skip the Workflow Conditionally

Action Name	Description	Version
Skip the Workflow Conditionally	End the workflow with the skipped status, but only when specified conditions are met.	11.17+

Test that an XPath Exists

Action Name	Description	Version
Test that an XPath Exists	Inspect the indicated XPath. If it exists, the result will be true. If an exception occurs or the XPath doesn’t exist, the result will be false.	11.9+

Transform a Message

Action Name	Description	Version
Transform a Message	Apply a transform map to the selected input message. Enable Apply Map to configure transform details. Enable Save Action Output to Workflow Messages to configure output details. This action was renamed in version 11.13.0. Older versions still use the action name Transform.	10.0+

Update a Variable

Action Name	Description	Version
Update a Variable	Update the specified variable with data extracted from the input message.	11.13+

Wait

Action Name	Description	Version
Wait	DEPRECATED. Stop the workflow execution (with or without an exception, as configured) and re-queue the message for re-try.	11.1+

Configuration Options

When configuring workflow actions, some configuration options can be added to multiple actions. Common options are detailed below.

Set Retry Save Point

When enabled, Set Retry Save Point allows a workflow to retry from a save point instead of retrying from the beginning. A retry save point is only used if the action was successful.

For example, if the workflow below is executed but fails on action E, the workflow will retry from action B - the last successful retry save point. This is because although action E is marked as a retry save point, it was not successfully completed, so is not counted as a retry point.

Select the Input Message to Use

This option indicates which message will be used by the action.

• All Messages selects all message data that has been fetched during this workflow execution. The format of this message wraps around other data.

  Basic format:

  <WFMessage>
    <Current>
      <!-- Triggered data, plus any modifications -->
    </Current>
    <RelatedMessages>
      <!-- Messages generated by workflow actions and mappings, grouped by output message name -->
    </RelatedMessages>
  </WFMessage>
  

  For example:

  <WFMessage>
    <Current>
      <course>
        <reg_num>20557</reg_num>
        <subj>CHEM</subj>
        <crse>212</crse>
        <sect>S</sect>
        <title>Intro Inorganic Chemistry</title>
        <units>1.0</units>
        <instructor>Geselbracht</instructor>
        <days>M-W-F</days>
        <time>
          <start_time>11:00AM</start_time>
          <end_time>11:50</end_time>
        </time>
        <place>
          <building>CHEM</building>
          <room>301</room>
        </place>
      </course>
    </Current>
    <RelatedMessages>
      <AddContentOutput>
        <custom_data>
          <AdditionalInfo>
            <reg_num>20557</reg_num>
          </AdditionalInfo>
        </custom_data>
      </AddContentOutput>
    </RelatedMessages>
  </WFMessage>
  

  XPath to “Current Message” content includes the prefix /WFMessage/Current (for example /WFMessage/Current/course/reg_num).

• Current Iteration selects this iteration of a for-each loop. This option is only enabled within loops.

• Current Message indicates the workflow’s triggered message, including any changes to that data (for example, appended content). XPaths depend on the data contained within the message, for example /course/reg_num.

  In the above example, Current Message would contain the following data:

  <course>
    <reg_num>20557</reg_num>
    <subj>CHEM</subj>
    <crse>212</crse>
    <sect>S</sect>
    <title>Intro Inorganic Chemistry</title>
    <units>1.0</units>
    <instructor>Geselbracht</instructor>
    <days>M-W-F</days>
    <time>
      <start_time>11:00AM</start_time>
      <end_time>11:50</end_time>
    </time>
    <place>
      <building>CHEM</building>
      <room>301</room>
    </place>
  </course>
  

• Named messages may also be selected. These are generated by other workflow actions.

  In the above example, the named message AddContentOutput would contain the following data:

  <custom_data>
    <AdditionalInfo>
      <reg_num>20557</reg_num>
    </AdditionalInfo>
  </custom_data>
  

Apply Map

If enabled, the input message will be mapped or transformed, as per advanced options (outlined below).

Select the Type of Map

This option is only available if Apply Map has been enabled.

• Map - choose this option to map data from one format to another. For example, to map order, customer or inventory data between two different systems. Advanced configuration of the map is applied using Visual Data Mapper. See Visual Data Mapper Overview for walkthroughs and tutorials.

• XSLT - choose this option if an XSLT file will be used to format the action’s message data. For best results, use this option to generate HTML content.

Select the Map to Use

This option is only available if Apply Map has been enabled.

Map Output

This option is only available if Apply Map has been enabled.

This option is used to help interact with mapping results within Saltbox. Each connector communicates with its supported vendor in that vendor’s natively supported language. The results of the mapping (regardless of format) are translated into the format required by each vendor.

Save Action Output to Workflow Messages

This option saves the output of an action (such as data mapping results) as part of the workflow execution. This is useful when an action’s mapping data is required further in the workflow. This option also aids in troubleshooting, provided data retention settings allow it.

Note that some actions don’t support saving an output message, such as when no message data is handled.

Select the Message to Write To

This option is only available if Save Action Output to Workflow Messages has been enabled.

This dictates where message data is saved. Most actions overwrite the selected message, so in most cases, a new output message is used. However, some actions augment the selected message (such as the Saltbox Core Connector action Add Content to Message).

Add Comment

Use this option to add context or help other users maintain this workflow. Inclusion of a comment has no impact on workflow execution.

When supplied, comments are displayed in both workflow designer and message trace.

Display Customized Error Message upon Failure

When enabled, a customized error message is displayed when a workflow fails at this action. Optionally append the original error message. This option can be used to provide likely causes of issues, such as recurring issues or pointers to personalized troubleshooting reminders.

RegEx in Workflow Config

Regular Expressions (RegEx) are supported by some actions (where identified) and are used to select substrings within a provided message or string.

Thorough testing of RegEx pattern matching is strongly recommended. RegEx is highly flexible, but it is also notorious for being easy to trip over.

Notes about configuring RegEx in Saltbox:

• patterns exclude “wrappers” like /.../g

  • ex: the following RegEx selects date-like strings: [0-9]{4}-[0-9]{1,2}-[0-9]{1,2}

  • ex: the following RegEx matches any 6-digit numbers: [0-9]{6}

• Replacement RegEx is not generally supported. Instead actions use secondary settings to enable replacement.

  • For example, the action Replace a String in a Message uses has one field for the RegEx pattern, one field for options like case insensitivity, and a third field for the string that will replace the matched pattern.

• Advanced settings like multi-line support, case insensitivity, etc. are not generally supported within the RegEx pattern. Instead, actions use secondary settings to identify usage of these features.

  When these options are provided, they apply as per Microsoft documentation (excerpt below):

  • IgnoreCase - Use case-insensitive matching.
  • MultiLine - Use multiline mode, where ^ and $ match the beginning and end of each line (instead of the beginning and end of the input string).
  • ExplicitCapture - Do not capture unnamed groups. The only valid captures are explicitly named or numbered groups of the form (?<name> subexpression).
  • SingleLine - Use single-line mode, where the period (.) matches every character (instead of every character except \n).
  • IgnorePatternWhitespace - Exclude unescaped white space from the pattern, and enable comments after a number sign (#).
  • RightToLeft - Change the search direction. Search moves from right to left instead of from left to right.
  • ECMAScript - Enable ECMAScript-compliant behavior for the expression.
  • CultureInvariant - Ignore cultural differences in language.