Host API

alert

This method allows you to send an alert message to YouTrack from within an app.

Here you can find a sample code that uses this method:

const host = await YTApp.register();
host.alert('Hello world');

fetchYouTrack

This method lets the app use the YouTrack REST API.

Here you can find a sample code that uses this method:

const host = await YTApp.register();
const user = await host.fetchYouTrack(`users/${YTApp.entity.id}?fields=id,login,name`);

Here's a sample that contains optional query parameters:

const ytResponse = await host.fetchYouTrack('users', {query: {fields: 'id,login,email'});

fetchApp

This method lets the app communicate with the custom HTTP handler and invoke its methods. The fetchApp method is similar to the fetchYouTrack method, but has an additional scope parameter. This parameter lets you indicate whether the request should be made to a scoped or global endpoint.

The fetchApp method parses JSON and returns a ready-to-use response object.

Here you can find a sample code that uses this method:

const host = await YTApp.register();
const appResponse = await host.fetchApp('backend/demo', {scope: true});

Here's a sample GET request with query parameters:

const appResponse = await host.fetchApp('backend/demo', {query: {key: '12345', count: 20, filter: true});

Here's a sample POST request with body:

const appResponse = await host.fetchApp('backend/demo', {method: 'POST', body: {test: 'test'}});

requestParams

The requestParams object is basically an extension of the requestInit object used to customize requests in the Fetch API. In addition to the base properties supported by the requestInit object, requestParams supports the following supplemental properties:

const query = {
    key: '12345',
    shelterID: 'abc00',
    count: 20,
    animals: true
};

// appResponse is a parsed JSON:
const appResponse = await host.fetchApp('backend/demo', {scope: true});
console.log('test', appResponse.test);

setTitle

setTitle(label: string, ?labelUrl: string): void

Sets the text displayed in the widget header. If a value is specified for the labelUrl parameter, the text is set as a link to the target URL.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

setLoadingAnimationEnabled

setLoadingAnimationEnabled(isEnabled: boolean): void

Toggles the image rotation animation for the widget reload icon. Call this method when the widget populates data from a remote server to indicate that a process is running in the background.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

enterConfigMode

enterConfigMode(): void

Invokes configuration mode. When in configuration mode, the visual presentation of the widget changes to indicate that its settings can be updated. The refresh icon is also hidden.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

exitConfigMode

exitConfigMode(): void

Exits configuration mode.

setError

setError(e: Error): void

Sets an error state in the widget, displaying an error message or taking other error-handling actions.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

clearError

clearError(): void

Clears any previously set error state in the widget.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

readCache

readCache(): Promise<unknown>

Reads data previously stored in the cache. Returns a promise that resolves to the cached data.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

storeCache

storeCache(data: unknown): Promise<Void>

Stores any object in the client-side cache. Use this method to store populated data locally and display it immediately in the widget, then refresh it from the server. Returns a promise that resolves when the data is successfully stored.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

readConfig

readConfig(): Promise<unknown>

Reads the widget configuration data. Returns a promise that resolves to the configuration data.

The schema for the config object must be declared in the settingsSchemaPath property of the widget manifest. Any undeclared payloads are ignored.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

storeConfig

storeConfig(config: unknown): Promise<Void>

Stores configuration data for the widget. Exits configuration mode if configuration mode is active.

The schema for the config object must be declared in the settingsSchemaPath property of the widget manifest. Any undeclared payloads are ignored.

Returns a promise that resolves when the configuration data is successfully stored.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

downloadFile

downloadFile(serviceID: string, relativeURL: string, requestParams: unknown, fileName?: string): Promise<void>

Downloads a file from a specified service.

Returns a promise that resolves when the file is successfully downloaded.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

fetchHub

fetchHub(relativeURL: string, requestParams: RequestParams): unknown

Fetches data from the Hub service that is connected to or built into YouTrack. Similar to the fetch method but specifically designed for Hub services.

Returns the fetched data. The return type depends on the information retrieved from the service.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

For example:

CustomWidgetAPILayer.fetchHub('api/rest/users/me?fields=name,login,profile(avatar(url))')
                .then(response => console.log(response));

The following example shows how to use this method in a POST request:

host.fetchHub('api/rest/users/me', {
                method: 'POST',
                body: {favoriteProjects: []}
                })
                .then(response => console.log(response));

alert

alert(...args: Parameters<(typeof AlertService)['addAlert']>): void

Displays a system alert in the lower left corner of the page.

This is a wrapper for the AlertService component from the JetBrains Ring UI component library.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.

For example:

host.alert('Hello world', 'success', 5000)

removeWidget

removeWidget(): void

Removes the embedded widget from the user interface.

Only available for widgets that use the DASHBOARD_WIDGET pr MARKDOWN extension points.