Metadata API Developer’s Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

CustomApplication

CustomApplication represents a custom or standard application. In API version 29.0 and earlier, CustomApplication represents only a custom application. An application is a list of tab references, with a description and a logo. This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

Custom and standard applications have the suffix .app and are stored in the applications folder.

Retrieving a component of this metadata type in a project makes the component appear in any Profile and PermissionSet components that are retrieved in the same package.

Note

Version

Custom applications are available in API version 10.0 and later. Standard applications are available in API version 30.0 and later.

Fields

Field Name Field Type Description
customApplicationComponents CustomApplicationComponents Represents custom console components (Visualforce pages) assigned to a Salesforce console app.
defaultLandingTab string The fullName of a standard tab or custom tab that opens when this application is selected.
description string The optional description text of the application.
detailPageRefreshMethod string Determines how detail pages refresh in a Salesforce console app. Required if isServiceCloudConsole is true. The valid values are:
  • none
  • autoRefresh
  • flag

This field is available in API version 25.0 and later.
domainWhitelist DomainWhitelist Any external domains that users can access from within a Salesforce console app. For example, www.yourdomain.com. This field is available in API version 25.0 and later.
enableKeyboardShortcuts boolean Indicates if a Salesforce console app has keyboard shortcuts enabled, which let users perform actions by pressing a combination of keys instead of having to use a mouse. After keyboard shortcuts are enabled, several default shortcuts are available for customization. Before you can create custom shortcuts, a developer must define the shortcut’s action with the addEventListener() method in the Salesforce Console Integration Toolkit. You can’t create keyboard shortcuts for actions performed outside of the console. This field is required if isServiceCloudConsole is true.

This field is available in API version 28.0 and later.
enableMultiMonitorComponents boolean Indicates if a Salesforce console app has multi-monitor components enabled, which let users move portions of a console from their browsers to locations on their screens. This field is required if isServiceCloudConsole is true.

This field is available in API version 30.0 and later.
isServiceCloudConsole boolean Indicates if the application is a Salesforce console app. For more information, see “Salesforce Console Overview” in the Salesforce online help.
keyboardShortcuts KeyboardShortcuts Represents the keyboard shortcuts for a Salesforce console app. Keyboard shortcuts let users perform actions by pressing a combination of keys instead of having to use a mouse.

This field is available in API version 28.0 and later.
fullName string The internal name of the application, based on the label, but with white spaces and special characters escaped out for validity. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
label string The name of the application.
listPlacement ListPlacement Represents how lists display in a Salesforce console app. Required if isServiceCloudConsole is true.
listRefreshMethod string Determines how lists refresh in a Salesforce console app. Required if isServiceCloudConsole is true. The valid values are:
  • none
  • refreshList
  • refreshListRows

This field is available in API version 25.0 and later.
liveAgentConfig LiveAgentConfig Represents the configurations for using Live Agent in the Salesforce Console.
logo string The optional reference to the image document for the application.
pushNotifications PushNotifications Represents push notifications for a Salesforce console app. Push notifications are visual indicators on lists and detail pages that show when a record or field has changed during a user’s session. For example, if two support agents are working on the same case and one agent changes the Priority, a push notification displays to the other agent so he or she notices the change and doesn’t duplicate the effort.

This field is available in API version 28.0 and later.
saveUserSessions boolean Indicates if a Salesforce console app saves user sessions automatically, so that when console users close their browsers or log out of Salesforce, any previously open tabs will display when users log in again. Required if isServiceCloudConsole is true.

This field is available in API version 28.0 and later.
tab string[] The list of tabs included in this application. In API version 12.0, the fullName for built-in tabs like Home, Account, and Reports, is the name of the tab (Home, for example). In API version 13.0 and later, built-in tabs are prefixed with standard- For example, to reference the Account tab you would use standard-Account.
workspaceMappings WorkspaceMappings Represents how records open in a Salesforce console app. Required if isServiceCloudConsole is true. This field is available in API version 25.0 and later.

CustomApplicationComponents

Represents custom console components (Visualforce pages) assigned to a Salesforce console app. Available in API version 25.0 and later.

Field Name Field Type Description
alignment string Determines how custom console components are aligned in the footer of a Salesforce console app.
customApplicationComponent string The name of a custom console component assigned to a Salesforce console app.

CustomShortcut

Represents custom keyboard shortcuts assigned to a Salesforce console app. Before you can create custom shortcuts, a developer must define the shortcut’s action with the addEventListener() method in the Salesforce Console Integration Toolkit. You can’t create keyboard shortcuts for actions performed outside of the console. Available in API version 28.0 and later.

