Adding correlations for error messages

Error correlator

The error correlator facility can be used to provide user-friendly or helpful summaries of encountered errors when using APIs or making network requests in Zowe Explorer. Developers can provide correlations to these error messages to offer tips and additional resources for resolving the error.

Correlation structure

export interface ErrorCorrelation {
  /**
   * An optional error code returned from the server.
   * @type {string}
   */
  errorCode?: string;
  /**
   * One or more patterns to check for within the error message.
   * @type {ErrorMatch | ErrorMatch[]}
   */
  matches: ErrorMatch | ErrorMatch[];
  /**
   * Human-readable, brief summary of the error that was encountered.
   * @type {string}
   */
  summary: string;
  /**
   * Troubleshooting tips for end users that encounter the given error.
   * @type {string[]}
   */
  tips?: string[];
  /**
   * Error-specific, external resources for users to help with resolution during troubleshooting.
   */
  resources?: ExternalResource[];
}

Adding to the correlator

Access the ErrorCorrelator instance from the ZoweExplorerExtender API exported by Zowe Explorer.

Call the ErrorCorrelator.addCorrelation function with a profile type, API type, and error correlation to add it into the instance.

For example:

const zeApi = ZoweVsCodeExtension.getZoweExplorerApi();
const extenderApi = zeApi.getExplorerExtenderApi();

const errorCorrelator = extenderApi.getErrorCorrelator();
errorCorrelator.addCorrelation(ZoweExplorerApiType.Mvs, "zosmf", {
  errorCode: "500",
  matches: ["Example substring match against error"],
  summary: "Summary of error",
  tips: ["helpful tip for users 1", "helpful tip for users 2"],
  resources: [
    { href: "https://example.com", title: "Example external resource link" },
  ],
});

Using the correlator

A correlation is used if at least one match is made between the error message and list of matches provided by that correlation.

• To get a correlation for an error, call the ErrorCorrelator.correlateError function and pass the original error.
• To display a correlated error, call the ErrorCorrelator.displayCorrelatedError function and pass the correlated error with any desired options.
• To find the correlated error and display it at the same time, call ErrorCorrelator.displayError and pass the original error with any desired options.

Where tips and resources are used

The Troubleshoot option is offered when displaying errors using the correlator. If clicked, a webview opens, presenting the error code, summary of the error, and a section for full error details.

Below this, tips and resources for the given correlation are listed. If unavailable, a default set of resources is listed, such as the Open Mainframe Project's Slack channel as well as the Zowe Explorer GitHub repository. Extenders can provide links to their repositories or documentation sites within the correlations.