Setup notes and best practices

Master token

Copy

In order to make use of the Tray Embedded APIs, an admin/owner of the Embedded account will need to create a Master Token.

This is generated in the Tokens section under Settings in your dashboard:

Embedded ID

Copy

You can set your Embedded ID (i.e. your company name or initials) in the Embedded Settings section.

This is required for loading Config Wizard CSS.

It is also passed as a parameter in the url for the Config Wizard:

Org / Environment setup

Copy

It is not currently possible to create Embedded Solutions in custom workspaces.

Therefore Solutions need to be created in the main 'Embedded' workspace.

Thus it is generally recommended to have multiple Tray accounts for e.g. dev, staging and prod and then promote from one account to the next.

Please see Environment Promotion for more information.

Setting alerts

Copy

You should configure an alerting Workflow which makes use of the Solution Alert Trigger In order to be alerted about any errors that are occurring with Solution Instances / Solutions / Workflows.

This is useful in terms of a 'helicopter view' of the overall health of your projects - which solutions and solution instances are causing problems.

Please see our page on Error handling (Embedded) for more information.

Custom OAuth apps

Copy

When delivering third-party app integrations, Tray strongly recommends that you use your own third-party Custom OAuth apps when going to production.

This will ensure:

1. Your customers can receive a branded, White-labeled authentication experience with no mention of Tray. 

2. This approach ensures that all necessary security approvals and reviews are communicated directly between you and the third-party vendor.

3. OAuth app reviews are common practice by third-party vendors and can impact uptime. You would have complete control over this process by using your own OAuth app.

User database

Copy

When presenting integrations to your users natively within your app, you should prepare a user model to store the Tray user IDs and details of solution Instances they are subscribed to.

This would allow you to serve your users faster and provide better UX.

Here is an example of what you may want to store for a user:

1
{
2
  "trayId": "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6",
3
  "userId": "23r8h29f",
4
  "userName": "Elmer Fudd",
5
  "solutionInstances": [
6
    {
7
      "solutionInstanceId": "jidajw9e-xxxx-xxxx-xxxx-9dy8ahd3hns6",
8
      "name": "Salesforce opportunities to Slack",
9
      "solutionId": "djaw821s-xxxx-xxxx-xxxx-s879hsqhjs27",
10
      "workflows": [
11
        {
12
          "workflowId": "dguyq28w-xxxx-xxxx-xxxx-dbjhasb12834",
13
          "workflowName": "Notify for opportunities"
14
        },
15
        {
16
          "workflowId": "dfta7rtg-xxxx-xxxx-xxxx-hdggea82tesb",
17
          "workflowName": "Send error messages"
18
        }
19
      ]
20
    }
21
  ],
22
  "authentications": [
23
    {
24
      "serviceEnvironmentId": "e6bc22a4-xxxx-xxxx-xxxx-828d6627aeea",
25
      "serviceEnvironmentTitle": "Acme Slack Custom OAuth app",
26
      "name": "Elmer Fudd Slack auth",
27
      "authId": "5eae2edb-xxxx-xxxx-xxxx-8dd913036b7a"
28
    },
29
    {
30
      "serviceEnvironmentId": "23f83f3e-xxxx-xxxx-xxxx-3498g384g43g",
31
      "serviceEnvironmentTitle": "Acme Salesforce Custom OAuth app",
32
      "name": "Elmer Fudd Salesforce auth",
33
      "authId": "27wdf-xxxx-xxxx-xxxx-f9384hf34f8as5"
34
    }
35
  ]
36
}

Callable workflows

Copy

The Call Workflow connector and Callable Trigger are very powerful tools when used together.

Together they allow you to simplify your workflows by allowing you to work with a 'modular' approach - i.e. multiple workflows can gather data before calling one workflow which can carry out the actual processing tasks (calculations, updating of records etc.)

A basic explanation of setting up a callable workflow can be seen on the Callable Trigger page.

Please see our Using callable workflows documentation for more information on best practices and advanced usage - such as processing large volumes of data.

Embedded setup gotchas

Copy

Custom JS

Copy

If you wish to use Custom JS please contact support to arrange turning on the feature flag

Creating solution instances

Copy

Requires Embedded ID in Settings. - The Embedded ID must be unique per account, or there will be error when creating solution instances per account. i.e., it must be different in all Tray accounts if a customer has multiple accounts in the same region. (This is due to the Custom CSS is attached to account and it requires unique access path)

Architectural views

Copy

Use solution instance ID (give an example of how to set this up) in data storage or csv key names if the scope is Workspace, this is to ensure uniqueness of the key per end user and prevent reaching limitations on data size per unique key- Concurrency measures that people should take to prevent any issues arising

Custom CSS

Copy

While the components are pre-defined in Tray, not only the look and feel can be customised, the action buttons and activity indicators can also be re-positioned