openPrimaryTab()

Opens a new primary tab to display the content of the specified URL, which can be relative or absolute. You can also override an existing tab. This method is only available in API version 20.0 or later.

If the ID corresponds to an existing primary tab, the existing tab is redirected to the given URL because the Salesforce console prevents duplicate tabs.
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 subtab of their parent accounts, and openPrimaryTab() is called on a case, the case opens as subtab on its parent account’s primary tab.

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

Syntax

1sforce.console.openPrimaryTab(id:String, url:URL, active:Boolean, (optional)tabLabel:String, (optional)callback:Function, (optional)NAME)

Where NAME is a variable.

Arguments

Name	Type	Description
`id`	string	ID of the primary tab to override. Use `null` to create a new primary tab. If the ID corresponds to an existing primary tab, the existing tab is redirected to the given URL because the Salesforce console prevents duplicate tabs.
`url`	URL	URL of the opened primary tab. 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 subtab of their parent accounts, and `openPrimaryTab()` is called on a case, the case opens as subtab on its parent account's 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.
`active`	boolean	If `true` , the opened primary tab displays immediately. If `false` , the opened primary tab displays in the background and the current tab maintains focus.
`tabLabel`	string	Optional label of the opened primary tab. If a label isn't specified, `External Page` displays. Add labels as text; HTML isn't supported.
`callback`	function	JavaScript method called upon completion of the method.
`name`	string	Optional name of the opened primary tab. 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="testOpenPrimaryTab();return false">
4         Click here to open a new primary tab</A> 
5
6    <apex:includeScript value="/support/console/68.0/integration.js"/>
7    <script type="text/javascript">
8        function testOpenPrimaryTab() {
9            //Open a new primary tab with the salesforce.com home page in it
10            sforce.console.openPrimaryTab(null, 'https://salesforce.com', false, 
11                'salesforce', openSuccess, 'salesforceTab');
12        }
13        
14        var openSuccess = function openSuccess(result) {
15            //Report whether opening the new tab was successful
16            if (result.success == true) {
17                alert('Primary tab successfully opened');
18            } else {
19                alert('Primary tab cannot be opened');
20            }
21        };
22        
23  </script>
24
25</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 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 tab successfully opened; `false` if the tab didn’t open.
`id`	string	ID of the primary tab. IDs are only valid during a user session; IDs become invalid when a user leaves the Salesforce console.