Qorus Integration Engine®  5.1.39_git
Finite State Machines / Flow Designer

Table of Contents

Overview of Finite State Machines / Flow Designer

All Qorus integration objects are described by YAML metadata produced by our IDE, which is available as a free (as in free of charge and also open source) extension to Microsoft Visual Studio Code, a multi-platform editor from Microsoft. The Qorus extension is called Qorus Developer Tools and can be installed directly from Visual Studio Code.

Qorus's Flow Designer creates executable configurations called finite state machines that allow arbitrary logic to be configured and deployed by connecting integration objects, supporting no-code solutions when existing building blocks are sufficient to cover the implementation requirements.

Note
Finite state machines can be defined for workflow steps, service methods, or jobs; if any finite state machine is defined for any of the preceding, then any code also defined for that object is ignored, and only the finite state machine is executed.
Flow Designer Example

Finite state machines are made up of a set of states connected by state transitions which determine the flow of execution and also control error handling.

Data Processing in Finite State Machines

Finite state machines can accept input data and produce output data as well; any input data submitted to the finite state machine when it is executed (either implicitly, such as when triggered from a service method call, other interface action, or event), is passed through the execution of the finite state machine; each state can accept or ignore its input data, and the data output by each state can be accepted or ignored by any states connected through transitions.

Note that the input data in a state is always available under the "input" key of the local context ($local:input) in template resolution when resolving configuration item vales; see Config Item / Building Block Template Substitution Strings for more information on templates.

Finite State Machine States

Each state can be one of the following types:

Note
A mapper can also be considered a single-element data pipeline, because mappers can also be elements of data pipelines.

Finite State Machine API Call States

An API call state is a state in the flow where an API call is made to an accessible data provider supporting the request-response integration pattern in Qorus.

These can be accessed through data provider factories, a connection supporting a data provider, or a remote Qorus connection.

The input type of the API call state depends on the value of the Allow API Arguments switch. If this switch is set to True, then there is no input type, and the state is compatible with all previous states, as the input data is used only as local context (as $local:input) when resolving arguments given in the state itself, otherwise the input type of the state is the request type.

In all cases the output type is the response type.

When the state is executed, the API is called using the argument data, either from input data (if Allow API Arguments is False) or from data given in the API call state itself (if Allow API Arguments is True) to form the request, and the response is returned as the output data of the state.

The following is an example API call state providing explicit arguments:

API Call State Example

Qorus APIs in API Call States

Qorus exports many convenient APIs through the qorus-api DataProvider factory that can be used in Finite State Machine.

The following is a table listing the available APIs.

Note
Each API should be self-documenting, as they are introspected with documentation about each API and also about each argument.

Qorus APIs in the qorus-api DataProvider Factory

