@itentialopensource/error-handling NPM

Error Handling

Overview
Requirements
Installation
Demonstration
Usage
- Reverting to a Previous Task
Additional Information

Overview

The Error Handling artifact defines an Itential certified way to show errors, warnings and other events within workflows to network engineers. Based on the event, a user can decide if the execution of the workflow should be cancelled or if the last step should be re-tried, potentially with different input data.

Requirements

The Error Handling artifact is compatible with the following versions of the Itential Automation Platform:

^2022.1

Installation

Please ensure that you are running a supported version of the Itential Automation Platform (IAP) as listed above in the requirements section in order to install the Error Handling artifact. If you do not currently have App-Artifacts installed on your server, please download the installer from your Nexus repository. Please refer to the instructions included in the App-Artifacts README to install it.

Error Handling can be installed from within App-Artifacts. Simply search for error-handling and click the install button as shown below:

After the notification pops up to inform you that the artifact has been installed, you should be able to navigate to Automations within Operations Manager and verify that the Error Handling Demo Operations Manager item has been installed.

Alternatively, you may clone this repository and run npm pack to create a tarball which can then be installed via the offline installer in App-Artifacts. Please consult the documentation for App-Artifacts for further information.

Demonstration

The Error Handling artifact is accompanied by an example workflow to demonstrate different use cases. To view the example, run the Error Handling Demo item from Operations Manager.

For the demonstration, you will be asked whether you want to explore usage for the sunny day path (Success) or for errors and warnings (Failure).

It is recommended to explore the Failure path, and to see how a workflow can revert to a previous task on retry after failure.

Usage

The Error Handling artifact can be run as a child job from within your primary workflow wherever there is a need for handling the exit state of a previous task and displaying the status to the user.

From within your workflow, choose the childJob task from WorkFlowEngine and add it to the canvas.

Double click the task to edit the details, then search for and select IAP Artifacts Error Handling as the workflow:

You must also supply two job variables, status and severity:

status: The status is a string which should be indicative of the error state and will be displayed to the user. This could be the returned status code from a REST call, for example, or a custom message you supply.
severity: The severity is the level of error, and must be one of the following values:
- fatal: A fatal error is one which would prevent your workflow from reaching completion. The user will be prompted to either allow a retry or abort the job. Please see the section below about reverting to an earlier task to retry.
- warning: A warning will alert the user and allow them to proceed or abort the job. The warning level should be used for non-critical failures which will not hinder the completion of the job, but which should be made aware to the user.
- success: This can be used to confirm that a given task or series of tasks completed successfully. No alert is shown to the user. Note that the severity level can also be supplied dynamically, and this can simply be used as a check before proceeding down a given path.

The Error Handling artifact will always resolve to a job variable called response. The response variable will be a string with the value of one of the following:

success: This indicates either a successful status, or that the user has selected to proceed with warning.
retry: This indicates the user has selected to retry. Please see the section below.
failure: This indicates the user has chosen to abort the job.
error: This indicates that an invalid severity level was passed in. This is merely a sanity check, and the response should never be an error.

Reverting to a Previous Task

Upon entering a state of fatal error, the user will be prompted to either retry or abort the job. It is a good idea to give the user the option to retry and revert to a prior state. As mentioned in the previous section, the response job variable from the Error Handling artifact will have the value of retry if the user has chosen to retry.

To perform this check, simply place an evaluation task after the childJob:

From here, add a success edge to revert back to a prior task in the workflow, and add a failure edge connecting to the end point of the workflow.