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.

Obtaining OAuth app approval for a third-party service can vary in time and effort. Partner with your Account Team to assess your individual situation.

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.