Please enable JavaScript to view this site.

Altova FlowForce Server 2020 

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 have a look at the instance-id, stderr, stdout, and failed-step expression functions.

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 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()))}


The parts between curly braces are two FlowForce expressions. These expressions essentially 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 or stderr functions, see below.

The exitcode function gets the actual exit code of the error from the result, as a number. Recall that this step is inside an On Error handler, so we expect that there is an exit error code (and possibly also error output). Had this been an On Success handler or a standard step, result would need to be processed in a different way (for example, as described in Create a Job from a StyleVision Transformation).

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

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.


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 which runs every N minutes (for example, 2 minutes). 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 (see Credentials).

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, 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 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. Additionally, it will log the job ID in the JobLog.txt file, since this behaviour has been configured to happen in the "Always" condition.

To see whether the job executed successfully, refer to the job log (see Viewing the Job Log).

© 2019 Altova GmbH