Qorus Integration Engine® Enterprise Edition 6.0.27_prod
|
Back to the Developer's Guide Table of Contents
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.
Finite state machines are made up of a set of states connected by state transitions which determine the flow of execution (and state data, for states that produce and accept data) and also control error handling.
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.
When editing config items in finite machine states, the input data passed to the state from the previous state can be referenced as $local:input
; for example to get the account-id
key from local input, you can use:
$local:{input.account-id}
Note the following example using input data in the argument of an API call state; the same approach can also be used in config items and other arguments in other state types.
When a finite state machine is associated with a service method, the input data is made up of the arguments to the method call.
If there is only one argument to the method, the finite state machine input data is that single argument.
If there is more than one argument, the input data to the finite state machine is the entire list of method arguments.
info
will be accessible as $local:input[0]
, and key
as $local:input[1]
in the first state. Globally in the finite state machine, info
will be accessible as $fsminput:*[0]
, and key
as $fsminput:*[1]
.When a finite state machine is associated with a step method, the input data depends on the method arguments. Generally, any method taking a single argument will have that single argument as the input data directly. Methods taking more than one argument will have the argument list as the input data. Methods taking no arguments will have no input data.
$local:input
in the first state. Globally in the finite state machine, the array argument passed to the primary step method will be accessible as $fsminput:*
. $local:input
in the first state. Globally in the finite state machine, the array argument passed to the validation method will be accessible as $fsminput:*
. $local:input
in the first state. Globally in the finite state machine, the async key passed to the validation method will be accessible as $fsminput:*
. $local:input[0]
and the array argument as $local:input[1]
in the first state. Globally in the finite state machine, the async key passed to the validation method (if available) will be accessible as $fsminput:*[0]
and the array argument as $fsminput:*[1]
. $local:input
in the first state. Globally in the finite state machine, the hash passed to the backend method will be accessible as $fsminput:*
. $local:input[0]
and the array argument as $local:input[1]
in the first state. Globally in the finite state machine, hash passed to the backend method will be accessible as $fsminput:*[0]
and the array argument as $fsminput:*[1]
. Local and global variables can be declared in a finite state machine flow, and in some cases read-only automatic variables are created depending on the context.
Declaring variables in a finite state machine allows the user to restrict values assigned to the variable to values of a certain type. If the type is declared as a DataProvider, then variable action states can also be created from the variable that allow actions to be executed on a persistent object that often represents a connection to a remote server or resource.
In addition, DataProviders that support transaction management can have transaction management actions performed on them as well, such as beginning, committing, or rolling back transactions.
Automatic variables are created by the IDE when an FSM or block state is created in a context that implies a DataProvider variable.
There are two such cases:
Automatic variables that represent DataProvider object can then be used in FSM variable action states to perform actions on the objects.
Each state can be one of the following types:
A class connector state executes a class connector for the given class. The state's input data is the class connector input data, and the state's output data is the connector's output data.
The class's config items can be configured in the state as well.
A data pipeline state is a state that executes a data pipeline. The input data to the state is the input data for the data pipeline.
Finite state machine data pipeline states do not have any output data, as pipelines have no output data.
Data pipelines do not have output data, because they are not necessarily linear; they can have any number of parallel queues, in which case there is no single final pipeline element; pipeline elements do not have output data but rather enqueue data for further processing, and in typical use cases the final data pipeline processor elements in a queue do not enqueu any data for further processing but rather write data to an output location, and finally data pipelines are designed to process large volumes of data (including the output processing of the data), therefore a bulk output of massive amounts of data is impractical and does not feature in the design of data pipelines.
Variable action states are states created from Finite State Machine Variables defined as DataProvider objects.
They can execute actions depending on the capabilities of the underlying DataProvider.
Transaction actions can be performed on DataProvider objects that support transaction management.
Supported Transaction Actions
Action | Description |
begin transaction | Executes a AbstractDataProvider::beginTransaction() call on the object, starting a transaction on the object. After this call, the transaction must be committed or rolled back, or an exception will be raised when the thread exits or the local thread resource context is closed |
commit | Executes a AbstractDataProvider::commit() call on the object, committing the transaction |
rollback | Executes a AbstractDataProvider::rollback() call on the object, rolling back the transaction |
An API call state is a state in the flow where an API call is made to an accessible DataProvider supporting the request-response integration pattern in Qorus.
These can be accessed through DataProvider factories, a connection supporting a DataProvider, 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:
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.
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 DataProvider; also supports upserting / merging in supported DataProvider |
factory/qorus-api/data-provider/delete | Executes a "delete record" action in a record-based DataProvider |
factory/qorus-api/data-provider/do-request | Executes a request-response API call in an API-based DataProvider |
factory/qorus-api/data-provider/search | Executes a record search action in a record-based DataProvider |
factory/qorus-api/data-provider/search-bulk-iterator | Returns a bulk record iterator object suitable for input to a data pipeline for record-based DataProviders |
factory/qorus-api/data-provider/update | Executes a "record update" action in a record-based DataProvider |
factory/qorus-api/jobs/disable | Disables a job |
factory/qorus-api/jobs/enable | Enables a job |
factory/qorus-api/jobs/get-job-result | Returns the result info for a job |
factory/qorus-api/jobs/info | Returns metadata and status information for a job |
factory/qorus-api/jobs/reset | Resets a job |
factory/qorus-api/jobs/run | Runs a job and returns the result |
factory/qorus-api/jobs/set-active | Activates a job |
factory/qorus-api/jobs/set-inactive | Deactivates a job |
factory/qorus-api/jobs/list | Provides DataProvider children representing all Qorus jobs |
factory/qorus-api/jobs/list/<job-name-or-id>/enable | Enables the given job |
factory/qorus-api/jobs/list/<job-name-or-id>/disable | Disables the given job |
factory/qorus-api/jobs/list/<job-name-or-id>/info | Returns metadata and status information for the given job |
factory/qorus-api/jobs/list/<job-name-or-id>/reset | Resets the given job |
factory/qorus-api/jobs/list/<job-name-or-id>/run | Runs the given job and returns the result |
factory/qorus-api/jobs/list/<job-name-or-id>/set-active | Activates the given job |
factory/qorus-api/jobs/list/<job-name-or-id>/set-inactive | Deactivates the given job |
factory/qorus-api/services/call-method | Calls a service method and returns the result |
factory/qorus-api/services/disable | Disables a service |
factory/qorus-api/services/enable | Enables a service |
factory/qorus-api/services/info | Returns metadata and status information for a service |
factory/qorus-api/services/load | Loads and initializes a service |
factory/qorus-api/services/reset | Resets a service |
factory/qorus-api/services/set-autostart | Sets the autostart value for a service |
factory/qorus-api/services/unload | Unloads a service |
factory/qorus-api/services/list | Provides DataProvider children representing all Qorus services |
factory/qorus-api/services/list/<service-name-or-id>/call-method | Calls a method in the given service and returns the result |
factory/qorus-api/services/list/<service-name-or-id>/disable | Disables the given service |
factory/qorus-api/services/list/<service-name-or-id>/enable | Enables the given service |
factory/qorus-api/services/list/<service-name-or-id>/info | Returns metadata and status information for the given service |
factory/qorus-api/services/list/<service-name-or-id>/load | Loads the given service |
factory/qorus-api/services/list/<service-name-or-id>/reset | Resets the given service |
factory/qorus-api/services/list/<service-name-or-id>/set-autostart | Sets the autostart value for the given service |
factory/qorus-api/services/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-sla-error | Posts an error event metric on an SLA |
factory/qorus-api/util/post-sla-success | Posts a success event metric on an SLA |
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/get-feedback | Retrieves workflow feedback data from a subworkflow step in the parent workflow |
factory/qorus-api/util/workflow/leave-feedback | Leaves workflow feedback data from a subworkflow step for the parent workflow |
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 |
factory/qorus-api/workflows/enable | Enables a workflow |
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 DataProvider 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 a synchronous 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 |
factory/qorus-api/jobs/disable
job:
the job ID or namename
(string): the job's nameversion
(string): the job's versionjobid
(int): the job IDinfo
(string): a string giving the status of the operationfactory/qorus-api/jobs/enable
job:
the job ID or namename
(string): the job's nameversion
(string): the job's versionjobid
(int): the job IDinfo
(string): a string giving the status of the operationfactory/qorus-api/jobs/run
job:
the job ID or namefactory/qorus-api/jobs/list/job-name-or-id/run
factory/qorus-api/services/disable
service:
the service ID or namename
(string): the service's nameversion
(string): the service's versionserviceid
(int): the service IDinfo
(string): a string giving the status of the operationfactory/qorus-api/services/enable
service:
the service ID or namename
(string): the service's nameversion
(string): the joserviceb's versionserviceid
(int): the service IDinfo
(string): a string giving the status of the operationfactory/qorus-api/workflow/create-order
workflow:
The workflow name, name:version, or workflow ID for the order to be createdstaticdata:
The initial static data for the orderdynamicdata:
The initial dynamic data for the orderexternal_order_instanceid:
An optional external ID for the workflow ordersensitive_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 datadata:
(hash) the sensitive data hash itselfmeta:
(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 dataCATEGORIES:
free-form information about the categories of sensitive dataRECIPIENTS:
free-form information about the recipients or recipient catories of sensitive dataSTORAGE:
free-form information about the storage time or rules for sensitive datastatus:
The initial order status (default if not present READY); must be either READY or BLOCKEDparent_workflow_instanceid:
A loosely-coupled workflow that will be marked as the parent of this workflowpriority:
The order priority from 0 - 999; priority 0 is the highest; 999 is the lowestscheduled:
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 SCHEDULEDglobal_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 keyworkflow_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 keyworkflow_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 keyorderkeys:
A hash of order keys for the orderfactory/qorus-api/workflow/disable
workflow:
the workflow ID or namename
(string): the workflow's nameversion
(string): the workflow's versionworkflowid
(int): the workflow IDinfo
(string): a string giving the status of the operationfactory/qorus-api/workflow/enable
workflow:
the workflow ID or namename
(string): the workflow's nameversion
(string): the workflow's versionworkflowid
(int): the workflow IDinfo
(string): a string giving the status of the operationfactory/qorus-api/util/break
factory/qorus-api/util/continue
factory/qorus-api/util/get-data
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.
factory/qorus-api/util/post-async-queue
queue:
The name of the asynchronous queuedata:
data to post on the queue; must be in hash format (or NOTHING)factory/qorus-api/util/post-sla-error
sla:
the name of the SLAvalue:
The metric for the error eventerr:
the error codedesc:
the error descriptionfactory/qorus-api/util/post-sla-success
sla:
the name of the SLAvalue:
The metric for the error eventfactory/qorus-api/util/post-sync-event
type:
The workflow synchronization event type for the event to postkey:
The unique event key name of the event type to postfactory/qorus-api/util/workflow/bind-event
factory/qorus-api/util/workflow/bind-event-unposted
factory/qorus-api/util/workflow/bind-subworkflow
workflow:
The workflow name, name:version, or workflow ID for the order to be createdstaticdata:
The initial static data for the orderdynamicdata:
The initial dynamic data for the orderexternal_order_instanceid:
An optional external ID for the workflow ordersensitive_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 datadata:
(hash) the sensitive data hash itselfmeta:
(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 dataCATEGORIES:
free-form information about the categories of sensitive dataRECIPIENTS:
free-form information about the recipients or recipient catories of sensitive dataSTORAGE:
free-form information about the storage time or rules for sensitive dataparent_workflow_instanceid:
A loosely-coupled workflow that will be marked as the parent of this workflowpriority:
The order priority from 0 - 999; priority 0 is the highest; 999 is the lowestscheduled:
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 SCHEDULEDglobal_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 keyworkflow_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 keyworkflow_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 keyorderkeys:
A hash of order keys for the orderfactory/qorus-api/util/workflow/get-feedback
key:
the key used by the child to leave workflow feedback datafactory/qorus-api/util/workflow/leave-feedback
key:
the key used by the child to leave workflow feedback datafactory/qorus-api/util/workflow/skip-async-step
factory/qorus-api/util/workflow/skip-event
factory/qorus-api/util/workflow/skip-subworkflow
factory/qorus-api/util/workflow/submit-async-key
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.factory/qorus-api/util/write-output
\$local:input: \$dynamic:account
account
key of workflow dynamic data when executed in a workflow context.$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
).$
signs must be escaped.$
signs must also be escaped.$local:input
represents FSM state input data$
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.A send message state sends a message with a message-based DataProvider.
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.
Since sending DataProvider messages provides no output, the send message state also has no output.
A single record search state uses the parameters configured in the state to execute a search for a single record in a record-based DataProvider, such a DB table or a platform that presents a table-like interface through the DataProvider API.
These can be accessed through DataProvider factories, a datasource connection, a connection supporting a DataProvider, 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 DataProvider.
In case a result is not required, the output type can also be no value.
A multiple record search state uses the parameters configured in the state to execute a search for a record set in a record-based DataProvider, such a DB table or a platform that presents a table-like interface through the DataProvider API.
These can be accessed through DataProvider factories, a datasource connection, a connection supporting a DataProvider, 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 DataProvider.
In case a result is not required, the output type can also be no value.
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 DataProvider, such a DB table or a platform that presents a table-like interface through the DataProvider API.
These can be accessed through DataProvider factories, a datasource connection, a connection supporting a DataProvider, 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.
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 DataProvider, such a DB table or a platform that presents a table-like interface through the DataProvider API.
These can be accessed through DataProvider factories, a datasource connection, a connection supporting a DataProvider, 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.
A record create state uses the parameters configured in the state to create records; new records are created in the given record-based DataProvider, such a DB table or a platform that presents a table-like interface through the DataProvider API.
These can be accessed through DataProvider factories, a datasource connection, a connection supporting a DataProvider, 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.
Block states support executing a group of states as a "block"; there are for, foreach, and while as well as transaction 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.
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 executedFSM-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 blockThese exception can also be thrown with the following API DataProviders:
Finite state machine for
blocks implement a loop driven by the following configuration:
$var:
hash where the value of the init expression is storedqore
or python
, giving the language for expression evaluationfor
loop; if present, it is evaluted after each iteration of the loop is executed and before the condition expression is evaluated for the next iterationAll 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.
qore
is the default for the expression evaluation language as it is fully multithreadedThe output data for a for
block is the output data for the last state executed in the block.
Finite state machine foreach
blocks implement a loop driven by a value or a list of values driven by the following configuration:
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.qore
or python
, giving the language for expression evaluationThe 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.
qore
is the default expression evaluation language as it is fully multithreadedThe output data for a foreach
block is the output data for the last state executed in the block.
Finite state machine while
blocks implement a loop driven by the following configuration:
qore
or python
, giving the language for expression evaluationThe 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.
qore
is the default for the expression evaluation language as it is fully multithreadedThe output data for a while
block is the output data for the last state executed in the block.
Finite state machine transaction block states implement a block that implies a transaction in a transaction-capable DataProvider. The transaction block requires a DataProvider as configuration that will be created as the automatic variable trans
that can then be used for operations on the DataProvider in DataProvider action states, such as record-based operations.
Transaction block states imply a transaction; at the beginning of the block an implicit call to AbstractDataProvider::beginTransaction() is made.
If the block exits without any active exception, then AbstractDataProvider::commit() is called on the DataProvider object, committing the transaction implicitly, otherwise if there is an active exception when the block exits, AbstractDataProvider::rollback() is called on the DataProvider object, rolling back the transaction.
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.
Input data is passed through as-is to states transitioned through if
states.
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.
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:
builtins.ValueError
)java.lang.NullPointerException
)SOCKET-CONNECT-ERROR
)Finite state machine boolean evaluation is driven by two elements of configuration:
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.
{ 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
. "$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
. 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
. 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
. "$local:version"
qore
is the default expression evaluation language as it is fully multithreadedOnce the template has been resolved, the value is processed according to its type as in the following table:
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 |