Tray Embedded / Core Topics / Whitelabelling

Whitelabelling

When creating Tray Embedded integrations you will generally want to 'whitelabel' all parts of the integration so that Tray.io branding is not visible anywhere.

Following is a list of all the features which require white-labelling, and how it is done:

Public / webhook urls

When your End Users create Solution Instances, the Workflow Instances found within will have automatically-generated public urls.

These are needed for any external services which are configured to communicate with these Workflow Instances via webhook.

The standard format for a webhook url is:

https://fc2e17f9-xxxx-xxxx-xxxx-537f62e78c57.trayapp.io

If you wish to remove the trayapp.io suffix it is possible to use the de-branded *.integration-hook.com suffix instead.

Please contact your customer success representative if you wish to set this up.

Config Wizard urls

When you launch the Config Wizard you will notice that the urls in the browser use the embedded.tray.io domain:

It is possible to overwrite this by using the *.integration-configuration.com domain.

In this case you can prefix this with any subdomain which identifies your company to the End User.

So if your company is ‘Acme’ all you need to do is open the Config Wizard with https://acme.integration-configuration.com/external/solutions/${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}

Instead of: https://embedded.tray.io/external/solutions/${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}

Note that the *.integration-configuration.com domain is wildcarded so you can prefix it with whatever you wish - acme, acmeltd, acmeco etc.

If you whitelabel the Config Wizard url you will also have to create custom auth apps for the services being used in your integration to allow for the change in the redirect url. Please see the section below and the relevant linked docs page for more information on how this is set up

Config Wizard CSS

The Config Wizard is a Tray.io component which you use to hand over the Solution Instance configuration process to. But it is possible to edit the CSS and styling of its components.

Please the Config Wizard CSS page for details.

Config Wizard authentication (custom OAuth apps)

In the Config Wizard, when End Users are authenticating with services which use the OAuth protocol (Salesforce, Slack etc.), the dialog will display Tray.io branding such as the following for Slack:

To ensure your End Users do not see the Tray.io logo and 'Tray.io is requesting...' message you will need to contact your Customer Success representative to arrange setting up custom OAuth app(s).

This will involve setting up the custom app / environment in the relevant service(s) and then sending us the key details:

  • Client Id
  • Client Secret
  • Service (Connector)
  • Connector Version (can be found under advanced properties)
  • A name for the Custom OAuth App (this is for internal use, in case you decide to have multiple OAuth apps for a single service. Often the naming convention is relative to the specific integration you'll be using the app for)
  • A list of Tray.io Login emails to enable this service for

Important note on Redirect URIs

In order for a solution to leverage your Oauth app, we will create an environment for the service on our end. You will then need to create an authentication that uses the environment (see Using custom OAuth apps in your Solutions).

In order for this step to work, your Oauth app will need to have the default Tray.io redirect URI (https://auth.tray.io/oauth2/token) set.

When you then use your config wizard, this will use a different redirect URI according to the domain you're using.

For some Oauth services such as Salesforce (see below), you are allowed to specify multiple redirect URIs which means you can set both URIs during the app creation.

However most Oauth services, such as Zendesk, only allow you to specify a single redirect URI at a time. In this case, you will need to do the following:

  1. Create the Oauth app (in e.g. Zendesk) with the redirect URI set to the default https://auth.tray.io/oauth2/token Tray.io URI
  2. Wait for Tray.io to create the Oauth environment in your account
  3. Create an authentication attached to the environment in your solution's workflow
  4. Amend the Oauth app settings (in e.g. Zendesk) to use the redirect URI for your whitelabelled domain
  5. Publish the solution

The last step is crucial in ensuring that your Oauth app is used in the config wizard for your solution.

All of the above is sensitive information, so please coordinate with your Tray.io contact in order to submit this information in a secure fashion

Example setup for Salesforce

In Salesforce, you will want to navigate to Setup, and then in the Quick Find, search for "App Manager". Now, click on "New Connected App", which will load a form where you will enter the information for your new app.

We recommend the following set up:

SettingValue
Connected App NameThe name you want to appear to customers during the login consent screen, e.g. Acme
API NameThis will usually default to the same as the Connected App Name
Contact EmailThe email address of your support team to handle issues that may arise
Logo Image URLThe image to show to your customers during the consent screen
Enable OAuth SettingsTicked
Callback URLYou will want to enter the following URL in this field: https://auth.tray.io/oauth2/token. This will ensure that you are able to create an authentication inside a Tray.io workflow. In addition, if you are using a whitelabelled domain such as [acme].integration-configuration.com, you will want to include the URL as https://[acme].integration-authentication.com/oauth2/token in this field. This is important for ensuring that your config wizard auth dialog works with your app
Selected OAuth ScopesSelect the required scopes for your integration. For a reference of the scopes used by Tray.io's app, when you create an authentication in the workflow builder you can look at what scopes are being asked for

All other settings in Basic Information can be filled out to further customise your application, other settings can be left as-is.

Send the app details to Tray.io

In order for your app to be usable with Tray.io, you will need to send the following to your customer success representative:

  • Consumer Key

  • Consumer Secret

It can take up to 10 minutes from creating your app for it to be ready and usable

Using custom OAuth apps in your Solutions

Once we have configured the environment for you, you can make use of it in your Solutions.

When the connector is added to a workflow, you must create an authentication (as you usually do when configuring and testing the workflow) and select the configured environment you wish to use, via the drop-down which appears at the top of the dialog:

From the above screenshot you can see that OAuth scopes are selected for this authentication. These scopes will then be set for any End User who authenticates when creating a Solution Instance based on this source workflow.

The key outcome here is that, when End Users are creating an authentication for this service they will automatically be logging into the correct environment and therefore the Tray.io branding will be removed: