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 {@code sfcc.app..checkConnectionHealth} convention — for example, {@code 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 {@code unknown} when the hook times out, throws, or returns {@code null}. {@code dw.system.HookMgr#callHook} itself rethrows any exception raised by the hook script — the {@code unknown} translation is applied by the BM endpoint dispatcher, not by {@code HookMgr}.

The BM endpoint interprets the returned Status as follows: {@code Status.OK} → healthy; {@code Status.ERROR} with code DEGRADED → degraded; {@code Status.ERROR} with code UNHEALTHY (or any other ERROR code) → unhealthy. A {@code null} return is treated as {@code 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 {@code dw.web.Resource} from the cartridge's resource bundles (e.g. files under {@code cartridge/templates/resources/}) instead of hard-coding English. The BM endpoint dispatcher invokes the hook in the BM session locale, so {@code 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 {@code null} return is treated as {@code unknown} by the BM endpoint.