Add Error Handling to a Job

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Job Configuration Examples >

Add Error Handling to a Job

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).

 

Prerequisites

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).

 

Tips

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 (see Step Result Functions).
Although this example uses Windows paths and commands, you can still test it on other operating systems, if you change the paths and the commands accordingly.

 

 

Creating the job

1.On the machine where FlowForce Server runs, create a file called JobLog.txt (this file will be used in subsequent steps).
2.Log on to FlowForce Server and navigate to the container where you have permission to create new jobs (in this example we are using /public).
3.Click Create, and then select Create job.
4.Under Execution Steps, click the add button, and then select new error/success handling step.
5.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.

Command

Enter the following shell command:

dir /s

On Windows, this command lists recursively the contents of the working directory (see the next setting).

Working directory

Set the value to an existing location on the machine where FlowForce Server runs, for example c:\

 

6.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.

From

Enter the email address of the sender. Leave this field empty if you have configured the mail settings from the administration page.

To

Enter your email address.

Subject

Enter the subject of the notification email as follows:

Job {instance-id()} has failed

Message body

Enter the following FlowForce Server expression:

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

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

Standard Output: {content(stdout(failed-step()))}

For information about the purpose of each function used here, see Step Result Functions.

 

7.Click new error/success handler, and then select Always.
8.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 /system/shell/commandline function.

Command

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

Set the value to the directory where the JobLog.txt file created in previous steps is located. This must be an existing directory on the machine where FlowForce Server runs, for example c:\

 

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

ExxampleErrorHandling1

9.Under Triggers, add a Timer trigger which runs every N minutes (for example, 5 minutes).

ExxampleErrorHandling2

10.Under Credentials, select an existing credential record or specify a local credential (see Credentials).
11.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