Purpose-built App API Reference

Introduction

This page provides an exhaustive list of all the configuration options available for Purpose-built App plugins. For a guide on how to create a Purpose-built App plugin, see the quickstart guide. For an explanation of available features, see the deep dive.

Config Properties

This section has a table with the full list of configuration properties that are specific to Purpose-built Apps inside of the config.json file of the plugin. All of these properties should be present at the top level inside of the metadata property in that file unless stated otherwise.

Notification Categories

The notificationsFilter property allows you to specify which notification categories should be shown to users of your app. The following categories are available:

Category	Description
AdminApprovals	Get notifications about usage and other administrative events.
Benchmarks	Get notified about benchmark-related events.
Collaboration	Get notified whenever someone shares something with you or mentions you in a comment.
Dashboards	Get notified about available reports and key metrics tracked by your organization.
Distributions	Receive a weekly email with insights about the health of distributions for selected projects and other status updates for sent or scheduled messages.
Pulse	Get notified about program or project status changes and setup issues.
Programs	Get notified about program-related events.
Recommendations	Get recommendations from Qualtrics that help you use full potential of Qualtrics XM platform.
Security	Get notified about security-related events.
Surveys	Receive a weekly email summary about your survey response data and get real-time notifications about response anomalies.
Tickets	Get notified about ticket assignments and status changes. (You might receive some ticket notifications even when the toggle is off based on your organization's preferences)
Workflows	Get notified based on custom workflows set up for your organisation.

Subcategories can be specified using colon notation. For example, Recommendations:FirstLogin would filter for the FirstLogin subcategory within the Recommendations category.

You can learn more about notifications on this page.

Constant Properties

The portalType, tags and type properties should not be changed.

Property	Type	Description	Required	Default
type	string	should always be "purposeBuiltApp"	Yes	N/A
tags	string array	must contain "purposeBuiltApp"	Yes	N/A
portalType	string	must always be "INTERNAL". EXTERNAL and HIDDEN are internal-only portal types used by first-party Qualtrics portals and are not available to extension plugins.	No	"INTERNAL"
nameKey	string	Translation key for the app name from your plugin's translation file	Yes	N/A
descriptionKey	string	Translation key for the app description from your plugin's translation file	Yes	N/A
shouldQualtricsBeVisible	boolean	If false, the user will not be able to switch from this app to the main Qualtrics experience.	No	true
tabs	object	see Tabs Properties	Yes	N/A
portalData	object	Describes style properties for the whole pba.	No	undefined
portalData.headerColor	string	The color of the header in the app. Available options can be found here	No	undefined
portalData.logoUrl	string	URL for the logo that can replace the Qualtrics logo in the top left hand corner of the app	No	undefined
configurationSettings	object	see Configuration Settings	No	undefined
isDeprecated	boolean	Indicates whether this app is deprecated. More information can be found here	No	false
deprecationMessage	string	A message explaining the app deprecation. If isDeprecated is set to true, this message will be provided for more details.	No	"This app type is deprecated and will no longer be supported. Please create a new app using the updated app type."
deprecationLink	string	A URL where users can find more information about the app deprecation. If isDeprecated is set to true, then this URL will be given to users to find more information about how to migrate off of the deprecated app	No	undefined
notificationsFilter	string array	Defines which notification categories should be shown to users of this app. Can include subcategories using colon notation (e.g., Recommendations:FirstLogin). See Notification Categories for available options.	No	undefined

Configuration Settings

Property	Type	Description	Required
configurable	boolean	Whether the user can configure the app. If set to false no other properties are permitted in the configurationSettings object.	Yes
allowTabNameCustomization	boolean	Whether users can customize the names of tabs in the app. When set to false, tab names will be locked to their default values. Defaults to true.	No
multiInstanceConfiguration	object	The configuration for multi-instance apps. When specified, the app acts as a template that brands can use to create multiple instances. See Multi-instance Apps for details.	No
multiInstanceConfiguration.authType	string	The type of authorization that will be used for instances of the app. Must use "cxRoles" for its value. This property is required when using multiInstanceConfiguration.	Yes (when multiInstanceConfiguration is used)
previewOptions	object	Contains all the fields to define how the preview on the configuration page should look.	Yes
previewOptions.breadcrumbType	string	The type of breadcrumb to display. DashboardBreadcrumb is the only valid option right now.	No
previewOptions.previewElements	object array	An array of preview elements that should appear in the preview. See Preview Elements for details.	Yes
configurationSettings.configurationPanel	object array	An array of panels that display as tabs on the configuration page. See Configuration Panel for the properties of each panel.	Yes

Configuration Panel

Property	Type	Description	Required
id	string	The id of the panel. Any unique value is acceptable.	Yes
path	string	The path for the panel.	Yes
nameKey	string	The translation key for the name of the panel.	Yes
descriptionKey	string	The translation key for the description of the panel.	Yes
iconName	string	Icon selected from the list of available Tab Icons link.	Yes
paneType	string	The type of panel to display. Must be "sections".	Yes
sections	object array	An array of sections within a pane.	Yes
sections.id	string	The ID of the section. Determines the section's contents. Valid values are "SupportContact", "Deactivate", "TabsSection", "EditLogo", "EditTheme", and "EnablementConfigurator".	Yes
sections.nameKey	string	The translation key for the name of the section. Only applicable when the section's id is set to "EnablementConfigurator".	No
sections.descriptionKey	string	The translation key for the description of the section. Only applicable when the section's id is set to "EnablementConfigurator".	No

Tab Properties

There are a few different types of tabs that can be used in a Purpose-built App. They are as follows:

• multiPageDashboardTab - A tab that displays a specific page of a multi-page dashboard.
• customBlockTab - A tab that displays a single page of content that is defined by a Custom Block plugin.
• content - A tab that displays a single page of content inside of an iframe. The location to fetch the content from is defined by the href property.

Property	Type	Description	Applicable Tab Type	Required
type	string	Defines the type of tab. Valid options are "content", "customBlockTab", and "multiPageDashboardTab"	All	Yes
iconName	string	Icon selected from the list of available Tab Icons link	All	Yes
order	number	Defines tab display order in the side navigation	All	No
accessControls	object	Defines the permissions required for a user to be able to view this tab. See Access Controls for details on how to configure this. requirements is a deprecated alias for this same object and accepts the same shape.	All	No
themeType	string	Color theme applied to the tab. Valid values are "blue", "green", "greenblue", "purple", and "yellow". See Customize the look and feel.	content, multiPageDashboardTab	Yes for multiPageDashboardTab, No for content
activeForGlobalWrapperConfigTypes	object array	List of Global Wrapper contexts for which this tab should be shown as active. Each entry requires contextType and may optionally include resourceType, subresourceType, resourceId, and urlMatch.	content	No
pluginId	string	Unique ID of the Custom Block Plugin being used as a Custom Tab	customBlockTab	Yes
globalWrapperConfig.tabsListType	String	Type of tabsList for blocking navigation menus from the Global Wrapper. Must be allowList or blockList. See Global Wrapper Menu.	content	No
globalWrapperConfig.tabsList	String[]	List of tabs for blocking navigation menus from the Global Wrapper. See Global Wrapper Menu.	content	No
id	string	Unique tab identifier, a human-readable id recommended	content, multiPageDashboardTab	Yes
nameKey	string	Translation key from your plugin's translation file. The text will be displayed as the title of the tab.	content, multiPageDashboardTab	Yes
href	string	Defines the URL which will be loaded when user navigates to the tab	content	Yes
translationURL	string	The platform accepts this field but always overrides it with the plugin's own public/translations/ path, so setting it has no effect.	content, multiPageDashboardTab	No
URLAllowList	string[]	List of regular expressions to determine which URLs can always be opened in the given tab. If tab is enabled and visible for user these values will be included in portals allowed URLs list	content	No
configurationSettings	object	Configuration settings for the tab.	content, multiPageDashboardTab	No
configurationSettings.configurable	boolean	If set to true, the the tab will be configurable to the user.	content, multiPageDashboardTab	Yes
configurationSettings.tabTitleKey	string	Translation key for the tab title.	content, multiPageDashboardTab	Yes
configurationSettings.tabDescriptionKey	string	Translation key for the tab description.	content, multiPageDashboardTab	Yes
configurationSettings.defaultEnabledState	boolean	Indicates the initial state of configurable tabs. When set to false, the tab will not be shown to users until the App configuration owner turns it on.	content, multiPageDashboardTab	Yes

Custom Tab Properties

Deprecation Notice

Custom Block plugins can currently contain some metadata that lets them configure how a Purpose-built App plugin should render a tab that uses it. This functionality will be deprecated in the future to make sure all configuration for Purpose-built Apps is done through the Purpose-built App plugin.

This table contains properties unique to a Custom Tab found in its config.json file:

Property	Type	Description	Required
configurationSettings.configurable	Boolean	If set to true, the the tab will be configurable to the user.	true
configurationSettings.tabTitleKey	String	Translation key for the tab title.	true
configurationSettings.tabDescriptionKey	String	Translation key for the tab description.	true
configurationSettings.defaultEnabledState	Boolean	Indicates the initial state of configurable tabs. When set to false, the tab will not be shown to users until the App configuration owner turns it on.	true
attachmentPoints	Object array	A List of Purpose-built App Plugins to which the Custom Block is	false
attachmentPoints.appId	String	The Unique ID of a particular Purpose-built App Plugin.	true
attachmentPoint.order	Number	Defines the descending order in which tab should be displayed in the left-side navigation.	false

Override Values

Fields like accessControls, iconName override values defined inside Custom Tab metadata.

Access Controls

Access controls can be defined on specific tabs to further restrict who should have access to them. Most Purpose-built-apps do not need to use this. To control access to the app, you should use the privileges that are automatically created for your extension. If you need this feature to further restrict access to particular tabs, see the supported permissions below.

Access Control Properties

Property	Type	Description	Required
AccountPermissions	String[]	List of Account Permissions which need to be fulfilled in order to display the tab to the end user	No
AppPermissions	String[]	List of App Permissions which need to be fulfilled in order to display the tab to the end user	No
ProjectPermissions	String[]	List of Project Permissions which need to be fulfilled in order to display the tab to the end user	No
BrandPermissions	String[]	List of Brand Permissions which need to be fulfilled in order to display the tab to the end user	No
CustomerJourneyOptimizerPermissions	String[]	List of Customer Journey Optimizer Permissions which need to be fulfilled in order to display the tab to the end user	No
AIPermissions	String[]	List of AI Permissions which need to be fulfilled in order to display the tab to the end user	No
ConfigurerPermissions	String[]	List of permissions that must be enabled in order for the user to be able to change the configuration of the tab	No
features	String[]	List of Feature Flippers which need to be turned on in order to display the tab to the end user	No
requireQualtrics	Boolean	If this is set to true, then the tab will only appear to the user if they also have access to the regular Qualtrics product as well.	No

{
  ...
  "metadata": {
    ...
    "tabs": [
      {
        ...
        "accessControls": {
          "AccountPermissions": ["accessSiteIntercept"],
          "AppPermissions": ["cxDashboardPortalViewer"],
          "features": ["Homepage.EnableUI"]
        }
      }
    ]
  }
}

Supported Permission Values

The platform supports a specific set of permission values for each permission type. Only the following permission values will be recognized:

AccountPermissions

• accessPanelManagement
• accessResearchHub
• accessSiteIntercept
• administerSiteIntercept
• allowHomepageWidgetPinning
• approveMailings
• createCBConjointProjects
• createFrontlineFeedbackProjects
• createMaxDiffProjects
• createSurveys
• createThreeSixties
• createVocalizeProjects
• createZone
• enableBrandManagementHub
• manageDirectory
• searchResearchHub
• useImportedDataProjects
• useSearchReport
• useVocalize
• viewNewUserNavigationTour

AppPermissions

• cxDashboardPortalConfigurer
• cxDashboardPortalViewer
• exTeamPortalConfigurer
• exTeamPortalViewer
• manageContactCenterFrontlineApp
• manageLocationAssistApp
• managePatientExperienceHub
• useContactCenterFrontlineApp
• useLocationAssistApp
• usePatientExperienceHub
• viewXMPlatform

ProjectPermissions

• BXCategory
• CXCategory
• EXCategory
• PXCategory
• ResearchCoreCategory
• employeeEngagement
• employeeGeneralFeedback
• employeeLifecycle
• employeePulse
• surveyPlatform
• threeSixty

BrandPermissions

• DigitalExperienceAnalytics
• ResearchHub
• enablePatientExperienceHub
• managerAssistDefaultActive
• useCXActionPlanning
• viewTARedesign

CustomerJourneyOptimizerPermissions

• actDataAnalyst
• actJourneyAdministrator
• actJourneyAnalyst
• actJourneyDesigner
• actJourneyPublisher

AIPermissions

• useInsightExplorer

features (Feature Flippers)

• CXUID2022
• Homepage.EnableChangeManagementBanner
• Homepage.EnableFavoritesInstructionalOverlay
• Homepage.EnableNavTour
• Homepage.EnableNewHomepageDesign
• Homepage.EnableUI
• Homepage.FAM.ServeHomepageAssets
• Homepage.LocalizeNavTour
• Portals.EnablePortalsHomepage
• Portals.HpsCollection.DisableWrites
• Portals.PbaCollection.EnableWrites
• Portals.PbaCollection.SwitchReads
• RP.UseRSDKReleaseCandidate
• Widgets.EnablePinning
• XMNotifications.HomepageNotificationsRevamp
• XMNotifications.HomepagePrefetchInternal
• XMNotifications.HomepageUseRevampedEndpoints
• XMMobileFrontlineExperience

URL Allow List

The URLAllowList property is used to control which URLs can be displayed within a tab and how URLs are routed to your app. For detailed information about URL handling and best practices, see Display Qualtrics Pages.