External Widget API Reference

An API abstraction which provides an interface for a frontend application running inside an IFrame within codebeamer to communicate with the codebeamer UI via the postMessage API of the browser.

(constructor)

constructor(window: MessageBroker, widgetId: string, origin: string | OriginPolicy);

Initializes an API instance.

Parameters:

• window - A window-like instance which provides the postMessage interface. Usually just simply window.
• widgetId - A unique string to represent this widget API instance.
• origin - Either the origin / host of the codebeamer instance as a string, a custom OriginPolicy instance to use when sending / receiving cross-window postMessage messages, or the "*" string literal if the host is unknown. In the latter case, the origin will not be checked and information leak may occur if the widget is loaded in a malicious environment.
• Interface OriginPolicy- Defines callbacks to customize origin checking behavior.
  • checkOrigin(origin: string): boolean; - is called each time a response is received for a particular API call. Should only return trueif the host is a codebeamer instance, and it is trusted. An example implementation could use a whitelist.
    • origin - The origin / host of the window where the response is received from.
  • provideOrigin(): string; - is called to provide the origin / host of codebeamer each time an API function is called. The underlying postMessage message will only be delivered if the parent window of the widget matches this.

authenticate

authenticate(): Promise<AuthenticatePayload>;

Request a JWT token for the currently logged-in user. The token may expire.

• Interface AuthenticatePayload:
  • token: string - A JWT token for the active user.

getBaseURL

getBaseURL(): Promise<GetBaseURLPayload>;

Requests the Swagger API's base URL, including the proper context. Ex.: https://codebeamer.com/cb/api

• Interface GetBaseURLPayload:
  • baseURL: string - BaseURL of the Swagger API.

getConfig

getConfig(): Promise<GetConfigPayload>;

Requests the user provided configuration for this particular widget instance.

• Interface GetConfigPayload:
  • config: any - Arbitrary user configuration.

getSelectedItem

getSelectedItem(): Promise<GetSelectedItemPayload>;

Queries which tracker item is selected on the codebeamer UI. May only work on certain pages. It may return undefined if there is no tracker item selected.

• Interface GetSelectedItemPayload:
  • itemId: string | undefined - ID of the currently selected Tracker Item, if applies. undefined otherwise.

onSelectedItemChange

onSelectedItemChange(callback: (item: string) => void): () => void;

Registers a callback to be called whenever the user selects a tracker item on the codebeamer UI. May only work on certain pages.

Parameters:

• callback - A function to be called when the selection changes.

reloadItem

reloadItem(config: ReloadItemPayload): Promise<void>;

Asks codebeamer to reload a Tracker Item if it is present on the UI. May only work on certain pages.

• Interface ReloadItemPayload:
  • itemId: string - Tracker Item ID to reload.

resize

resize(height: number): Promise<void>;

Asks codebeamer to resize the IFrame window vertically inside the UI. Only works on the Tracker Item Details page.

Parameters:

• height - Preferred height in browser pixels.