Error Handling

JS7 - JavaScript Jobs apply error handling at job level as offered by the JavaScript language.

For error handling at workflow level using JS7 - Workflow Instructions see JS7 - How to apply error handling.

Download workflow implementing JavaScript error handling (upload .json): pdJavaScriptErrorHandling.workflow.json

Terminating Job successfully

There are no specifics for successful termination of a JavaScript job:

class JS7Job extends js7.Job {

	processOrder(js7Step) {
    	// do some stuff  
		return;
        // ...
    }
}

Explanation:

• As for every JavaScript function the return statement can be used to leave the processOrder() method prematurely.
• If the return statement is not used then the job terminates successfully when leaving the processOrder() method.

Terminating Job successfully with warning due to return code

JavaScript Jobs can be configured to continue in case of warnings and to send a JS7 - Notifications:

• JavaScript Jobs can be configured to consider a number of return codes that raise warnings.
• Any return codes will not fail the job but will result in a notification if specified with the job configuration.
  
  

The implementation of a job that specifies a return code looks like this:

class JS7Job extends js7.Job {

	processOrder(js7Step) {
      	// do some stuff
      
        js7Step.getLogger().warn('warning occurred');
        js7Step.getOutcome().setReturnCode(1);
		return;
    }
}

Explanation:

• The getLogger().warn() method creates log output that qualifies as a warning.
• The getOutcome().setReturnCode() method is used to specify a return code:
  • Setting the return code in a JavaScript Job does not raise an error. 
  • Return codes can be checked in a subsequent job or JS7 - If Instruction.
  • If the job configuration specifies one or more Return Codes on Warning and if the job's return code matches one of the values then a notification is created. Otherwise the job will terminate successfully without a warning.
• For details see JS7 - Job API.

If a warning is created then the Monitor->Order Notifications view will display the warning for a job like this:

Optionally notifications for warnings are sent by mail if configured by JS7 - Notifications.

Terminating Job successfully with warning due to output to stderr

This scenario applies to a situation when an unsolicited error occurs that results in output to to the stderr channel, for details see JS7 - How to detect job errors and warnings

• No exception is raised in JavaScript, but some statement fails and writes to stderr. In this situation the job continues and might terminate successfully.
• The JS7 - Job Instruction offers the Warn on output to stderr option: if any output in the stderr channel is detected then the job is considered to terminate with warnings.

In the Configuration->Inventory view users specify the related option from the Job Options tab like this:

A job that writes output to the stderr channel can be implemented like this:

class JS7Job extends js7.Job {

	processOrder(js7Step) {
      	// do some stuff
      
        js7Step.getLogger().error('some error occurred');
		return;
    }
}

Explanation:

• No error is raised in this example. Instead the getLogger().error() method is used to write output to stderr.
• Similarly any other JavaScript statements can create output in the stderr channel.

Terminating Job with error

The typical error handling for JavaScript applies:

• If an exception is raised then this will cause the job to terminate immediately with error. This applies to unsolicited errors and to exceptions raised by a throw statement.
• Users are encouraged to apply try .. catch .. finally statements for better control of error handling.

class JS7Job extends js7.Job {

	processOrder(js7Step) {
        try {
            js7Step.getLogger().info( '.. try: do some stuff')
			throw 'error occurred, exiting job';
        } catch (e) {
          	js7Step.getLogger().info('.. catch: do some error handling')
            throw e;
        } finally {
          	js7Step.getLogger().info('.. finally: do some cleanup such as closing database connections')          
        }
    }
}

Terminating Job with error due to output to stderr

This scenario applies to a situation when an unsolicited error occurs that results in output to to the stderr channel, for details see JS7 - How to detect job errors and warnings

• No exception is raised in JavaScript, but some statement fails and writes to stderr. In this situation the job continues and might terminate successfully.
• The JS7 - Job Instruction offers the Fail on output to stderr option: if any output in the stderr channel is detected then the job is considered being failed.

In the Configuration->Inventory view users specify the related option from the Job Options tab like this:

A job that writes output to the stderr channel can be implemented like this:

class JS7Job extends js7.Job {

	processOrder(js7Step) {
      	// do some stuff
      
        js7Step.getLogger().error('some error occurred');
		return;
    }
}

Explanation:

• No error is raised in this example. Instead the getLogger().error() method is used to write output to stderr.
• Similarly any other JavaScript statements can create output in the stderr channel.

Further Resources

• JS7 - Job API
• JS7 - JavaScript Jobs