External Widget API Reference
This topic describes an API abstraction which provides an interface for a frontend application running inside an IFrame within Codebeamer to communicate with the Codebeamer UI through the postMessage API of the browser.
(constructor)
constructor(window: MessageBroker, widgetId: string, origin: string | OriginPolicy);
This initializes an API instance using the following parameters:
• window—A window-like instance which provides the postMessage interface. Usually specified as window.
• widgetId—A unique string to represent this widget API instance.
• origin—Either the host of the Codebeamer instance as a string, a custom OriginPolicy instance to use when sending and receiving cross-window postMessage messages, or the "*" string literal if the host is unknown. If the host is unknown , the origin is not checked and an information leak can occur if the widget is loaded in a malicious environment.
• Interface OriginPolicy—Defines callbacks to customize origin checking behavior.
◦ checkOrigin(origin: string): boolean;—Called each time a response is received for a particular API call. Return true only if the host is a Codebeamer instance, and it is trusted. An example implementation could use an allow list.
▪ origin—The host of the window from which the response is received.
◦ provideOrigin(): string;—Called to provide the host of Codebeamer each time an API function is called. The underlying postMessage message is only be delivered if the parent window of the widget matches this parameter.
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. For example, https://codebeamer.com/cb/api
• Interface GetBaseURLPayload:
◦ baseURL: string—The BaseURL of the Swagger API.
getConfig
getConfig(): Promise<GetConfigPayload>;
Requests the user provided configuration for this widget instance.
• Interface GetConfigPayload:
◦ config: any—Arbitrary user configuration.
getSelectedItem
getSelectedItem(): Promise<GetSelectedItemPayload>;
Queries which tracker item is selected on the Codebeamer UI. May work only on certain pages. It may return undefined if there no tracker item is 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 user interface. May work only on certain pages.
Parameters:
• callback—A function to be called when the item selection changes.
reloadItem
reloadItem(config: ReloadItemPayload): Promise<void>;
Asks Codebeamer to reload a tracker item if it is present on the user interface . May work only 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 user interface .Works only works on the tracker item details page.
Parameters:
• height—Preferred height in browser pixels.