You are viewing our older product's guide. Click here for the documentation of GoodData Cloud, our latest and most advanced product.

Customize the White-Labeled Domain

Customizing a white-labeled domain is done via the API. If you do not have a technical administrator or developer who can work with APIs, contact GoodData Support.

When you create a white-labeled domain, references to GoodData in the Portal, error messages, and the Glossary of the Metric Editor are automatically replaced.

Customizable Elements

When customizing your white-labeled domain, verify that all assets specified by URL (such as logo images, favicon image, and so on) are in locations that are publicly available on the Internet. To see how customized versions of these elements appear in the GoodData Portal, see What You Can White-Label.

Graphics and text

organizationName (required) The name of your organization on the GoodData platform. This value is used in the copyright text (for example, Copyright 2020 {organizationName}, all rights reserved) and in the body of emails generated by the Portal. This value is not displayed in the Portal footer. Format: String Example: My Analytics Default: GoodData
logoUrl (required) The URL pointing to the logo displayed in the top-left corner of the Portal. The logo image must be in the PNG format. Acceptable image dimensions (in px): 120x25 Format: Fully qualified or relative URL Example: /images/logo.png Default: /images/header/logo.png
applicationTitle (required) Text in the browser title bar or tab title; also appears on the Registration and Login pages. Format: String Example: My Analytics Default: GoodData
isBranded (optional) The flag that shows or hides the following elements:
- The Documentation link under Help and in the Portal footer
- The question mark icons indicating the embedded help
- (For embedded mode only) The GoodData logo in the top right corner
Format: Boolean (true/false) Default: true (the elements are hidden)
faviconUrl (optional) The URL pointing to the image that appears in the browser address bar. The favicon image must be in the ICO format. Acceptable image dimensions (in px): 16x16, 32x32, 48x48, or 64x64 Format: Fully qualified or relative URL Example: /images/portal/favicon.ico Default: /images/favicon.ico
appleTouchIconUrl (optional) The URL pointing to the desktop icon that iOS users see when they save a GoodData page to the desktop. The icon image must be in the PNG format. Acceptable image dimensions (in px): 114x114 Format: Fully qualified or relative URL Example: /images/apple_icon.png Default: /images/appleTouchIcon.png
applicationBackgroundColor (optional) The custom background color for the dashboard in the Dashboards section. This color is not applied to the Login, Logout, Registration, Invitation, or Confirmation pages. If you specify both a dashboard image and a color, the image is displayed on top of the background color. Format: HTML hex color code Example: #999
activeColor (optional) The custom underline color on active navigation elements in the Dashboards section. Format: HTML hex color code Example: #F7FE2E Default: #FFF
highlightColor (optional) The color of a highlighted or selected element (link, button, selected item in a dropdown, and so on) on a dashboard in the Dashboards section. This setting is valid only when you have the new look-and-feel of the Dashboards section enabled (see “Switch to the new look-and-feel of the Dashboards section” in Configure Various Features via Platform Settings). Format: HTML hex color code Example: #E14E2E
Set highlightColor to a color that has enough contrast to be clearly visible on the white dashboard background. Avoid too light colors.
headerTextColor (optional) The color for the text on the dashboard header. Format: HTML hex color code Example: #610B38 Default: #000 or #FFF
headerColor (optional) The color for the dashboard header. Format: HTML hex color code Example: #FF0040 Default: #000

Custom themes

For details, see Create Custom Themes.

In GoodData, terms workspace and project denote the same entity. For example, project ID is exactly the same as workspace ID. See Find the Workspace ID.

UI elements to toggle on and off

displayFlashNews (required) The flag that shows or hides the status bar that appears in the Portal after a new GoodData platform release. This status bar links to information published by GoodData. Format: Boolean (true/false) Default: true (the status bar is shown)
displayProjects (required) The flag that allows or forbids users to select workspaces on the workspace picker menu located in [username] > Account > Active Workspace. Format: Boolean (true/false) Default: true (users are allowed to select workspaces)
displayAccountPage (required) The flag that allows or forbids users to access their account details under [username] > Account. Format: Boolean (true/false) Default: true (users are allowed to access account details)

WalkMe configuration

walkMe (optional) The ID pointing to your WalkMe configuration. WalkMe configurations can be displayed everywhere in the Portal except for the KPI Dashboards and CSV Uploader. The ID is a part of your custom WalkMe URL: https://cdn.walkme.com/users/{your_id}/walkme_{your_id}_https.js Format: String Example: 9co9eaewd2b3ntqz3slw9co9eaewd2b3

Email addresses and URLs