Field Name Field Type Description
action string Required. The action performed in the console when a user presses the keyboard shortcut.
active boolean Required. Indicates whether the keyboard shortcut is active (true) or not (false).
keyCommand string Required. The combination of keys a user presses to trigger the keyboard shortcut. Keyboard shortcuts aren’t case sensitive, but they display as uppercase on setup pages in the Salesforce user interface so that they’re easier to read.

Each key command can include up to four modifier keys followed by one non-modifier key. Modifier and non-modifier keys are separated by the + key. Modifier keys can occur in any order, but you must place non-modifier keys at the end of the key command sequence. For example, SHIFT+CTRL+ALT+META +A.

Valid modifier keys are:
  • SHIFT
  • CTRL
  • ALT
  • META (represents the COMMAND key on Macs)
Valid non-modifier keys are letters A through Z and numbers 0 through 9. Additional valid keys are:
  • TAB
  • ENTER
  • PAUSE/BREAK
  • CAPS LOCK
  • ESC
  • SPACE
  • PAGE UP
  • PAGE DOWN
  • END
  • HOME
  • LEFT ARROW
  • UP ARROW
  • RIGHT ARROW
  • DOWN ARROW
  • PRINT SCREEN
  • INSERT
  • DELETE
  • RIGHT WINDOW
  • NUMPAD 0
  • NUMPAD 1
  • NUMPAD 2
  • NUMPAD 3
  • NUMPAD 4
  • NUMPAD 5
  • NUMPAD 6
  • NUMPAD 7
  • NUMPAD 8
  • NUMPAD 9
  • MULTIPLY
  • ADD
  • SUBTRACT
  • DECIMAL POINT
  • DIVIDE
  • F1
  • F2
  • F3
  • F4
  • F5
  • F6
  • F7
  • F8
  • F9
  • F10
  • F11
  • F12
  • NUM LOCK
  • SCROLL LOCK
  • ;
  • =
  • ,
  • —
  • .
  • /
  • ‘
  • [
  • ]
  • \
  • '
description string The optional description text for the keyboard shortcut.
eventName string Required. Code available to developers who want to add custom shortcut functions to the console via the Salesforce Console Integration Toolkit.

DefaultShortcut

Represents default keyboard shortcuts assigned to a Salesforce console app. Once you enable keyboard shortcuts for a console, several default shortcuts are available for customization, such as opening and closing tabs, moving between tabs, and saving records. Available in API version 28.0 and later.

Field Name Field Type Description
action string Required. The action performed in the console when a user presses the keyboard shortcut. Valid values are:
  • FOCUS_CONSOLE
  • FOCUS_NAVIGATOR_TAB
  • FOCUS_DETAIL_VIEW
  • FOCUS_PRIMARY_TAB_PANEL
  • FOCUS_SUBTAB_PANEL
  • FOCUS_LIST_VIEW
  • FOCUS_FIRST_LIST_VIEW
  • FOCUS_SEARCH_INPUT
  • MOVE_LEFT
  • MOVE_RIGHT
  • UP_ARROW
  • DOWN_ARROW
  • OPEN_TAB_SCROLLER_MENU
  • OPEN_TAB
  • CLOSE_TAB
  • ENTER
  • EDIT
  • SAVE

For a list and description of the default keyboard shortcuts, see “Default Keyboard Shortcuts for a Salesforce Console” in the Salesforce online help.
active boolean Required. Indicates whether the keyboard shortcut is active (true) or not (false).
keyCommand string Required. The combination of keys a user presses to trigger the keyboard shortcut. Keyboard shortcuts aren’t case sensitive, but they display as uppercase on setup pages in the Salesforce user interface so that they’re easier to read.

Each key command can include up to four modifier keys followed by one non-modifier key. Modifier and non-modifier keys are separated by the + key. Modifier keys can occur in any order, but you must place non-modifier keys at the end of the key command sequence. For example, SHIFT+CTRL+ALT+META +A.

Valid modifier keys are:
  • SHIFT
  • CTRL
  • ALT
  • META (represents the COMMAND key on Macs)