API Path Description
factory/qorus-api/data-provider/create Executes a "create record" action in a record-based data provider; also supports upserting / merging in supported data providers
factory/qorus-api/data-provider/delete Executes a "delete record" action in a record-based data provider
factory/qorus-api/data-provider/do-request Executes a request-response API call in an API-based data provider
factory/qorus-api/data-provider/search Executes a record search action in a record-based data provider
factory/qorus-api/data-provider/search-bulk-iterator Returns a bulk record iterator object suitable for input to a data pipeline for record-based data providers
factory/qorus-api/data-provider/update Executes a "record update" action in a record-based data provider
factory/qorus-api/job/disable Disables a job
factory/qorus-api/job/enable Enables a job
factory/qorus-api/job/get-job-result Returns the result info for a job
factory/qorus-api/job/info Returns metadata and status information for a job
factory/qorus-api/job/reset Resets a job
factory/qorus-api/job/run Runs a job and returns the result
factory/qorus-api/job/set-active Activates a job
factory/qorus-api/job/set-inactive Deactivates a job
factory/qorus-api/job/list Provides data provider children representing all Qorus jobs
factory/qorus-api/job/list/<job-name-or-id>/enable Enables the given job
factory/qorus-api/job/list/<job-name-or-id>/disable Disables the given job
factory/qorus-api/job/list/<job-name-or-id>/info Returns metadata and status information for the given job
factory/qorus-api/job/list/<job-name-or-id>/reset Resets the given job
factory/qorus-api/job/list/<job-name-or-id>/run Runs the given job and returns the result
factory/qorus-api/job/list/<job-name-or-id>/set-active Activates the given job
factory/qorus-api/job/list/<job-name-or-id>/set-inactive Deactivates the given job
factory/qorus-api/service/call-method Calls a service method and returns the result
factory/qorus-api/service/disable Disables a service
factory/qorus-api/service/enable Enables a service
factory/qorus-api/service/info Returns metadata and status information for a service
factory/qorus-api/service/load Loads and initializes a service
factory/qorus-api/service/reset Resets a service
factory/qorus-api/service/set-autostart Sets the autostart value for a service
factory/qorus-api/service/unload Unloads a service
factory/qorus-api/service/list Provides data provider children representing all Qorus services
factory/qorus-api/service/list/<service-name-or-id>/call-method Calls a method in the given service and returns the result
factory/qorus-api/service/list/<service-name-or-id>/disable Disables the given service
factory/qorus-api/service/list/<service-name-or-id>/enable Enables the given service
factory/qorus-api/service/list/<service-name-or-id>/info Returns metadata and status information for the given service
factory/qorus-api/service/list/<service-name-or-id>/load Loads the given service
factory/qorus-api/service/list/<service-name-or-id>/reset Resets the given service
factory/qorus-api/service/list/<service-name-or-id>/set-autostart Sets the autostart value for the given service
factory/qorus-api/service/list/<service-name-or-id>/unload Unloads the given service
factory/qorus-api/util/break Executes a break action in a Finite State Machine loop
factory/qorus-api/util/continue Executes a continue action in a Finite State Machine loop
factory/qorus-api/util/get-data Returns data for onwards processing in subsequent Finite State Machine states
factory/qorus-api/util/log-message Logs a message in the current log file in a Finite State Machine
factory/qorus-api/util/post-async-queue Posts a value on an asynchronous queue for an asynchronous step
factory/qorus-api/util/post-sync-event Posts a workflow synchronization event to enable any workflow synchronization steps waiting on the event to continue processing
factory/qorus-api/util/rest-request Makes a REST request and returns the response
factory/qorus-api/util/throw-exception Throws an exception in a Finite State Machine
factory/qorus-api/util/workflow/bind-event Binds a workflow synchronization event to a workflow synchronization step
factory/qorus-api/util/workflow/bind-event-unposted Binds a workflow synchronization event to a workflow synchronization step only if the event is unposted
factory/qorus-api/util/workflow/bind-subworkflow Binds a subworkflow to a subworkflow step
factory/qorus-api/util/workflow/skip-async-step Skips binding an asynchronous queue entry to an asynchronous step
factory/qorus-api/util/workflow/skip-event Skips binding a workflow synchronization event to a workflow synchronization step
factory/qorus-api/util/workflow/skip-subworkflow Skips binding a subworkflow to a subworkflow step
factory/qorus-api/util/workflow/submit-async-key Binds a asynchronous queue key to an asynchronous step
factory/qorus-api/util/write-output Writes output data according to a template hash
factory/qorus-api/workflows/block-order Blocks a workflow order
factory/qorus-api/workflows/cancel-order Cancels a workflow order
factory/qorus-api/workflows/create-order Creates a workflow order
factory/qorus-api/workflows/exec-async Executes a workflow order in a synchronous workflow execution instance with an asynchronous call (the call returns immediately)
factory/qorus-api/workflows/exec-sync Executes a workflow order in a synchronous workflow execution instance with a synchronous call (the call returns when the workflow order has a final status)
factory/qorus-api/workflows/get-order-info Returns order information for a workflow order
factory/qorus-api/workflows/retry-order Retries a workflow order
factory/qorus-api/workflows/unblock-order Unblocks a workflow order and resets its previous status
factory/qorus-api/workflows/uncancel-order Uncancels a workflow order and resets its previous status
factory/qorus-api/workflows/disable Disables a workflow order
factory/qorus-api/workflows/enable Enables a workflow order
factory/qorus-api/workflows/info Returns metadata and status information for a workflow
factory/qorus-api/workflows/reset Resets a workflow
factory/qorus-api/workflows/set-autostart Sets the autostart value for a workflow
factory/qorus-api/workflows/list Provides data provider children representing all Qorus workflows
factory/qorus-api/workflows/list/<workflow-name-or-id>/disable Disables the given workflow
factory/qorus-api/workflows/list/<workflow-name-or-id>/enable Enables the given workflow
factory/qorus-api/workflows/list/<workflow-name-or-id>/exec-async Executes a workflow order for the given workflow in a synchronous workflow execution instance with an asynchronous call (the call returns immediately)
factory/qorus-api/workflows/list/<workflow-name-or-id>/exec-sync Executes a workflow order for the given workflow in a synchronous workflow execution instance with an asynchronous call (the call returns when the workflow order has a final status)
factory/qorus-api/workflows/list/<workflow-name-or-id>/info Returns metadata and status information for the given workflow
factory/qorus-api/workflows/list/<workflow-name-or-id>/reset Resets the given workflow
factory/qorus-api/workflows/list/<workflow-name-or-id>/set-autostart Sets the autostart value for the given workflow

Qorus Data Provider API: Run Job

Summary
Runs a job and returns the result
Path to Data Provider API
factory/qorus-api/job/run
Arguments
  • job: the job ID or name
Return Value
  • job_instanceid: the unique ID of the result of running the job
  • status: The job status (either COMPLETE or ERROR)

Qorus Data Provider API: Run Implicit Job

Summary
Runs the job identified in the data provider path and returns the result
Path to Data Provider API
factory/qorus-api/job/list/job-name-or-id/run
Arguments
This API takes no arguments
Return Value
  • job_instanceid: the unique ID of the result of running the job
  • status: The job status (either COMPLETE or ERROR)

Qorus Data Provider API: Create Order

Path to Data Provider API
factory/qorus-api/workflow/create-order
Summary
Creates a workflow order for processing
Arguments
  • workflow: The workflow name, name:version, or workflow ID for the order to be created
  • staticdata: The initial static data for the order
  • dynamicdata: The initial dynamic data for the order
  • external_order_instanceid: An optional external ID for the workflow order
  • sensitive_data: A hash of sensitive data information for the workflow; this key can only be used when submitting the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values, and the hash values have the following keys:
    • aliases: (optional list of strings) zero or more string aliases for the sensitive data
    • data: (hash) the sensitive data hash itself
    • meta: (optional hash) a hash of metadata for the sensitive data with the following recommended keys (recommended keys are not enforced by the API itself):
      • PURPOSE: free-form information about the purpose of the sensitive data
      • CATEGORIES: free-form information about the categories of sensitive data
      • RECIPIENTS: free-form information about the recipients or recipient catories of sensitive data
      • STORAGE: free-form information about the storage time or rules for sensitive data
  • status: The initial order status (default if not present READY); must be either READY or BLOCKED
  • parent_workflow_instanceid: A loosely-coupled workflow that will be marked as the parent of this workflow
  • priority: The order priority from 0 - 999; priority 0 is the highest; 999 is the lowest
  • scheduled: The earliest date and time the order can be processed; if this date is given as a future date/time value and a READY tatus is given, then the initial status of the workflow order data instance will be automatically changed to SCHEDULED
  • global_unique_key: A hash giving one or more unique order keys for the order (across all workflows regardless of workflowid, name, or version); keys are order key names and values are the string key values; if this key already exists for any order in the system, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_specific_unique_key: A hash giving one or more unique order keys for the particular workflowid (which matches a unique name and workflow version); keys are order key names and values are the string key values; if any of the keys given already exists for an order with the target workflowid, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_unique_key: A hash giving one or more unique order keys for the particular workflow by name only (across all workflows with the same name regardless of version); keys are order key names and values are the string key values; if this key already exists for a workflow order with the same name, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • orderkeys: A hash of order keys for the order

Qorus Data Provider API: Break

Path to Data Provider API
factory/qorus-api/util/break
Summary
Executes a break action in a Finite State Machine loop
Arguments
This API takes no arguments

Qorus Data Provider API: Continue

Path to Data Provider API
factory/qorus-api/util/continue
Summary
Executes a continue action in a Finite State Machine loop
Arguments
This API takes no arguments

Qorus Data Provider API: Get Data

Path to Data Provider API
factory/qorus-api/util/get-data
Summary
Returns data for onwards processing in subsequent Finite State Machine states.

The argument can be of any type; as all API state arguments are subjected to automatic template substitution, this argument can also contain template strings.

Qorus Data Provider API: Post Async Queue

