Workspace API

This component allows you to access methods for programmatically controlling workspace tabs and subtabs in a Lightning console app. In Lightning console apps, records open as workspace tabs and their related records open as subtabs.

To access the methods, create an instance of the lightning:workspaceAPI component and assign an aura:id attribute to it.

1<lightning:workspaceAPI aura:id="workspace" />

This example opens a new tab displaying the record with the given relative URL in the url attribute when the button is clicked.

1<aura:component implements="flexipage:availableForAllPageTypes" access="global">
2  <lightning:workspaceAPI aura:id="workspace" />
3  <lightning:button label="Open Tab" onclick="{! c.openTab }" />
4</aura:component>

The button in the component calls the following client-side controller.

1{(
2    openTab : function(component, event, helper) {
3        var workspaceAPI = component.find("workspace");
4        workspaceAPI.openTab({
5            url: '#/sObject/001R0000003HgssIAC/view',
6            focus: true
7        });
8    },
9)}

This component supports the following methods. Most methods take only one argument, a JSON array of parameters. For more information on these methods, see the Console Developer Guide.

closeTab({tabId})

• tabId (string): ID of the workspace tab or subtab to close.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

focusTab({tabId})

• tabId (string): The ID of the workspace tab or subtab on which to focus.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

getAllTabInfo()

Returns a Promise. Success resolves to an array of tabInfo objects. The Promise will be rejected on error.

getFocusedTabInfo()

Returns a Promise. Success resolves to a tabInfo object. The Promise will be rejected on error.

getTabInfo({tabId})

• tabId (string): ID of the tab for which to retrieve the information.

Returns a Promise. Success resolves to a tabInfo object. The Promise will be rejected on error.

getTabURL({tabId})

• tabId (string): ID of the tab for which to retrieve the URL.

Returns a Promise. Success resolves to the tab URL. The Promise will be rejected on error.

isSubtab({tabId})

• tabId (string): ID of the tab.

Returns a Promise. Success resolves to true if the tab is a subtab, false otherwise. The Promise will be rejected on error.

isConsoleNavigation()

Returns a Promise. Success resolves to true if console navigation is present, false otherwise. The Promise will be rejected on error.

getEnclosingTabId()

Returns a Promise. Success resolves to the enclosing tabId or false if not within a tab. The Promise will be rejected on error.

openSubtab({parentTabId, pageReference, recordId, url, focus})

• parentTabId (string): ID of the workspace tab within which the new subtab should open.
• pageReference (object): Optional. A PageReference representing the content of the new subtab.
• recordId (string): Optional. A record ID representing the content of the new subtab.
• url (string): Optional. The URL representing the content of the new subtab. URLs can be either relative or absolute.
• focus (boolean): Optional. Specifies whether the new subtab has focus.

Returns a Promise. Success resolves to the tabId of the subtab. The Promise will be rejected on error.

openTab({pageReference, recordId, url, focus, overrideNavRules})

• pageReference (object): Optional. A PageReference representing the content of the new tab.
• recordId (string): Optional. A record ID representing the content of the new tab.
• url (string): Optional. The URL representing the content of the new tab. URLs can be either relative or absolute.
• focus (boolean): Optional. Specifies whether the new tab has focus.
• overrideNavRules (boolean): Optional. Specifies whether to override nav rules when opening the new tab.

Returns a Promise. Success resolves to the tabId of the workspace. The Promise will be rejected on error.

setTabIcon({tabId, icon, iconAlt})

• tabId (string): The ID of the tab for which to set the icon.
• icon (string): An SLDS icon key. See a full list of icon keys on the SLDS reference site.
• iconAlt (string): Optional. Alternative text for the icon.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

setTabLabel({tabId, label})

• tabId (string): The ID of the tab for which to set the label.
• label (string): The label of the workspace tab or subtab.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

setTabHighlighted({tabId, highlighted, options})

• tabId (string): The ID of the tab for which to highlight.
• highlighted (boolean): Specifies whether the new tab should be highlighted.
• options (object): Optional. Additional options that modify the appearance of the highlighted tab.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

disableTabClose({tabId, disabled})

• tabId (string): The ID of the tab for which to disable or enable close capabilities.
• disabled (boolean): Specifies whether the tab should have close capabilities disabled or enabled.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

refreshTab({tabId, includeAllSubtabs})

• tabId (string): ID of the workspace tab or subtab to refresh.
• includeAllSubtabs (boolean): Optional. If the tabId corresponds to a workspace tab, all subtabs within that workspace are refreshed. The default is true. Keep in mind that the first subtab has the same tabId as the workspace tab.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

generateConsoleURL({pageReferences})

• pageReferences (array): An array of PageReferences to a workspace or workspace and subtabs to generate a URL for.

Generates a URL to a workspace or workspace and subtabs. Returns a Promise. Success resolves to the active tab id. The Promise will be rejected on error.

openConsoleURL({url, focus, labels})

• url (string): The URL representing the content of the new workspace or workspace and subtabs.
• focus (boolean): Optional. Specifies whether the new active tab has focus.
• labels (array): Optional. An array of labels to be applied to the workspace or workspace and subtabs.

Opens a URL generated via the generateConsoleURL API. Returns a Promise. Success resolves to true. The Promise will be rejected on error.

addToBrowserTitleQueue({title})

• title (string): Title that needs to be added to the browser title queue

Adds a browser tab title to a list of titles, which rotates every few seconds. Returns a Promise. Success resolves to true. The Promise will be rejected on error.

removeFromBrowserTitleQueue({title})

• title (string): Title that needs to be removed from the browser title queue

Removes a browser tab title from the list of titles, which rotates every few seconds. Returns a Promise. Success resolves to true if title was removed, false otherwise. The Promise will be rejected on error.