For the elements under this section, you can set custom values, or you can also hide their corresponding visual elements from the UI.

For example:

Disabling the trustUrl setting hides the Trust link from the Portal footer.
Disabling the termsOfUse setting hides the Terms of Use link from the Portal footer and the whole text section starting with “I agree with the GoodData Terms of Use…” from the Registration page.

For more information about disabling these settings, see Update White-Labeling Settings.

supportEmail (optional) - under the portalSettings section, not to be confused with supportEmail under the mailSettings section, see Email elements The email address to which tickets are sent when users select Help > Submit Ticket. Format: String in the format of an email address Example: support@myanalytics.com Default: support@gooddata.com
supportForumUrl (optional) The URL to which users are directed when they select Help > Visit Support Portal or click Customer Support in the Portal footer. Format: Fully qualified or relative URL Example: /support/tickets Default: https://support.gooddata.com
privacyPolicyUrl (optional) The URL to which users are directed when they select [username] > Account > Personal Information > privacy policy or click Privacy Policy in the Portal footer. Format: Fully qualified or relative URL Example: /privacy Default: http://www.gooddata.com/privacy.html
documentationUrl (optional) The URL to which users are directed when they select Help > Documentation or click Help in the Portal footer. Format: Fully qualified or relative URL Example: /online/help Default: https://help.gooddata.com/doc/
securityStatementUrl (optional) The URL to which users are directed when they click Security Statement in the Portal footer. Format: Fully qualified or relative URL Example: /security Default: http://www.gooddata.com/security.html
termsOfUseUrl (optional) The URL to which users are directed when they click Terms of Use in the Portal footer or on the Registration page. Format: Fully qualified or relative URL Example: /tos Default: http://www.gooddata.com/terms.html
trustUrl (optional) The URL to which users are directed when they click Trust in the Portal footer. Format: Fully qualified or relative URL Example: /trust Default: http://www.gooddata.com/trust/

SSO configuration

For more information about SSO, see Set up User Authentication and SSO.

