openSubtab()

Opens a new subtab (within a primary tab) that displays the content of a specified URL, which can be relative or absolute. You can also override an existing subtab. Use to open a new subtab on a primary tab via the primary tab's ID. This method is only available in API version 20.0 or later.

If there's an error opening the tab, the error code is reported in the JavaScript console.

Syntax

1sforce.console.openSubtab(primaryTabId:String, url:URL, active:Boolean, tabLabel:String, id:String, (optional)callback:Function, (optional)name:String)

Arguments

Name	Type	Description
primaryTabId	string	ID of the primary tab in which the subtab opened.
url	URL	URL of the opened subtab. If the URL is to a Salesforce object, that object displays as specified in the Salesforce console app settings. For example, if cases are set to open as a primary tab, and `openSubtab()` is called on a case, the case opens as a primary tab. Users can open an external URL if it’s been added to the console’s allowlist. When using a relative URL, make sure that you include "`/`" at the beginning of your URL. When pointing to a Visualforce page, use "`/apex/`" at the beginning of your URL. Otherwise, your URL might not work as expected. Note
active	boolean	If `true`, the opened subtab displays immediately. If `false`, the opened subtab displays in the background and the current tab maintains focus.
tabLabel	string	Optional label of the opened subtab. If a label isn't specified, `External Page` displays. Add labels as text; HTML isn't supported.
id	string	ID of the subtab to override. Use `null` to create a new subtab.
callback	function	JavaScript method called upon completion of the method.
name	string	Optional name of the opened subtab. This argument is only available in API version 22.0 and later.

Sample Code–Visualforce

1<apex:page standardController="Case">
2
3    <A HREF="#" onClick="testOpenSubtab();return false">
4        Click here to open a new subtab</A> 
5
6    <apex:includeScript value="/support/console/63.0/integration.js"/>
7    <script type="text/javascript">
8        function testOpenSubtab() {
9            //First find the ID of the primary tab to put the new subtab in
10            sforce.console.getEnclosingPrimaryTabId(openSubtab);
11        }
12        
13        var openSubtab = function openSubtab(result) {
14            //Now that we have the primary tab ID, we can open a new subtab in it
15            var primaryTabId = result.id;
16            sforce.console.openSubtab(primaryTabId , 'https://salesforce.com', false, 
17                'salesforce', null, openSuccess, 'salesforceSubtab');
18        };
19        
20        var openSuccess = function openSuccess(result) {
21            //Report whether we succeeded in opening the subtab
22            if (result.success == true) {
23                alert('subtab successfully opened');
24            } else {
25                alert('subtab cannot be opened');
26            }
27        };
28    </script>
29</apex:page>

To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links in the Salesforce help.

Note

Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:

Name	Type	Description
success	boolean	`true` if the subtab successfully opened; `false` if the subtab didn't open.
id	string	ID of the subtab. IDs are only valid during a user session; IDs become invalid when the user leaves the Salesforce console.

Salesforce Console Developer Guide

openSubtab()

Syntax

Arguments

Sample Code–Visualforce

Response