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/falseDefault: 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

  • 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.

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/falseDefault: 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 WorkspaceFormat: Boolean (true/falseDefault: true (users are allowed to select workspaces)  
  • displayAccountPage (required) The flag that allows or forbids users to access their account details under [username] > AccountFormat: Boolean (true/falseDefault: 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

  • 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 TicketFormat: 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

  • 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/falseDefault: 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/falseDefault: 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/falseDefault: false (the hyperlink is enabled)

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:

  1. 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).

  2. 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.

  3. 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: !=