ssoExpiredUrl (optional) The URL of the custom “Not authorized” page to which users are directed instead of the default GoodData Not authorized page when their SuperSecure Token expires or is not valid. To enable this setting, set showSSOCustomUnauthorizedLoginPage to true (see further in this section). Format: Fully qualified or relative URL Example: /expired
ssoUnauthorizedUrl (optional) The URL of the custom “Not authorized” page to which users are directed instead of the default GoodData Not authorized page when the users are trying to access a workspace that they are not authorized to access or when the users do not have a GoodData account. To enable this setting, set showSSOCustomUnauthorizedLoginPage to true (see further in this section). Format: Fully qualified or relative URL Example: /unauthorized
ssoLogoutUrl (optional) The URL of the custom Logout page to which users are directed instead of the default GoodData Logout page when they are logging out of the application. Format: Fully qualified or relative URL Example: /logout
showSSOCustomUnauthorizedLoginPage (optional) The flag that controls what page users logged in by SSO are directed to: the default GoodData Login page (false; default) or a custom “Not authorized” page (true; the URL of the custom “Not authorized” page is defined by either the ssoExpiredUrl setting or the ssoUnauthorizedUrl setting depending on the users' authorization status). Format: Boolean (true/false) Default: false (the users are directed to the default GoodData Login page)

Login and Registration page elements

brandColor (optional) The color of the narrow strip on the top of the Login and Registration pages. Format: HTML hex color code Example: #999 Default: #000
largeLogoUrl (optional) The URL pointing to the logo displayed on the Login and Registration pages. The preferable format of the logo image is PNG. Acceptable image dimensions: up to 130 px height, up to 470 px width Format: Fully qualified or relative URL Example: /images/large_logo.png Default: /images/logo-new.png
hideRegistration (optional) The flag that shows or hides the link to the Registration page on the Login page. When the link is hidden, users cannot register without being invited. Format: Boolean (true/false) Default: true (the link to the Registration page is hidden)

Email elements

For more information about specific email templates, see Email Templates.

noReplyEmail (required) The email address from which scheduled reports are sent. Format: String in the format of an email address Example: no-reply@myanalytics.com Default: no-reply@gooddata.com
registrationEmail (required) The email address from which registration confirmation emails and forgotten password emails are sent. Format: String in the format of an email address Example: registration@myanalytics.com Default: registration@gooddata.com
invitationEmail (required) The email address from which workspace invitation emails are sent. Format: String in the format of an email address Example: invitation@myanalytics.com Default: invitation@gooddata.com
supportEmail (required) - under the mailSettings section, not to be confused with supportEmail under the portalSettings section, see Email addresses and URLs The email address to which emails to your customer support are sent; also appears in the body of some emails. Format: String in the format of an email address Example: support@myanalytics.com Default: support@gooddata.com
supportPhone (required) The phone number for reaching your Customer Support. This phone number appears in email templates. Format: String Example: +1 234 567 89 01
suppressProjectLinks (optional) The flag that enables and disables hyperlinks for the workspace in email footers. This is primarily used with white-labeled dashboards where the hyperlink leads to a GoodData-branded view of the relevant dashboard. Format: Boolean (true/false) Default: false (the hyperlink is enabled)

Update White-Labeling Settings

You must be a domain admin to update white-labeling settings.

Customizing a white-labeled domain is done via the API.

To update white-labeling settings, you must first obtain your current white-label settings, update them as you need, and then submit them back.

Steps:

Use the API for retrieving white-labeling settings:
- API resource: https://secure.gooddata.com/gdc/organizations/{domain_name}/settings
- Method: GET
- Request headers:
```
Content-Type: application/json
Accept: application/json
```
The API returns the current settings for your domain (for an example what the response may look like, see Sample JSON).
Copy the returned JSON from the response and update the settings as you need. For information about individual settings, see Customizable Elements.
- The settings that you do not change and submit them exactly as you obtained them in Step 1 will not change.
- The settings that you change and submit with a new value will be updated.
- The settings that you delete from the JSON will be reset to their defaults.
  You can delete only optional settings from the JSON. Omitting a required setting will return an error in the next step of this procedure.
  If you omit a setting from the section Email addresses and URLs, its corresponding visual element will be hidden from the UI. For example, omitting the trustUrl setting will hide the Trust link from the Portal footer; omitting the termsOfUse setting will hide the Terms of Use link from the Portal footer and the whole text section starting with “I agree with the GoodData Terms of Use…” from the Registration page.
Use the API for updating white-labeling settings to submit the new settings:
- API resource: https://secure.gooddata.com/gdc/organizations/{domain_name}/settings
- Method: PUT
- Request headers:
```
Content-Type: application/json
Accept: application/json
```
- Request body: Use the updated JSON from Step 2 (for an example what the request may look like, see Sample JSON)
The API returns an HTTP status code of 204, which indicated that the white-label settings have been updated.

Sample JSON

The following sample illustrates the structure of the JSON payload that you receive when obtaining your white-labeling settings.

It also represents an example of the JSON that you should include in the request body.

{
  "settings": {
    "mailSettings": {
      "noReplyEmail": "no-reply@myanalytics.com",
      "registrationEmail": "registration@myanalytics.com",
      "invitationEmail": "invitation@myanalytics.com",
      "supportEmail": "support@myanalytics.com",
      "supportPhone": "+1 234 567 89 01",
      "suppressProjectLinks": true
    },
    "portalSettings": {
      "organizationName": "My Analytics",
      "logoUrl": "/images/logo.png",
      "applicationTitle": "My Analytics",
      "displayFlashNews": false,
      "displayProjects": false,
      "displayAccountPage": false,
      "isBranded": false,
      "faviconUrl": "/images/portal/favicon.ico",
      "appleTouchIconUrl": "/images/apple_icon.png",
      "applicationBackgroundColor": "#999",
      "activeColor": "#F7FE2E",
      "highlightColor": "##F7FE2E",
      "headerTextColor": "#610B38",
      "headerColor": "#FF0040",
      "walkMe": "9co9eaewd2b3ntqz3slw9co9eaewd2b3",
      "supportEmail": "support@myanalytics.com",
      "supportForumUrl": "/support/tickets",
      "privacyPolicyUrl": "/privacy", 
      "documentationUrl": "/online/help",
      "securityStatementUrl": "/security",
      "termsOfUseUrl": "/tos",
      "trustUrl": "/trust",
      "ssoExpiredUrl": "/expired",
      "ssoUnauthorizedUrl": "/unauthorized",
      "ssoLogoutUrl": "/logout",
      "showSSOCustomUnauthorizedLoginPage": true,
      "brandColor": "#999",
      "largeLogoUrl": "/images/large_logo.png",
      "hideRegistration": false
    }
  }
}

Calling the API from a White-Labeled Domain

When executing calls to the APIs after migrating to the white-labeled domain, use the white-labeled domain name.

To perform calls using https://secure.gooddata.com after migrating to the white-labeled domain, include the following HTTP header:

X-GDC-CHECK-DOMAIN=false

If you forget this header, you receive an error message like the following:

javax.net.ssl.SSLException: hostname in certificate didn't match: !=

Coordinate Rollout