Path to Data Provider API
factory/qorus-api/util/post-async-queue
Summary
Posts a value to an asynchronous workflow step queue
Arguments
Details
Updates a pending entry in an asynchronous step queue with status WAITING to RECEIVED.

Data is stored serialized in YAML format, so that type information is preserved when passed to the step's asynchronous back-end code.

Qorus Data Provider API: Post Synchronization Event

Path to Data Provider API
factory/qorus-api/util/post-sync-event
Summary
Posts a workflow synchronization event to enable any workflow synchronization steps waiting on the event to continue processing.
Arguments

Qorus Data Provider API: Bind Workflow Synchronization Event

Path to Data Provider API
factory/qorus-api/util/workflow/bind-event
Summary
Binds a workflow synchronization event to a workflow synchronization step.
Note
This API can only be called from a workflow synchronization step

Qorus Data Provider API: Bind Workflow Synchronization Event Unposted

Path to Data Provider API
factory/qorus-api/util/workflow/bind-event-unposted
Summary
Binds a workflow synchronization event to a workflow synchronization step but only if the event is still unposted.
Note
This API can only be called from a workflow synchronization step

Qorus Data Provider API: Bind Subworkflow

Path to Data Provider API
factory/qorus-api/util/workflow/bind-subworkflow
Summary
Binds a subworkflow to a subworkflow step
Arguments
  • workflow: The workflow name, name:version, or workflow ID for the order to be created
  • staticdata: The initial static data for the order
  • dynamicdata: The initial dynamic data for the order
  • external_order_instanceid: An optional external ID for the workflow order
  • sensitive_data: A hash of sensitive data information for the workflow; this key can only be used when submitting the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values, and the hash values have the following keys:
    • aliases: (optional list of strings) zero or more string aliases for the sensitive data
    • data: (hash) the sensitive data hash itself
    • meta: (optional hash) a hash of metadata for the sensitive data with the following recommended keys (recommended keys are not enforced by the API itself):
      • PURPOSE: free-form information about the purpose of the sensitive data
      • CATEGORIES: free-form information about the categories of sensitive data
      • RECIPIENTS: free-form information about the recipients or recipient catories of sensitive data
      • STORAGE: free-form information about the storage time or rules for sensitive data
  • parent_workflow_instanceid: A loosely-coupled workflow that will be marked as the parent of this workflow
  • priority: The order priority from 0 - 999; priority 0 is the highest; 999 is the lowest
  • scheduled: The earliest date and time the order can be processed; if this date is given as a future date/time value and a READY tatus is given, then the initial status of the workflow order data instance will be automatically changed to SCHEDULED
  • global_unique_key: A hash giving one or more unique order keys for the order (across all workflows regardless of workflowid, name, or version); keys are order key names and values are the string key values; if this key already exists for any order in the system, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_specific_unique_key: A hash giving one or more unique order keys for the particular workflowid (which matches a unique name and workflow version); keys are order key names and values are the string key values; if any of the keys given already exists for an order with the target workflowid, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_unique_key: A hash giving one or more unique order keys for the particular workflow by name only (across all workflows with the same name regardless of version); keys are order key names and values are the string key values; if this key already exists for a workflow order with the same name, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • orderkeys: A hash of order keys for the order
Details
This API is the alternative to calling Qorus Data Provider API: Skip Subworkflow
Note
This API can only be called from a subworkflow step

Qorus Data Provider API: Skip Async Step

Path to Data Provider API
factory/qorus-api/util/workflow/skip-async-step
Summary
This API will cause the execution of an asynchronous step to be skipped.
Arguments
This API takes no arguments
Details
This API is the alternative to calling Qorus Data Provider API: Submit Workflow Async Key
Note
This API can only be called from an asynchronous step

Qorus Data Provider API: Skip Workflow Synchronization Event Step

Path to Data Provider API
factory/qorus-api/util/workflow/skip-event
Summary
Skips binding a workflow synchronization event to a workflow synchronization step
Arguments
This API takes no arguments
Note
This API can only be called from a workflow synchronization step

Qorus Data Provider API: Skip Subworkflow

Path to Data Provider API
factory/qorus-api/util/workflow/skip-subworkflow
Summary
Skips binding a subworkflow to a subworkflow step
Arguments
This API takes no arguments
Details
This API is the alternative to calling Qorus Data Provider API: Bind Subworkflow
Note
This API can only be called from a subworkflow step

Qorus Data Provider API: Submit Workflow Async Key

