Storing users and integrations

For your integrations you will need to manage:

Users and their authentications
The connectors, operations, input schema and service environments involved in each integration

Exactly how you manage these will of course be up to you, and there will be specific approaches you will take depending on your use case.

However we generally recommend that you create databases on your own infrastructure to manage your users and integrations, for the following reasons:

Tray’s connectors and operations are regularly updated as and when the underlying third-party API changes.
Storing the input schema for the individual operations your integration makes use of gives you complete control over the UI form presented to your End Users
A user model is needed to store the Tray user IDs and details of integrations configured by an End User in order to show them their list of configured integrations when they log in to your service
Your UI would be much slower if you were to make an API call for every End User interaction .
For scalable solutions, relying only on APIs could cause latency issues . A caching system can go a long way toward improving UX.

User database

The following simple visual gives an overview of how you might store users and their auths:

users-database

For each user you could store the following details:

Tray userId (returned by Create User mutation)
externalUserId (pass as an input in Create User mutation to link user to your external db)
Tray user name

And for each of their auths:

name
authId
Service Environment title (e.g. Zoom Custom OAuth app)
serviceEnvironmentId

So, in json format, a sample users database might look like this:

warning

This is an example of what you might store in your own infrastructure, therefore the exact names of fields (e.g. trayID or userName) is up to you!

info

Remember that, when creating users in Tray with Create new user (Embedded GraphQL mutation), you will need to specify an externalId which links the user to their entry in your own db. In the below example this is represented by userId (this could be anything you wish - UUID, email address etc.)

Copy

Copied

{
  "users": [
    {
      "trayId": "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6",
      "userId": "23r8h29f",
      "userName": "Elmer Fudd",
      "authentications": [
        {
          "serviceEnvironmentId": "e6bc22a4-xxxx-xxxx-xxxx-828d6627aeea",
          "serviceEnvironmentTitle": "Acme Jira Custom OAuth app",
          "name": "Elmer Fudd Jira auth",
          "authId": "5eae2edb-xxxx-xxxx-xxxx-8dd913036b7a"
        },
        {
          "serviceEnvironmentId": "23f83f3e-xxxx-xxxx-xxxx-3498g384g43g",
          "serviceEnvironmentTitle": "Acme Asana Custom OAuth app",
          "name": "Elmer Fudd Asana auth",
          "authId": "27wdf-xxxx-xxxx-xxxx-f9384hf34f8as5"
        }
      ]
    },
    {
      "trayId": "d83325-XXXX-XXXX-XXXX-ac3f23f2r8b6",
      "userId": "23f923ff",
      "userName": "Bugs Bunny",
      "authentications": [
        {
          "serviceEnvironmentId": "e6bc22a4-xxxx-xxxx-xxxx-828d6627aeea",
          "serviceEnvironmentTitle": "Acme Jira Custom OAuth app",
          "name": "Bugs Bunny Jira auth",
          "authId": "5e23e23e-xxxx-xxxx-xxxx-ef9393hef6b7a"
        },
        {
          "serviceEnvironmentId": "23f83f3e-xxxx-xxxx-xxxx-3498g384g43g",
          "serviceEnvironmentTitle": "Acme Asana Custom OAuth app",
          "name": "Bugs Bunny Asana auth",
          "authId": "23r23r3-xxxx-xxxx-xxxx-f9384hf34f8as5"
        }
      ]
    }
  ]
}

Integrations database

The following simple visual gives an overview of how you might store your integrations:

integrations-database

For each connector in your integration, you might want to store:

Details of the Tray Service
The auth input schemas of your Custom OAuth app

Both of the above are obtained using the Get service environments endpoint

So, in json format, a sample integrations database might look like this:

warning

This is an example of what you might store in your own infrastructure, therefore the exact names of fields (e.g. trayService or customOAuthApp) is up to you!

Copy

Copied

{
  "integrations": [
    {
      "name": "Jira tasks to Asana",
      "connectors": [
        {
          "name": "jira-cloud",
          "version": "2.0",
          "trayService": {
            "id": "6c9a3924-xxxx-xxxx-xxxx-9765d1b635d9",
            "name": "jira-cloud",
            "version": 1
          },
          "customOAuthApp": {
            "id": "634dadf7-xxxx-xxxx-xxxx-446233ac09e9",
            "title": "Acme Jira Custom OAuth app",
            "userDataSchema": {...},
            "credentialsSchema": {...},
            "scopes": [...]
          },
           "operations": ['list_project_issues', 'get_issue']
        },
        {
          "name": "asana",
          "version": "4.11",
          "trayService": {
            "id": "238r923r-xxxx-xxxx-xxxx-23r238935215",
            "name": "asana",
            "version": 1
          },
          "customOAuthApp": {
            "id": "92323r32-xxxx-xxxx-xxxx-329fj23f093j",
            "title": "Acme Asana Custom OAuth app",
            "userDataSchema": {...},
            "credentialsSchema": {...},
            "scopes": [...]
          },
          "operations": ['update_task']
        }
      ],
      "formInputSchema": {
       ...
      }
    },
    {
      "name": "Gcal and Zoom",
      "connectors": [
        {
          "name": "calendar",
          "version": "4.0",
          "trayService": {
            "id": "fcf2d82f-xxxx-xxxx-xxxx-11c01cf1f28c",
            "name": "google-calendar",
            "version": 2
          },
          "customOAuthApp": {
            "id": "928efh2f-xxxx-xxxx-xxxx-23f823f23",
            "title": "Acme GCal Custom OAuth app",
            "userDataSchema": {...},
            "credentialsSchema": {...},
            "scopes": [...]
          },
          "operations": ['update_event', 'list_events']
        },
        {
          "name": "zoom",
          "version": "2.1",
          "trayService": {
            "id": "44d802b4-xxxx-xxxx-xxxx-80c53f6799eb",
            "name": "zoom",
            "version": 2
          },
          "customOAuthApp": {
            "id": "839fh2f-xxxx-xxxx-xxxx-09238h33",
            "title": "Acme Zoom Custom OAuth app",
            "userDataSchema": {...},
            "credentialsSchema": {...},
            "scopes": [...]
          },
          "operations": ['create_meeting']
        }
      ],
      "formInputSchema": {
       ...
      }
    }
  ]
}