Valid non-modifier keys are letters A through Z and numbers 0 through 9. Additional valid keys are:
  • TAB
  • ENTER
  • PAUSE/BREAK
  • CAPS LOCK
  • ESC
  • SPACE
  • PAGE UP
  • PAGE DOWN
  • END
  • HOME
  • LEFT ARROW
  • UP ARROW
  • RIGHT ARROW
  • DOWN ARROW
  • PRINT SCREEN
  • INSERT
  • DELETE
  • RIGHT WINDOW
  • NUMPAD 0
  • NUMPAD 1
  • NUMPAD 2
  • NUMPAD 3
  • NUMPAD 4
  • NUMPAD 5
  • NUMPAD 6
  • NUMPAD 7
  • NUMPAD 8
  • NUMPAD 9
  • MULTIPLY
  • ADD
  • SUBTRACT
  • DECIMAL POINT
  • DIVIDE
  • F1
  • F2
  • F3
  • F4
  • F5
  • F6
  • F7
  • F8
  • F9
  • F10
  • F11
  • F12
  • NUM LOCK
  • SCROLL LOCK
  • ;
  • =
  • ,
  • —
  • .
  • /
  • ‘
  • [
  • ]
  • \
  • '

DomainWhitelist

Represents any external domains that users can access from within a Salesforce console app. For example, www.yourdomain.com. Available in API version 25.0 and later.

Field Name Field Type Description
domain string The external domains that users can access from within this Salesforce console app.

KeyboardShortcuts

Represents keyboard shortcuts assigned to a Salesforce console app. Required if isServiceCloudConsole is true. Available in API version 28.0 and later.

Field Name Field Type Description
customShortcut KeyboardShortcuts[] Represents custom keyboard shortcuts assigned to a Salesforce console app. Before you can create custom shortcuts, a developer must define the shortcut’s action with the addEventListener() method in the Salesforce Console Integration Toolkit. You can’t create keyboard shortcuts for actions performed outside of the console.
defaultShortcut KeyboardShortcuts[] Represents default keyboard shortcuts assigned to a Salesforce console app. Once you enable keyboard shortcuts for a console, several default shortcuts are available for customization, such as opening and closing tabs, moving between tabs, and saving records.

For a list and description of the default keyboard shortcuts, see “Default Keyboard Shortcuts for a Salesforce Console” in the Salesforce online help.

ListPlacement

Represents how lists display in a Salesforce console app. Required if isServiceCloudConsole is true. Available in API version 25.0 and later.

Field Name Field Type Description
height int Height of the list in pixels or percentage. Required if location is top.
location string Required. Location of the list on the screen. Valid values are:
  • full
  • top
  • left
units string Required. Represents if height or width is in pixels or percentage.
width int Width of the list in pixels or percentage. Required if location is left.

LiveAgentConfig

Represents your organization’s settings for using Live Agent in the Salesforce Console.

Field Name Field Type Description
enableLiveChat boolean Specifies whether Live Agent is enabled in your organization (true) or not (false).
openNewAccountSubtab boolean Specifies whether to open a new Account subtab in the Salesforce Console automatically (true) or not (false) when an agent accepts a chat.
openNewCaseSubtab boolean Specifies whether to open a new Case subtab in the Salesforce Console automatically (true) or not (false) when an agent accepts a chat.
openNewContactSubtab boolean Specifies whether to open a new Contact subtab in the Salesforce Console automatically (true) or not (false) when an agent accepts a chat.
openNewLeadSubtab boolean Specifies whether to open a new Lead subtab in the Salesforce Console automatically (true) or not (false) when an agent accepts a chat.
openNewVFPageSubtab boolean Specifies whether to open a new Visualforce page as a subtab in the Salesforce Console automatically (true) or not (false) when an agent accepts a chat.
pagesToOpen PagesToOpen Specifies the Visualforce pages to open in subtabs when an agent accepts a chat in the Salesforce Console.
showKnowledgeArticles boolean Specifies whether to display the Knowledge component while using Live Agent in the Salesforce Console (true) or not (false).

PagesToOpen

Represents the Visualforce pages you want to open in subtabs when an agent accepts a chat request in the Salesforce Console. Available in API version 28.0 and later.

Field Name Field Type Description
pagesToOpen string The name of the Visualforce pages you want to open in subtabs when an agent accepts a chat in the Salesforce Console.

PushNotifications

Represents a set of push notifications, which are visual indicators on lists and detail pages that show when a record or field has changed during a user’s session. Available for use if isServiceCloudConsole is true. Available in API version 28.0 and later.

Field Name Field Type Description
pushNotification PushNotification[] The set of push notifications.

PushNotification

Represents if visual indicators on lists and detail pages display in a Salesforce console app when a record or field has changed during a user’s session. Available for use if isServiceCloudConsole is true. Available in API version 28.0 and later.

