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.

Contents:

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

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 projects on the project picker menu located in [username] > Account > Active Project.
    Format: Boolean (true/false)
    Default: true (users are allowed to select projects)
     
  • 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. For more information, 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.
    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 project 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 form on the Login page. When the link is hidden, users cannot register without being invited.
    Format: Boolean (true/false)
    Default: true (the registration form 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 project 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 project 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:

  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.

      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.

  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: !=
Powered by Atlassian Confluence and Scroll Viewport.