Class ConnectionHealthCheckHooks

• TopLevel.Object
  • dw.commerceapps.hooks.ConnectionHealthCheckHooks

This interface represents the optional connection health check extension point for Commerce App providers. It lets a Commerce App report whether its external service is reachable and operating correctly so Business Manager can surface health on the app’s installation details. Implementing this hook is not required — apps that do not depend on an external connection may omit it entirely. When omitted, Business Manager does not display health status on the app’s tile.

A function must be defined inside a JavaScript source and must be exported. The script with the exported hook function must be located inside a site cartridge. Inside the site cartridge a ‘package.json’ file with a ‘hooks’ entry must exist.

1"hooks": "./hooks.json"

The hooks entry links to a json file, relative to the ‘package.json’ file. This file lists all registered hooks inside the hooks property:

1"hooks": [
2     {"name": "sfcc.app.tax.checkConnectionHealth", "script": "./checkConnectionHealth.js"}
3]

A hook entry has a ‘name’ and a ‘script’ property.

• The ‘name’ contains the extension point, the hook name.
• The ‘script’ contains the script relative to the hooks file, with the exported hook function.

The hook is registered per app domain using the sfcc.app.<domain>.checkConnectionHealth convention — for example, sfcc.app.tax.checkConnectionHealth for a tax app.

IMPORTANT: This hook should only be implemented and registered by Commerce Apps (applications installed via the Commerce App framework with a CAP file). It is not intended for custom merchant cartridges or storefront implementations.

This class does not have a constructor, so you cannot create it directly.

assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values

checkConnectionHealth(): Status

Reports the current health of the Commerce App's connection to its external service. The platform applies a CPU timeout, so implementations should be lightweight and time-bounded.

The Business Manager connection-health endpoint that invokes this hook reports unknown when the hook times out, throws, or returns null. dw.system.HookMgr#callHook itself rethrows any exception raised by the hook script — the unknown translation is applied by the BM endpoint dispatcher, not by HookMgr.

The BM endpoint interprets the returned Status as follows: Status.OK → healthy; Status.ERROR with code DEGRADED → degraded; Status.ERROR with code UNHEALTHY (or any other ERROR code) → unhealthy. A null return is treated as unknown.

Use Status.addDetail(String, Object) with keys ConnectionHealthStatusCodes.DETAIL_MESSAGE and ConnectionHealthStatusCodes.DETAIL_REMEDIATION to provide structured information for the BM UI. DETAIL_REMEDIATION should describe actionable steps the merchant can take when the connection is degraded or unhealthy.

Both detail values are surfaced verbatim in Business Manager. To localize them for the BM admin's language, look up the strings via dw.web.Resource from the cartridge's resource bundles (e.g. files under cartridge/templates/resources/) instead of hard-coding English. The BM endpoint dispatcher invokes the hook in the BM session locale, so Resource.msg(...) resolves against the admin's language.

1var Resource = require('dw/web/Resource');
2var Status = require('dw/system/Status');
3
4exports.checkConnectionHealth = function () {
5    var status = new Status(Status.ERROR, 'DEGRADED');
6    status.addDetail('message', Resource.msg('healthcheck.degraded.message', 'taxapp', null));
7    status.addDetail('remediation',
8        Resource.msgf('healthcheck.degraded.remediation', 'taxapp', null, providerName));
9    return status;
10};

Returns:

• the connection health status. A null return is treated as unknown by the BM endpoint.