Field Name Field Type Description
fieldNames string Required. The name of the field, or fields, that trigger push notifications for the selected object.
objectName string Required. Name of the object that triggers push notifications.

WorkspaceMappings

Represents how records open in a Salesforce console app. Required if isServiceCloudConsole is true. Available in API version 25.0 and later.

Field Name Field Type Description
mapping WorkspaceMapping Represents how records for a specific tab open in a Salesforce console app. Required for each tab specified in the CustomApplication.

WorkspaceMapping

Represents how records for a specific tab open in a Salesforce console app. Required for each tab specified in the CustomApplication. Available in API version 25.0 and later.

Field Name Field Type Description
fieldName string The name of the field that specifies the primary tab in which to display tab as a subtab. If not specified, tab opens as a primary tab.
tab string Required. Name of the tab.

Retrieving Apps

To retrieve apps in your organization, use the CustomApplication type name in the package.xml manifest file. You can either retrieve all apps or specify which apps to retrieve in the types section of package.xml.

To retrieve all apps in your organization—custom and standard apps, specify the wildcard character (*), as follows.

1<types>
2    <members>*</members>
3    <name>CustomApplication</name>
4</types>

In API version 29.0 and earlier, use of the wildcard returns only all custom applications but not standard applications.

Note

To retrieve a custom app, just specify the app name.

1<types>
2    <members>MyCustomApp</members>
3    <name>CustomApplication</name>
4</types>

To retrieve a standard app, add the standard__ prefix to the app name. For example, to retrieve the Chatter standard app, specify standard__Chatter.

1<types>
2    <members>standard__Chatter</members>
3    <name>CustomApplication</name>
4</types>

To retrieve an app that is part of an installed package, add the package namespace prefix followed by two underscores and the app name. For example, if the package namespace is myInstalledPackageNS and the app name is PackageApp, specify myInstalledPackageNS__PackageApp, as follows.

1<types>
2    <members>myInstalledPackageNS__PackageApp</members>
3    <name>CustomApplication</name>
4</types>

Declarative Metadata Sample Definition

The following is the definition of a custom app:

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomApplication xmlns="http://soap.sforce.com/2006/04/metadata">
3    <defaultLandingTab>Myriad_Publishing__c</defaultLandingTab>
4    <description>App to manage Myriad Publishing</description>
5    <label>Myriad</label>
6    <logo>MyriadFolder/Myriad_Logo.jpg</logo>
7    <tab>standard-Chatter</tab>
8    <tab>standard-File</tab>
9    <tab>Myriad_Publishing__c</tab>
10    <tab>standard-report</tab>
11    <tab>standard-Dashboard</tab>
12</CustomApplication>

The following is a definition of a standard app (Chatter):

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomApplication xmlns="http://soap.sforce.com/2006/04/metadata">
3    <defaultLandingTab>standard-home</defaultLandingTab>
4    <label>Collaboration</label>
5    <tab>standard-Chatter</tab>
6    <tab>standard-UserProfile</tab>
7    <tab>standard-OtherUserProfile</tab>
8    <tab>standard-CollaborationGroup</tab>
9    <tab>standard-File</tab>
10</CustomApplication>

Declarative Metadata Sample Definition—Salesforce Console

