getWebclientApi()

dashlet.getWebclientApi() gives typed access to the seven webclient endpoints. The handle is fully asynchronous (the wire is an asynchronous postMessage exchange): every method returns a promise. Both handle accessors (getWebclientApi / getRichClientApi) are available per environment and fail hard — a missing environment is never a silent null fallback.

1. Signature

const web: WebclientApi = dashlet.getWebclientApi();

The accessor is cached: every repeated call returns the same instance (identity via ===). The handle methods read the wire per call — they delegate into the same dispatch core as the facade, so wire posts, normalization, fire-and-forget behavior, correlation, and timeouts stay exactly identical.

2. Endpoints

Method Wire post (webclient) Resolution

openIndexData(options)

openIndexData with the array slot [inNewTab, mode, objectId, objectTypeId] (correlated)

host boolean result (`boolean

undefined`).

openObject(objectId)

openIndexData with [false, 'view', objectId] (read-only, correlated)

host boolean result (`boolean

undefined`).

openLocation(options)

openLocation with the 5-slot array [inNewTab, objectId, objectTypeId, parentId, parentTypeId]

undefined (void, host reply awaited).

openHitListByIds(options)

openHitListByIds with the OBJECT slot; inNewTab = false → fire-and-forget (no msgId), true → correlated

undefined; fire-and-forget calls resolve immediately.

refreshHitListObjects(ids)

refreshHitListObjects — the id array as ONE argument (correlated)

host boolean result (`boolean

undefined`).

getSelectedObjects()

getSelectedObjects with an empty parameter array (correlated)

normalized selection entries (SelectedObjectRef[]).

resetSessionTimeout()

resetSessionTimeout with an empty parameter array (correlated)

undefined (void, host reply awaited).

The parameter shapes and the exact per-environment behavior are identical to the facade methods — see e.g. openIndexData() and openHitListByIds().

3. call() — the documented escape hatch

web.call('myHostEndpoint', [1, 2]) posts any host endpoint name on the wire as [method, params, { msgId }] — the host validates the origin of the inbound call (a different environment is never reached), the reply is correlated through the unguessable msgId, and the call is bounded by the configured response timeout. The promise resolves with the host reply and rejects on a host { error } payload or on a missing reply (bounded TimeoutError). The cataloged endpoints (table above) are the preferred path — call is the documented fallback for uncataloged endpoints.

4. Notes

  • No has() — the webclient host is not introspectable from the dashlet (there are no local bridge members to probe); endpoint availability is a question of the host setup, not of the library.

  • Async only — in contrast to getRichClientApi (synchronous, raw bridge), the webclient wire is asynchronous; every method is promise-based.

  • Standalone — in the standalone environment (no webclient host) the accessor is not available and throws the wrong-environment error (see Errors). While still detecting (environment not yet resolved) it throws the await-init error instead (see Errors).

5. Errors

  • Error('dashlet destroyed') — the dashlet was destroyed before the call (accessor and handle methods).

  • TypeError: Dashlet.getWebclientApi(): the environment is not resolved yet - await the dashlet.init promise first — the call happened before the environment was resolved.

  • TypeError: Dashlet.getWebclientApi(): the webclient API handle is only available in the webclient environment (current: …) — call in the wrong environment (the current value is named).

  • TimeoutError — bounded no-reply in standalone, or a host that never answered within timeoutMs.

  • The host { error } payload — when the host reports a failure on a method call.