Path to Data Provider API
factory/qorus-api/util/workflow/submit-async-key
Summary
Binds a asynchronous queue key to an asynchronous step.
Arguments
  • key: the key for the asynchronous queue entry; must be unique in the queue; this key along with the queue name must be used later to update the queue to cause the step to go to a COMPLETE status.
Details
This API is the alternative to calling Qorus Data Provider API: Skip Async Step
Note
This API can only be called from an asynchronous step

Qorus Data Provider API: Write Output API Data Provider

Path to Data Provider API
factory/qorus-api/util/write-output
Summary
Writes output data to locations provided by the hash argument, which should be assigned a hash as follows.
Argument Format
key (data to write) ➜ location (output location)
YAML Argument Example
\$local:input: \$dynamic:account
Details
This above argument would result in FSM input data being stored in the account key of workflow dynamic data when executed in a workflow context.

Hash keys in the argument are subject to template substitution with UserApi::expandTemplatedValue() (where $local:input represents input data to the current state); hash values provide the output locations to store the values according to template substitution strings marked as writable (W).

Hash keys must be strings when passed to the internal API call, therefore any $ signs must be escaped.

Hash values must be strings representing output locations, therefore any $ signs must also be escaped.
Note
  • $local:input represents FSM state input data
  • Template values in API call arguments are automatically evaluated before being passed to the data provider; for this reason, all $ signs must be escaped with a backslash as in the above example, so they are evaluated by the Qorus API call itself and not during standard template evaluation of API call arguments by Qorus.
This API only works when called from a Qorus interface, as an interface context is needed for writing output data.

Finite State Machine Single Record Search States

A single record search state uses the parameters configured in the state to execute a search for a single record in a record-based data provider.

These can be accessed through data provider factories, a datasource connection, a connection supporting a data provider, or a remote Qorus connection.

This state has no input type, meaning that it's compatible with all other states on input. Input data is used only as local context (as $local:input) when resolving arguments given in the state itself.

If the required_result option is True, then a search returning no record causes a SEARCH-SINGLE-RESULT-ERROR exception to be raised. In this case the output type is always the record type of the data provider.

In case a result is not required, the output type can also be no value.

Finite State Machine Multiple Record Search States

A multiple record search state uses the parameters configured in the state to execute a search for a record set in a record-based data provider.

These can be accessed through data provider factories, a datasource connection, a connection supporting a data provider, or a remote Qorus connection.

This state has no input type, meaning that it's compatible with all other states on input. Input data is used only as local context (as $local:input) when resolving arguments given in the state itself.

If the required_result option is True, then a search returning no records causes a SEARCH-RESULT-ERROR exception to be raised. In this case the output type is always the record type of the data provider.

In case a result is not required, the output type can also be no value.

Finite State Machine Record Update States

A record update state uses the parameters configured in the state to update records based on search criteria and update criteria; the updates are performed in the given record-based data provider.

These can be accessed through data provider factories, a datasource connection, a connection supporting a data provider, or a remote Qorus connection.

This state has no input type, meaning that it's compatible with all other states on input. Input data is used only as local context (as $local:input) when resolving arguments given in the state itself.

If the required_result option is True, then an update operation updating no records causes a UPDATE-RESULT-ERROR exception to be raised.

In all cases the output type of this state is a hash with a single key: records_affected, where the value is the number of rows updated by the operation.

Finite State Machine Record Delete States

A record delete state uses the parameters configured in the state to delete records based on search criteria; the deletes are performed in the given record-based data provider.

These can be accessed through data provider factories, a datasource connection, a connection supporting a data provider, or a remote Qorus connection.

This state has no input type, meaning that it's compatible with all other states on input. Input data is used only as local context (as $local:input) when resolving arguments given in the state itself.

If the required_result option is True, then a delete operation deleting no records causes a DELETE-RESULT-ERROR exception to be raised.

In all cases the output type of this state is a hash with a single key: records_affected, where the value is the number of rows deleted by the operation.

Finite State Machine Record Create States

A record create state uses the parameters configured in the state to create records; new records are created in the given record-based data provider.

These can be accessed through data provider factories, a datasource connection, a connection supporting a data provider, or a remote Qorus connection.

This state has no input type, meaning that it's compatible with all other states on input. Input data is used only as local context (as $local:input) when resolving arguments given in the state itself.