The following is the definition of a custom app where isServiceCloudConsole is true:

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomApplication xmlns="http://soap.sforce.com/2006/04/metadata">
3    <customApplicationComponents>
4       <alignment>left</alignment>
5       <customApplicationComponent>MyComponent</customApplicationComponent>
6    </customApplicationComponents>
7    <defaultLandingTab>standard-home</defaultLandingTab>
8    <detailPageRefreshMethod>autoRefresh</detailPageRefreshMethod>
9    <isServiceCloudConsole>true</isServiceCloudConsole>
10    <keyboardShortcuts>
11       <customShortcut>
12         <action>MyCustomShortcutAction</action>
13         <active>true</active>
14         <keyCommand>X</keyCommand>
15         <description>Custom Shortcut example</description>
16         <eventName>myCustomShortcutExample</eventName>
17       </customShortcut>
18       <defaultShortcut>
19         <action>FOCUS_CONSOLE</action>
20         <active>true</active>
21         <keyCommand>ESC</keyCommand>
22       </defaultShortcut>
23       <defaultShortcut>
24         <action>FOCUS_NAVIGATOR_TAB</action>
25         <active>true</active>
26         <keyCommand>V</keyCommand>
27       </defaultShortcut>
28       <defaultShortcut>
29         <action>FOCUS_DETAIL_VIEW</action>
30         <active>true</active>
31         <keyCommand>SHIFT+S</keyCommand>
32       </defaultShortcut>
33       <defaultShortcut>
34         <action>FOCUS_PRIMARY_TAB_PANEL</action>
35         <active>true</active>
36         <keyCommand>P</keyCommand>
37       </defaultShortcut>
38       <defaultShortcut>
39         <action>FOCUS_SUBTAB_PANEL</action>
40         <active>true</active>
41         <keyCommand>S</keyCommand>
42       </defaultShortcut>
43       <defaultShortcut>
44         <action>FOCUS_LIST_VIEW</action>
45         <active>true</active>
46         <keyCommand>N</keyCommand>
47       </defaultShortcut>
48       <defaultShortcut>
49         <action>FOCUS_FIRST_LIST_VIEW</action>
50         <active>true</active>
51         <keyCommand>SHIFT+F</keyCommand>
52       </defaultShortcut>
53       <defaultShortcut>
54         <action>FOCUS_SEARCH_INPUT</action>
55         <active>true</active>
56         <keyCommand>R</keyCommand>
57       </defaultShortcut>
58       <defaultShortcut>
59         <action>MOVE_LEFT</action>
60         <active>true</active>
61         <keyCommand>LEFT ARROW</keyCommand>
62       </defaultShortcut>
63       <defaultShortcut>
64         <action>MOVE_RIGHT</action>
65         <active>true</active>
66         <keyCommand>RIGHT ARROW</keyCommand>
67       </defaultShortcut>
68       <defaultShortcut>
69         <action>UP_ARROW</action>
70         <active>true</active>
71         <keyCommand>UP ARROW</keyCommand>
72       </defaultShortcut>
73       <defaultShortcut>
74         <action>DOWN_ARROW</action>
75         <active>true</active>
76         <keyCommand>DOWN ARROW</keyCommand>
77       </defaultShortcut>
78       <defaultShortcut>
79         <action>OPEN_TAB_SCROLLER_MENU</action>
80         <active>true</active>
81         <keyCommand>D</keyCommand>
82       </defaultShortcut>
83       <defaultShortcut>
84         <action>OPEN_TAB</action>
85         <active>true</active>
86         <keyCommand>T</keyCommand>
87       </defaultShortcut>
88       <defaultShortcut>
89         <action>CLOSE_TAB</action>
90         <active>true</active>
91         <keyCommand>C</keyCommand>
92       </defaultShortcut>
93       <defaultShortcut>
94         <action>ENTER</action>
95         <active>true</active>
96         <keyCommand>ENTER</keyCommand>
97       </defaultShortcut>
98       <defaultShortcut>
99         <action>EDIT</action>
100         <active>true</active>
101         <keyCommand>E</keyCommand>
102       </defaultShortcut>
103       <defaultShortcut>
104         <action>SAVE</action>
105         <active>true</active>
106         <keyCommand>CTRL+S</keyCommand>
107       </defaultShortcut>
108    </keyboardShortcuts>
109    <label>MyConsole</label>
110    <listPlacement>
111       <location>left</location>
112       <units>percent</units>
113       <width>20</width>
114    </listPlacement>
115    <listRefreshMethod>refreshList</listRefreshMethod>
116    <pushNotifications>
117       <pushNotification>
118         <fieldNames>CreatedBy</fieldNames>
119         <objectName>Campaign</objectName>
120       </pushNotification>
121       <pushNotification>
122         <fieldNames>CustomField1__c</fieldNames>
123         <objectName>CustomObject1__c</objectName>
124       </pushNotification>
125    </pushNotifications>
126    <saveUserSessions>false</saveUserSessions>
127    <tab>standard-Case</tab>
128    <tab>standard-Account</tab>
129    <tab>standard-Contact</tab>
130     <tab>standard-Contract</tab>
131    <workspaceMappings>
132       <mapping>
133          <tab>standard-Case</tab>
134       </mapping>
135       <mapping>
136          <fieldName>AccountId</fieldName>
137          <tab>standard-Contract</tab>
138       </mapping>
139       <mapping>
140          <tab>standard-Contract</tab>
141       </mapping>
142       <mapping>
143          <fieldName>ParentId</fieldName>
144          <tab>standard-Account</tab>
145       </mapping>
146    </workspaceMappings>
147</CustomApplication>