Please enable JavaScript to view this site.

Altova FlowForce Server 2020 Advanced Edition

This example shows how to add error handling to a simple job that lists the contents of a directory. More specifically, it shows you how to configure FlowForce Server as follows:


Whenever the job fails to execute due to any reason, send an email notification to a named recipient.

Whenever the job execution finishes, regardless of the execution status, log the job internal ID to a file on the local system.


In FlowForce Server terms, in this example you create a protected block with two error handling conditions: "On Error" and "Always" (each will handle one of the scenarios mentioned above).



Required licenses: FlowForce Server

FlowForce Server is running at the configured network address and port (see Setting the Network Address and Port)

The FlowForce Server mail settings have been configured (see Setting the Mail Parameters)

You have a FlowForce Server user account with permissions to one of the containers (by default, the /public container is accessible to any authenticated user).



This example uses FlowForce Server expressions, which are required to handle the job return values. To understand this example better, you might want to get familiar with FlowForce Expressions.

Although this example uses Windows paths and commands, you can still test it on other operating systems, if you adapt the paths and the commands accordingly.


Creating the job

1.On the machine where FlowForce Server runs, create a directory where the job output will be saved. This can be, for example, C:\FlowForce, or a similar path. Note that your user account on the operating system must have read and write rights for this directory.

2.Log in to the FlowForce Server Web administration interface, open the /public container, and then click Create Job. Next, enter a name and, optionally, a description for the Web service you are creating.

3.Under "Execution Steps", click new error/success handling step.

4.Under "Execute with error/success handling", click the add button, and choose to add a new execution step, with the following settings:


Execute function

Browse for the /system/shell/commandline function.


Enter the following shell command:


dir /s


On Windows, this command lists recursively the contents of a directory. If the directory is not specified like in this case, then it lists the contents of the working directory (see below).

Abort on error

Leave this option as is.

Working directory

Enter the path to the working directory created previously, for example C:\FlowForce


5.Under the "On error" condition, click the add button and choose to add a new execution step, with the following settings:


Execute function

Browse for the builtin_function/system/mail/send function.


Enter the email address of the sender, for example flowforce@localhost. Leave this field empty if you have configured the mail settings from the administration page.


Enter your email address.


Enter the subject of the notification email as follows:


Job {instance-id()} has failed


The part between curly braces is a FlowForce expression which calls the instance-id  function to get the unique ID of the current (failed) job instance.

Message body

Type the following:


Exit Code: {string(exitcode(failed-step()))}

Standard Error: {content(stderr(failed-step()))}

Error message: {error-message(failed-step())}


The parts between curly braces are two FlowForce expressions. These expressions get the erroneous output and convert it to a string that will be the body of the email:


The failed-step function returns the result of the failing step. This is an abstract FlowForce type that, in order to become more useful, must be supplied as argument to the exitcode, stderr , or error-message functions, see below.

The exitcode function gets the actual exit code of the error from the result, as a number, assuming that there is an exit code.

The stderr function gets the standard error output of the error from the result, as a stream, assuming that there is standard error output.

The error-message function gets the text of the FlowForce error message as it appears in the log. It may also return an empty string if there is no error or if it is not technically possible to retrieve the error text.

The string function converts the numeric exit code to a string (this must be done because the body of the email is of string type).

The content function converts the error output from a stream to a string.


The exitcode and stderr functions return a value only if execution produces an exit code and error output, respectively. This is typically the case for errors such as the ones produced by the command line. The error-message function is just for informational purpose and is not guaranteed to return the text of the error for every possible job configuration and error condition encountered.


6.Click new error/success handler, and then select Always.

7.Under the "Always" condition, click the add button and choose to add a new execution step, with the following settings:


Execute function

Browse for the builtin_function/system/shell/commandline function.


Enter the following shell command:


echo {instance-id()} >> JobLog.txt


On Windows, this command writes the job ID to a file called JobLog.txt. If the file contains data, the new text will be added after the existing data.

Working directory

Enter the path of the directory created previously (for example, C:\FlowForce).


At this stage, the job should look as follows (provided you did not use different paths or shell commands).


8.Under "Triggers", add a Timer trigger that will fire the job. Make sure to adjust the date, time, and time zone as required.


9.Under "Credentials", select an existing credential record or specify a local credential.

10.Click Save.



At this stage, you have completed the job configuration, and you might want to do one of the following:


To test the "Always" condition, edit the trigger timer and wait for the trigger condition to be met. Whenever the trigger condition is met, a new job ID is appended to the contents of the JobLog.txt file.

To test the "On Error" condition, change the parameters of the first step to some deliberately incorrect value (perhaps, by mistyping the shell command, or by specifying a path that does not exist). If this case, FlowForce Server will send an email to the address specified in the recipient field of the "On Error" handler. For example, the e-mail could look as follows if you mistyped the dir command:


As stated above, the error functions used in this example are not guaranteed to return a value for each and every possible job configuration. Therefore, the level of detail provided by the e-mail depends on your job configuration and the kind of error encountered, and it should not be expected that the Exit Code, Standard Error, and Error message e-mail fields always contain text. The most authoritative reference for the cause of the error is the FlowForce Server log.


To view more details about the outcome of the job (be it success or failure), refer to the job log.

© 2020 Altova GmbH