In all cases the output type of this state is the record type; the output value is the list of records created.

Finite State Machine Block States

Block states support executing a group of states as a "block"; there are for, foreach, and while block states.

A type of "local variable" is implemented for blocks in the $var:{} Template expression; each block has its own copies of variables in this hash, also a type of "global variable" if implemented in the $transient:{} Template expression; see the previous links and Config Item / Building Block Template Substitution Strings for more information.

The output data for a block is the output data for the last execution of the block defined by the output data of the last state to be executed in the block.

Flow Control in Finite State Machine Block States

When executing finite state machine blocks, the block's flow can be controlled by the following special exceptions:

  • FSM-BREAK: if this exception is thrown, a break action is performed, and the flow will exit the current block being executed (Qorus Data Provider API: Break)
  • FSM-CONTINUE: if this exception is thrown a continue action is performed, and the flow will start again from the initial state, if there is another loop to be made in the block, otherwise the flow exits the current block (Qorus Data Provider API: Continue)

Finite State Machine For Block States

Finite state machine for blocks implement a loop driven by the following configuration:

  • condition: the condition expression; evaluated immediately before each iteration of the loop is executed; the loop stops executing when this expression evaluates to False
  • init: the initialization expression; the value of this expression will be stored in the location identifed by init_var; this expression is evaluated once at the start of the loop
  • init_var: a string value giving the field name in the $var: hash where the value of the init expression is stored
  • language: either qore or python, giving the language for expression evaluation
  • update: the update expression for the for loop; if present, it is evaluted after each iteration of the loop is executed and before the condition expression is evaluated for the next iteration

All expressions (init, condition, and update) are first substituted with a call to UserApi::expandTemplatedValue(). If the value returned is a string, then it is evaluated with the language defined by language. If the value is any other type, then that value is used as the value of the expression without further evaluation.

For more information on the boolean evaluation of the condition template expression, see Finite State Machine Boolean Evaluation.

Note
  • Both init and init_var must be present or both are ignored
  • Both update and update_var must be present or both are ignored
  • qore is the default for the expression evaluation language as it is fully multithreaded
See also
Config Item / Building Block Template Substitution Strings

Finite State Machine For State Data Processing

The output data for a for block is the output data for the last state executed in the block.

Finite State Machine Foreach Block States

Finite state machine foreach blocks implement a loop driven by a value or a list of values driven by the following configuration:

  • loop: This expression is evaluated once at the start of the foreach loop, and the value returned is used to execute the loop and determine the data submitted to the initial state(s) in the block. If the expression evaluates to a list, then the loop is executed with each element of list in turn as the data for the initial state(s) in the block. If the expression evaluates to a single value, then the foreach loop is executed once for that value. If the expression evaluates to no value, then foreach loop execution is skipped.
  • language: either qore or python, giving the language for expression evaluation

The loop expression is first substituted with a call to UserApi::expandTemplatedValue(). If the value returned is a string, then it is evaluated with the language defined by language. If the value is any other type, then that value is used as the value of the expression without further evaluation.

Note
qore is the default expression evaluation language as it is fully multithreaded

Finite State Machine Foreach State Data Processing

The output data for a foreach block is the output data for the last state executed in the block.

Finite State Machine While Block States

Finite state machine while blocks implement a loop driven by the following configuration:

  • condition: the condition expression; evaluated immediately before each iteration of the loop is executed; the loop stops executing when this expression evaluates to False
  • language: either qore or python, giving the language for expression evaluation

The condition expression is first substituted with a call to UserApi::expandTemplatedValue(). If the value returned is a string, then it is evaluated with the language defined by language. If the value is any other type, then that value is used as the value of the expression without further evaluation.

For more information on the boolean evaluation of the condition template expression, see Finite State Machine Boolean Evaluation.

Note
qore is the default for the expression evaluation language as it is fully multithreaded

Finite State Machine While State Data Processing

The output data for a while block is the output data for the last state executed in the block.

Finite State Machine If States

The if state is a special state that has a condition and True and False transitions. The condition is a string expression that is first processed with UserApi::expandTemplatedValue(). If the result of this expression is a string, then it is interpreted as an expression in the given language (either qore or python).

The value is then converted to a bool, which then triggers the execution of either the True transition(s) or the False transition(s).

Transitions in if states cannot be further qualified with conditions on each transition.

