Interface IWorkflowVariableHandler

public interface IWorkflowVariableHandler
Interface for the variable handler used during execution of the workflow. During workflow execution, nodes may access data via variables. This contains methods for retrieving and storing variables.
Since:
7.0.0
Author:
XIMA MEDIA GmbH

  • Method Details

    • accessAtPath

      @Nullable List<?> accessAtPath(@Nullable Object base, @Nullable String jsonPath)
      Access a value of the given object at a certain JSON path. Note that while simple JSON path only result in a single value, some JSON paths may match multiple values. This method always returns a list of all matching values. If the JSON path only matches a single value, this returns a list with one item.

      For example: 

      // => ["a"]
accessAtPath(["a", "b"], "[0]")

// => [ ["a", "b"] ]
accessAtPath([ ["a", "b"], ["c", "d"] ], "[0]")

// => [ "b" ]
accessAtPath([ ["a", "b"], ["c", "d"] ], "[0][1]")

// => [ 0 ]
accessAtPath({"foo": {"bar": 0}, "baz": 1}, "foo.bar")

// => [ 0 ]
accessAtPath({"foo": {"bar": 0}, "baz": 1}, "foo.bar")

// => [ "c", "d" ]
accessAtPath([ ["a", "b"] , ["c", "d"] ], "[1][*]")
      Parameters:
      base - Base object where to start. If null, an empty list is returned.
      jsonPath - Path to access on the result. If null or empty, the base value is returned.
      Returns:
      A list containing all values matching the given JSON path.

    • getCurrentLoopIndex

      @Nonnull int[] getCurrentLoopIndex()
      Finds the current nested loop index. When only one loop is active, this returns a single number, e.g. [0] for the first iteration, [1] for the second iteration etc. When multiple loops are nested, this returns a list of indices, with one indices entry for each loop, e.g. [2,1,3] for the 3rd iteration of the first loop, the 2nd iteration of the second loop, and the 4th iteration of the third loop.
      Returns:
      The current multi loop index, as determined by the calls to loopStart() and loopNext(). Empty array when no loop is currently active. Should be treated as read-only, modifications to this array are not reflected.
      Since:
      8.2.0

    • getDeclaredCurrentAttachmentsForNode

      @Nullable IWorkflowAttachmentValue getDeclaredCurrentAttachmentsForNode(@Nonnull WorkflowNode node)
      Finds the current attachments provided by the node while it is being executed, see also handler.getCurrentAttachmentValueDescriptor(). When the node is not being executed currently or does not have any attachments, this returns an empty attachment value, but never null.
      Parameters:
      node - Node for which to find the current attachments.
      Returns:
      Attachments provided of the given node if it is being executed, or an empty attachment value otherwise.
      Since:
      8.2.0

    • getDeclaredCurrentFilesForNode

      @Nullable IWorkflowFileValue getDeclaredCurrentFilesForNode(@Nonnull WorkflowNode node)
      Finds the current files provided by the node while it is being executed, see also handler.getCurrentFileValueDescriptor(). When the node is not being executed currently or does not have any files, this returns an empty file value, but never null.
      Parameters:
      node - Node for which to find the current files.
      Returns:
      Files provided of the given node if it is being executed, or an empty file value otherwise.
      Since:
      8.2.0

    • getDeclaredCurrentValueForNode

      @Nullable Object getDeclaredCurrentValueForNode(@Nonnull WorkflowNode node)
      Finds the current value provided by the node while it is being executed, see also handler.getCurrentValueDescriptor(). When the node is not being executed currently or does not provide any value, this returns null.
      Parameters:
      node - Node for which to find the current value.
      Returns:
      Value provided of the given node if it is being executed, or null otherwise.
      Since:
      8.2.0

    • getDeclaredSuccessValuesForNode

      @Nonnull IMultiDimensionalReadOnlyList<IWorkflowNodeResult> getDeclaredSuccessValuesForNode(@Nonnull WorkflowNode node)
      Finds all results for the given node, see also handler.getSuccessValueDescriptor(). A node may be executed multiple times when placed inside a loop. Note that loop can be nested. When the node was not executed yet, this returns null.

      See IWorkflowExecutionContext.node(), to find the nodes for which to obtain the result.

      Parameters:
      node - A node for which to retrieve the result.
      Returns:
      All results that were obtained when the node was executed. When the node was executed multiple times, returns the results in the order of the individual executions. Do not attempt to modify this list.
      Since:
      8.1.0
      See Also:

    • getException

      @Deprecated @Nullable NodeThrewException getException(int index)
      Deprecated.
      Use getCurrentException(int)
      Returns the exception at the given index in the exception stack.

      An exception can be caught via try-catch-blocks. The exception stack keeps track of the exception that was caught by the catch-block. When a catch block contains another try-catch-block, the stack contains a list of all exceptions from all currently active catch-blocks

      Parameters:
      index - Index of the exception to access. 0 corresponds to the most recent catch-block, 1 corresponds to the outer catch block, 2 corresponds to the outer catch block of the outer catch block etc. You can also use negative indices to refer to elements from the beginning of the stack: -1 corresponds to the outermost catch block.
      Returns:
      The exception at the given index, or null when the index is out of range.

    • getCurrentException

      @Nullable NodeThrewException getCurrentException(int index)
      Returns the exception at the given index in the exception stack.

      An exception can be caught via try-catch-blocks. The exception stack keeps track of the exception that was caught by the catch-block. When a catch block contains another try-catch-block, the stack contains a list of all exceptions from all currently active catch-blocks

      Parameters:
      index - Index of the exception to access. 0 corresponds to the most recent catch-block, 1 corresponds to the outer catch block, 2 corresponds to the outer catch block of the outer catch block etc. You can also use negative indices to refer to elements from the beginning of the stack: -1 corresponds to the outermost catch block.
      Returns:
      The exception at the given index, or null when the index is out of range.
      See Also:

    • getExecutionDataForCurrentNodeStack

      @Nonnull <T extends INodeExecutionData> List<T> getExecutionDataForCurrentNodeStack(@Nonnull Class<T> type)
      Each node may provide additional data via IWorkflowExecutor.provideExecutionData(WorkflowNode, INodeExecutionData) that is available while the node is executed. Custom logic may make use of this data to provide different behavior depending on the currently executed nodes.
      Parameters:
      type - Desired type of the node data to return.
      Returns:
      The data associated with the IWorkflowNodeLocator.currents(), in that order, filtered to instances of the given type. The list is read-only and cannot not be modified.
      Since:
      8.2.0

    • getExecutionDataForNode

      @Nonnull List<INodeExecutionData> getExecutionDataForNode(@Nonnull WorkflowNode node)
      Each node may provide additional data via IWorkflowExecutor.provideExecutionData(WorkflowNode, INodeExecutionData) that is available while the node is executed. Custom logic may make use of this data to provide different behavior depending on the currently executed nodes.
      Parameters:
      node - Node for which to get its data.
      Returns:
      The data associated with the node, or empty when no data is available. The list is read-only and cannot not be modified.
      Since:
      8.2.0

    • getExecutionDataForNode

      @Nonnull default <T extends INodeExecutionData> Iterable<T> getExecutionDataForNode(@Nonnull WorkflowNode node, @Nonnull Class<T> type)
      Same as getExecutionDataForNode(WorkflowNode), but filters the results to the given type.
      Type Parameters:
      T - Type of the node data to return.
      Parameters:
      node - Node for which to get its data.
      type - Desired type of the node data to return.
      Returns:
      The data associated with the node, or empty when no data is available.
      Since:
      8.2.0

    • getFormElementFieldValueContext

      Map<String,Integer> getFormElementFieldValueContext()
      Looks in the getExecutionDataForCurrentNodeStack(Class) for IFormElementFieldValueContextData and returns a map with the repetition index for each field name within a context. When multiple contexts exist for a field name, the closest context relative to the currently executed is used.
      Returns:
      A mapping between the name of each repetition context and the corresponding repetition index.
      Since:
      8.2.0

    • getFormElementRepetitionContext

      Map<String,Integer> getFormElementRepetitionContext()
      Looks in the getExecutionDataForCurrentNodeStack(Class) for IFormElementRepetitionContextData and returns a map with the repetition index for each repeated field name. When multiple contexts exist for a field name, the closest context relative to the currently executed is used.
      Returns:
      A mapping between the name of each repetition context and the corresponding repetition index.
      Since:
      8.2.0

    • getLatestException

      @Nullable NodeThrewException getLatestException(int index)
      Gets the latest exception that occurred during the current workflow execution. An index of 0 returns the most recent exception, an index of 1 returns the exception before that, and so on.

      There is also getCurrentException, which gets an exception from the exception stack. Certain workflow elements may push exceptions to the stack, such as an error handler block (try-catch). However, the exception will be popped from the stack when the workflow element completes. This means that the exception is not available in an action that executes after that workflow element has completed. This method effectively inspects all actions that were executed so far, finds the latest action that threw, and returns that exception.

      Parameters:
      index - The index of the exception to retrieve. 0 for the latest, 1 for the one before that, etc. Indices that are larger than the maximum allowed index are capped to the maximum allowed index. If the index is negative, adds the size of the exceptions to it, i.e. -1 returns the oldest exception, -2 the second oldest, etc.
      Returns:
      The exception at the given index, or null if no exception exists at that index.
      See Also:

    • getResultForNode

      @Deprecated @Nullable default IWorkflowNodeResult getResultForNode(@Nonnull WorkflowNode node)
      Deprecated.
      Use getDeclaredSuccessValuesForNode(node).getLast().
      Finds the latest result for the given node. When no result exists, this returns an empty INormalCompletionResult instead of null. Use hasResultForNode(WorkflowNode) to check whether a result exists.
      Parameters:
      node - A node for which to retrieve the result.
      Returns:
      The result that was obtained when the node was executed, never null. When no result is available, an empty result is returned. When the node was executed multiple times (such as when placed in a loop), the latest result is returned.
      See Also:

    • getResultsForNode

      @Deprecated @Nonnull default List<IWorkflowNodeResult> getResultsForNode(@Nonnull WorkflowNode node)
      Deprecated.
      Use getDeclaredSuccessValuesForNode(node).getAllFlat(getCurrentLoopIndex()).
      Finds all results for the given node. A node may be executed multiple times when placed inside a loop.
      Parameters:
      node - A node for which to retrieve the result.
      Returns:
      All results that were obtained when the node was executed. When the node was executed multiple times, returns the results in the order of the individual executions. Do not attempt to modify this list.
      See Also:

    • getTriggerData

      @Nullable Object getTriggerData(@Nullable String path)
      Each trigger can provide a set of data that will be available when the task is executed. The data can be a JSON like object with nested objects and arrays. This method finds the data at the given JSON path, if it exists.
      Parameters:
      path - Optional JSON path to access, e.g. button[0].name. If null or empty, the root value is returned.
      Returns:
      The value at the given path. null when the trigger provides no such data.

    • getTriggerFiles

      IWorkflowFileValue getTriggerFiles()
      Each trigger can provide a set of files that will be available when the task is executed. This method returns the files provided by the trigger.
      Returns:
      The files provided by the trigger. null when the trigger provides no files.

    • hasExecutionDataForNode

      boolean hasExecutionDataForNode(WorkflowNode node)
      Each node may provide additional data via IWorkflowExecutor.provideExecutionData(WorkflowNode, INodeExecutionData) that is available while the node is being executed. Custom logic may make use of this data to provide different behavior depending on the currently executed nodes.
      Parameters:
      node - Node for which to check if data is present.
      Returns:
      Whether data associated with the node, or null when no data is available.
      Since:
      8.2.0

    • hasResultForNode

      boolean hasResultForNode(@Nonnull WorkflowNode node)
      Parameters:
      node - A WorkflowNode to check.
      Returns:
      Whether a result exist for the given node, i.e. whether it was executed or not.
      See Also:

    • popException

      @Deprecated void popException()
      Deprecated.
      Use IWorkflowExecutor.popException()
      Pops the exception on top of the exception stack, see getException(int). This method should only be used by workflow nodes that represent a try-catch block.

    • pushException

      @Deprecated void pushException(@Nonnull NodeThrewException e)
      Deprecated.
      Use IWorkflowExecutor.pushException(NodeThrewException)
      Pushes the given exception to the exception stack, see getException(int). This method should only be used by workflow nodes that represent a try-catch block.
      Parameters:
      e - Exception to push to the stack.