For more information on the boolean evaluation of the condition template expression, see Finite State Machine Boolean Evaluation.

Finite State Machine If State Data Processing

Input data is passed through as-is to states transitioned through if states.

Finite State Machine State Transitions

State transitions determine the flow of execution in finite state machines. At the end of executing each state, transitions are evaluated and executed in order. Each state transition (if not a transition from an if state) can be configured with a condition, which if evaluated to True, causes the flow of execution to continue to the next state. If there is no condition associated with the transition, then the transition is executed unconditionally.

State transition conditions can be either a string expression or a class connector; when the condition is evaluated, the result is converted to a boolean value as described here which determines if the flow of execution continues to the next state or not.

Transition expressions are first parsed with UserApi::expandTemplatedValue(). If the result of this expression is a string, then it is interpreted as an expression in the given language (either qore or python).

In either case, the resulting value is converted to a bool to determine if the transition is followed or not.

For more information on the boolean evaluation of the transition condition template expression, see Finite State Machine Boolean Evaluation.

Finite State Machine State Error Transitions

State transitions can also be configured with a string error value; if an exception is thrown during state execution, the exception error string is compared to the string error value, and if it matches, then execution continues in the target state.

The error string is derived depending on the source language as follows:

  • Python: the full error class name (ex: builtins.ValueError)
  • Java: the full error class name (ex: java.lang.NullPointerException)
  • Qore: the error string code (ex: SOCKET-CONNECT-ERROR)
Note
An exact match to the actual exception class is made for Python and Java; no subclass comparisons are made

Finite State Machine Boolean Evaluation

Finite state machine boolean evaluation is driven by two elements of configuration:

  • condition: a condition template expression
  • language: the evaluation language if condition evaluates to a string

First, condition is evaluated with an internal call to UserApi::expandTemplatedValue().

If the resulting value is a string, then it is evaluated with the language specified by language.

If the resulting value is not a string, then it is evaluated per its data type according to the table below.

Example 1
In this example, the template is evaluated with a local input context with the following keys: 
{
    intent_name: "i.400.userID-correct",
    project_id: "02724364-f352-46a2-9279-083989c53360",
    session_id: "769113b8-ee2a-4495-acf3-b12bf4709790",
    timestamp: 1635493630000,
    timestamp_str: "Fri Oct 29 09:47:10 CEST+0200",
    parameters: {
        p_inbound_user_id: "SJ3ZA",
        yes: "ja"
    }
}
The following template: 
"$local:input.parameters.p_inbound_user_id".val()
will be first subjected to template substitution, resulting in the following string: 
"SJ3ZA".val()
which will then be evaluated as a Qore expression, resulting in the result True.
See also
<string>::val()
Example 2
If on the other hand, the following template would be evaluated in the same context as in the previous example: 
"$local:input.parameters.p_outbound_user_id".val()
This results in the following string after template substitution: 
"".val()
(because the "parameters" hash has no "p_outbound_user_id" key) which will then be evaluated as a Qore expression, resulting in the result False.
See also
<string>::val()
Example 3
As an alternative to achieve the same results as in the first example, the following template string: 
exists $qore-expr-value:{$local:input.parameters.p_inbound_user_id}
will be first subjected to template substitution, resulting in the following string: 
exists "SJ3ZA"
which will then be evaluated as a Qore expression, resulting in the result True.
See also
Example 4
If on the other hand, the following template would be evaluated in the same context as in the first example: 
exists $qore-expr-value:{$local:input.parameters.p_outbound_user_id}
This results in the following string after template substitution: 
exists NOTHING
(because the "parameters" hash has no "p_outbound_user_id" key) which will then be evaluated as a Qore expression, resulting in the result False.
See also
Note
  • To prohibit evaluation of a template value that results in a string, enclose the template in quotes; ex: "$local:version"
  • qore is the default expression evaluation language as it is fully multithreaded

Once the template has been resolved, the value is processed according to its type as in the following table:

Boolean Evaluation per Data Type
Type Description
bool value taken literally
string True if non empty and not "0", False if empty or "0"
int, float, or number True if non zero, False if zero
hash, list, binary True if non-empty, False if empty
date True if not 1970-01-01Z or a zero duration, False if 1970-01-01Z or a zero duration
nothing, null False
See also
Config Item / Building Block Template Substitution Strings