Solution Instances

Solution Instances are the end user's configuration of your Solutions. Instances contain their own auths and config data.

Get solution instances (user/master token)

post/

Return the Solution Instances associated with a particular user.

Pay particular attention to solutionVersionFlags as a piece of returned data, which indicates if the Instance needs upgrading due to new information being required from the End User. For more information, refer the decision table.

Required token Notes
Master Obtained from the Tray app UI. Refer this.
If using a Master token it is possible to filter Solution Instances by the owner of the Solution Instance, or by the ID of the Solution which it came from
User obtained after creating a user token (Users/Mutations/Create User Token)
the user token is a persistent token (valid for 2 days) that should be securely stored in your application
If a User token is used, the Solution Instances displayed will only be those owned by that End User

The query accepts the following filter criteria:

Criteria Notes
solutionId Can be used to filter based on the Solution which the Instance came from. If used with a User Token it will only return instances owned by that user
owner This is the userId of an End User. Can only be used with a Master Token, in order to filter Solution Instances of a particular user

Note that it is possible to filter by both owner and solutionId at the same time.

Returned Data Subfields Notes
totalCount Note this is a top-level field, so is specified before 'edge' as per example query below
The results returned by the totalCount will depend on the filter criteria specified:
If solutionId is specified the total count will refer to the solution instances for that particular solution
If owner (userId) is specified (when using a Master Token) the total count will refer to the solution instances for that end user
If owner and solutionId are both specified the total count will refer to the solution instances for that user and for that solution
id the solutionInstance id
name the name (derived from the parent Solution)
enabled boolean to indicate whether the solutionInstance has been activated using Update Solution Instance
created the date and time the solutionInstance was created
solutionVersionFlags hasNewerVersion
requiresUserInputToUpdateVersion
requiresSystemInputToUpdateVersion
boolean flags used to indicate if an underlying Solution has a newer version which might need upgrading as explained in Updating / Upgrading Solution Instances
solution id
title
description
customFields
configSlots
authSlots
details of the parent Solution
workflows id
triggerUrl
sourceWorkflowId
sourceWorkflowName
triggerUrl is the webhook url for the End User's version of that workflow (see Retrieving Webhook URLs)
configValues externalId
value
any config data that has been set for the End User of the solutionInstance
authValues externalId
authId
authentications associated with this solutionInstance

Pagination

You can paginate the results of this query using the methods discussed in Pagination

Here are some example queries:

Get solution instance(s) by owner - Master Token
query {
    viewer {
        solutionInstances(criteria: { owner: "13b3ab9c-XXXX-XXXX-XXXX-c4dd07fbbfa4" }) {
            edges {
                node {
                    id
                    name
                    enabled
                    owner
                    created
                    solutionVersionFlags {
                        hasNewerVersion
                        requiresUserInputToUpdateVersion
                        requiresSystemInputToUpdateVersion
                    }
                    workflows {
                        edges {
                            node {
                                triggerUrl
                                id
                                sourceWorkflowId
                sourceWorkflowName
                            }
                        }
                    }
                    authValues {
                        externalId
                        authId
                    }
                    configValues {
                        externalId
                        value
                    }
                }
                cursor
            }
            pageInfo {
                startCursor
                endCursor
                hasNextPage
                hasPreviousPage
            }
        }
    }
}
Get solution instance(s) by owner and solution ID - Master Token
query {
    viewer {
        solutionInstances(criteria: { 
                solutionId: "b73d4e07xxx-xxx-xxx-xxx-xxxafad23d94",
                owner: "13b3ab9c-XXXX-XXXX-XXXX-c4dd07fbbfa4" 
            }) {
            edges {
                node {
                    id
                    name
                    enabled
                    owner
                    created
                    solutionVersionFlags {
                        hasNewerVersion
                        requiresUserInputToUpdateVersion
                        requiresSystemInputToUpdateVersion
                    }
                    workflows {
                        edges {
                            node {
                                triggerUrl
                                id
                                sourceWorkflowId
                                sourceWorkflowName
                            }
                        }
                    }
                    authValues {
                        externalId
                        authId
                    }
                    configValues {
                        externalId
                        value
                    }
                }
                cursor
            }
            pageInfo {
                startCursor
                endCursor
                hasNextPage
                hasPreviousPage
            }
        }
    }
}
SecuritybearerAuth
Request
Responses
200

OK - If master token is used, an array of solution instances for all end users is returned. In case of user token, only instances owned by the user are returned.

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples
curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <USER_OR_MASTER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query ($ownerId: String!){\n\tviewer {\n\t\tsolutionInstances(criteria: { owner: $ownerId }) {\n\t\t\tedges {\n\t\t\t\tnode {\n\t\t\t\t\tid\n\t\t\t\t\tname\n\t\t\t\t\tenabled\n\t\t\t\t\towner\n\t\t\t\t\tcreated\n\t\t\t\t\tsolutionVersionFlags {\n\t\t\t\t\t\thasNewerVersion\n\t\t\t\t\t\trequiresUserInputToUpdateVersion\n\t\t\t\t\t\trequiresSystemInputToUpdateVersion\n\t\t\t\t\t}\n\t\t\t\t\tworkflows {\n\t\t\t\t\t\tedges {\n\t\t\t\t\t\t\tnode {\n\t\t\t\t\t\t\t\ttriggerUrl\n\t\t\t\t\t\t\t\tid\n\t\t\t\t\t\t\t\tsourceWorkflowId\n                                sourceWorkflowName\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\tauthValues {\n\t\t\t\t\t\texternalId\n\t\t\t\t\t\tauthId\n\t\t\t\t\t}\n\t\t\t\t\tconfigValues {\n\t\t\t\t\t\texternalId\n\t\t\t\t\t\tvalue\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tcursor\n\t\t\t}\n\t\t\tpageInfo {\n\t\t\t\tstartCursor\n\t\t\t\tendCursor\n\t\t\t\thasNextPage\n\t\t\t\thasPreviousPage\n\t\t\t}\n\t\t}\n\t}\n}",
    "variables": {
      "ownerId": "13b3ab9c-XXXX-XXXX-XXXX-c4dd07fbbfa4"
    }
  }'
Response samples
application/json
{
  • "data": {
    • "viewer": {
      • "solutionInstances": {
        • "edges": [
          • {
            • "node": {
              • "id": "533d48e8-XXXX-XXXX-XXXX-74ff887198d3",
              • "name": "Sample Instance",
              • "enabled": true,
              • "owner": "13b3ab9c-XXXX-XXXX-XXXX-c4dd07fbbfa4",
              • "created": "2019-12-03T21:11:09.456Z",
              • "solution": {
                • "id": "b73d4e07xxx-xxx-xxx-xxx-xxxafad23d94",
                • "title": "Slack webhook solution",
                • "description": "sends a message to a slack channel of your choice"
                },
              • "solutionVersionFlags": {
                • "hasNewerVersion": true,
                • "requiresUserInputToUpdateVersion": true,
                • "requiresSystemInputToUpdateVersion": false
                },
              • "workflows": {
                • "edges": [
                  • {
                    • "node": {
                      • "triggerUrl": null,
                      • "id": "89f8ebeb-XXXX-XXXX-XXXX-be070f3cd0f8",
                      • "sourceWorkflowId": "3af6461f-XXXX-XXXX-XXXX-91ada5769f90"
                      }
                    }
                  ]
                },
              • "authValues": [
                • {
                  • "externalId": "external_slack_authentication",
                  • "authId": "dcbc11f1-XXXX-XXXX-XXXX-b7f90dafcf28"
                  }
                ],
              • "configValues": [ ]
              },
            • "cursor": "NTMzZDQ4ZTgtNjM2Zi00M2FkLTk1ZjItNzRmZjg4NzE5OGQz"
            }
          ],
        • "pageInfo": {
          • "startCursor": "NTMzZDQ4ZTgtNjM2Zi00M2FkLTk1ZjItNzRmZjg4NzE5OGQz",
          • "endCursor": "NTMzZDQ4ZTgtNjM2Zi00M2FkLTk1ZjItNzRmZjg4NzE5OGQz",
          • "hasNextPage": false,
          • "hasPreviousPage": false
          }
        }
      }
    }
}

Create solution instance (user token)

post/

This mutation is used to create a Solution Instance for an End User who has chosen to activate a particular Solution for their own use.

The steps involved in activating a Solution Instance for an End User are:

  1. Use this mutation to create a Solution Instance which returns a id

  2. Generate a Config Wizard authorization code with Users/Mutations/Create Config Wizard Authorization Code

  3. Use the id from step 1 and the auth code from step 2 to activate the pop-up Configuration Wizard for the End User with the following url:

     https://embedded.tray.io/external/solutions/${partnerId}/configure/${solutionInstanceId}?code=${authorizationCode}
    
  4. Your app will receive a tray.configPopup.finish PostMessage as explained in Launching wizard in your code

  5. Once the Solution Instance is configured for the End User, use Solution Instances/Mutations/Update Solution Instance to set the status to 'enabled'

Required token Notes
User obtained after creating a user token (Users/Mutations/Create User Token)
the user token is a persistent token (valid for 2 days) that should be securely stored in your application

The mutation accepts the following arguments:

Argument Required Note
solutionId Yes obtained with Solutions/Queries/Get Solutions
instanceName Yes
authValues No can be used to import end user authentications.
see Importing Auths
configValues No can be used to import config data
see Importing config data

Here is an example mutation:

Create Solution Instance
mutation {
   createSolutionInstance(input: {
       solutionId: "b3422397-XXXX-XXXX-XXXX-57e7e66771b3"
       instanceName: "PetersGraphQLInstance"
   }) {
     solutionInstance {
       id
       name
       enabled
       created
       authValues {
           authId
           externalId
       }
       configValues {
           value
           externalId
       }
       solution {
           id
           title
           description
           tags
           customFields
           configSlots
       }
       workflows {
           edges {
               node {
                   id
                   sourceWorkflowId
                   sourceWorkflowName
                   triggerUrl
               }
           }
       }
       solutionVersionFlags {
           hasNewerVersion
           requiresUserInputToUpdateVersion
           requiresSystemInputToUpdateVersion
       }
     }
   }
}

It can return the following data:

Returned Data Subfields Notes
id
name
created
enabled defaults to False so must be set to True with Mutations/Solution Instances/Update Solution Instance - Enable
solution id, title, description, tags, customFields, configSlots details of the parent solution
workflows id, sourceWorkflowId, sourceWorkflowName, triggerUrl details of the source workflows, including webhook url (triggerUrl)
authValues authId, externalId details of the auths associated with the instance
configValues value, externalId details of config values associated with the user
solutionVersionFlags hasNewerVersion, requiresUserInputToUpdateVersion, requiresSystemInputToUpdateVersion boolean flags used to indicate if an underlying Solution has a newer version which might need upgrading as explained in Updating / Upgrading Solution Instances
SecuritybearerAuth
Request
Responses
200

OK - InstanceId of the newly created instance is returned

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples
curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation ($solutionId: ID!, $instanceName: String!){\n   createSolutionInstance(input: {\n       solutionId: $solutionId\n       instanceName: $instanceName\n   }) {\n     solutionInstance {\n       id\n       name\n       enabled\n       created\n       workflows {\n           edges {\n               node {\n                   id\n                   triggerUrl\n                   sourceWorkflowId\n               }\n           }\n       }\n     }\n   }\n }",
    "variables": {
      "solutionId": "b3422397-XXXX-XXXX-XXXX-57e7e66771b3",
      "instanceName": "Gene Slack star instance 2"
    }
  }'
Response samples
application/json
{
  • "data": {
    • "createSolutionInstance": {
      • "solutionInstance": {
        • "id": "625xxx-xxx-xxx-xxx-xxx111f",
        • "name": "Gene Slack star instance 2",
        • "enabled": false,
        • "created": "2019-02-25T11:02:21.884Z",
        • "workflows": {}
        }
      }
    }
}

Update solution instance (user token)

post/

The primary use of this mutation is to 'enable' the solution instance. This is a required step after creating and configuring the solution instance.

If you are auto enabling the instances for your end users after they complete the config wizard, your code should be configured to delay this enable mutation by least 2 seconds after createSolutionInstance is complete.
This mutation can also be used to update existing auth and config values that were attached after the user ran the config wizard.

If you are dealing with new auth/config settings, the parent solution will be on a new version, and the instance must be upgraded by the end user re-running the Config Wizard or using Solution Instances/Mutations/Upgrade Solution Instance. This is explained in detail in Updating/Upgrading Solution Instances

Required token Notes
User Obtained after using Users/Mutations/Create User Token.
The User Token is a persistent token that should be securely stored in your application for future use (expires after 2 days)

The mutation accepts the following arguments:

Argument Required Note
solutionInstanceId Yes obtained with Solution Instances/Queries/Get Solution Instances
instanceName No
enabled No set to True to enable the Solution Instance after it is created
authValues No accepts an array of objects. Each object has two keys: externalId and authId. Check an example mutation below to see how it will be passed
configValues No accepts an array of objects. Each object has two keys: externalId and value. Note that value is always a string. So it must be stringified if it is of any other type (object/array, boolean, number). Check an example mutation below to see how it will be passed

Here is an example mutation:

Update Solution Instance - Enable
mutation {
  updateSolutionInstance(input: {
      solutionInstanceId: "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266",
      instanceName: "test-instance", 
      enabled: true
  }) {
    solutionInstance {
      id
      name
      enabled
      created
    }
  }
}
Update Solution Instance - Update config and auth values
mutation {
  updateSolutionInstance(input: {
      solutionInstanceId: "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266",
      configValues: [
        {
          "externalId": "external_limit",
          "value": "10"
        },
        {
                "externalId": "external_datamappings",
                "value": "{\"location\":\"**********\",\"email\":\"**********\"}"
            }
      ]
      authValues: [
        { 
          "externalId": "external_slack_authentication", 
          "authId": "aaa67786-XXXX-XXXX-XXXX-97dedd1519b3"
        }
        ]
  }) {
    solutionInstance {
      id
      name
      enabled
      created
    }
  }
}
Returned Data Subfields Notes
id
name
created
enabled defaults to False so must be set to True with this mutation
solution id, title, description, tags, customFields, configSlots, authSlots details of the parent solution
workflows id, sourceWorkflowId, sourceWorkflowName, triggerUrl details of the source workflows, including webhook url (triggerUrl)
authValues authId, externalId details of the auths associated with the instance
configValues value, externalId details of config values associated with the user
solutionVersionFlags hasNewerVersion, requiresUserInputToUpdateVersion, requiresSystemInputToUpdateVersion boolean flags used to indicate if an underlying Solution has a newer version which might need upgrading as explained in Updating / Upgrading Solution Instances
SecuritybearerAuth
Request
Responses
200

OK - Updates the solution instance

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples
curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation ($solutionInstanceId: ID!, $instanceName: String!, $enabled: Boolean!) {\n  updateSolutionInstance(input: {\n      solutionInstanceId: $solutionInstanceId,\n      instanceName: $instanceName, \n      enabled: $enabled\n  }) {\n    solutionInstance {\n      id\n      name\n      enabled\n      created\n    }\n  }\n}",
    "variables": {
      "solutionInstanceId": "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266",
      "instanceName": "myCustomersSolutionInstanceName",
      "enabled": true
    }
  }'
Response samples
application/json
{
  • "data": {
    • "updateSolutionInstance": {
      • "solutionInstance": {
        • "id": "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266",
        • "name": "myCustomersSolutionInstanceName",
        • "enabled": true,
        • "created": "2019-02-25T11:02:21.884Z"
        }
      }
    }
}

Upgrade solution instance (user token)

post/

This mutation is used when a new version of a Solution has been published which contains new Config Data (which doesn't require user input) and you wish to upgrade an End User's Instance with the new Config Data, without asking them to use the Configuration Wizard again.

Please see our page on Updating / Upgrading Solution Instances for a full explanation of how to manage changes to your Workflows and Solutions.

Required token Notes
User Obtained after using Users/Mutations/Create User Token.
The User Token is a persistent token that should be securely stored in your application for future use (expires after 2 days)

The mutation accepts the following arguments:

Argument Required Note
solutionInstanceId Yes obtained with Solution Instances/Queries/Get Solution Instances
instanceName No
authValues No Can be used to import End User authentications. See Importing Auths
configValues No Can be used to import config data. See Importing config Data
clientMutationId No Only relevant if using the Relay GraphQL client

Here is an example mutation:

Update Solution Instance - Enable
mutation {
  upgradeSolutionInstance (input: {
    solutionInstanceId: "5f85b697-XXXX-XXXX-XXXX-5d7dabe22634", 
    configValues: [
      { 
        "externalId": "external_support-email", 
        "value": "support@example.com"  
      }
      ],
    authValues: [
      { 
        "externalId": "external_slack_authentication", 
        "authId": "aaa67786-XXXX-XXXX-XXXX-97dedd1519b3"
      }
      ]
  }) { 
    solutionInstance  {
      id
      configValues{
        externalId
        value
      }
      authValues{
        authId
        externalId
      }
      enabled
      owner
      created
    }
  }
}
SecuritybearerAuth
Request
Responses
200

OK - Upgrades the solution instance with new auths or configs

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples
curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation ($solutionInstanceId: ID!, $configValues: [ConfigValue!], $authValues: [AuthValue!] ){\n  upgradeSolutionInstance (input: {\n    solutionInstanceId: $solutionInstanceId, \n    configValues: $configValues,\n    authValues: $authValues\n  }) \n    { \n solutionInstance  {\n  id\n  configValues{\n    externalId\n    value\n  }\n  authValues{\n    authId\n    externalId\n  }\n  enabled\n  created\n  }\n }\n}",
    "variables": {
      "solutionInstanceId": "625xxx-xxx-xxx-xxx-xxx111f",
      "configValues": [
        {
          "externalId": "external_support-email",
          "value": "support@example.com"
        }
      ],
      "authValues": [
        {
          "externalId": "external_slack_authentication",
          "authId": "aaa67786-XXXX-XXXX-XXXX-97dedd1519b3"
        }
      ]
    }
  }'
Response samples
application/json
{
  • "data": {
    • "upgradeSolutionInstance": {
      • "solutionInstance": {
        • "id": "625xxx-xxx-xxx-xxx-xxx111f",
        • "enabled": true,
        • "created": "2019-02-25T11:02:21.884Z",
        • "configValues": [
          • {
            • "externalId": "external_support-email",
            • "value": "support@example.com"
            }
          ],
        • "authValues": [
          • {
            • "externalId": "external_slack_authentication",
            • "authId": "aaa67786-XXXX-XXXX-XXXX-97dedd1519b3"
            }
          ]
        }
      }
    }
}

Delete Solution Instance (user token)

post/

Used to delete a Solution Instance.

Required token Notes
User obtained after creating a user token (Users/Mutations/Create User Token)
the user token is a persistent token (valid for 2 days) that should be securely stored in your application

The mutation accepts the following as inputs:

Input Required Notes
solutionInstanceId Yes obtained with Solution Instances/Queries/Get Solution Instances
clientMutationId No Only relevant if using the Relay GraphQL client

Here are some example mutations:

Delete Solution Instance
mutation {
  removeSolutionInstance(input: {solutionInstanceId: "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266"}) {
   clientMutationId
 }
}
Delete Solution Instance with clientMutationId
mutation {
  removeSolutionInstance(input: {solutionInstanceId: "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266", clientMutationId: "some-mutation-id"}) {
   clientMutationId
 }
}

It can return the following data:

Returned Data Notes
clientMutationId while this data is Only relevant if using the Relay GraphQL client, it is actually required here as currently this mutation does not return any other data
SecuritybearerAuth
Request
Responses
200

OK - Solution instance is deleted

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples
curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation ($solutionInstanceId: ID!){\n  removeSolutionInstance(input: {solutionInstanceId: $solutionInstanceId}) {\n   clientMutationId\n }\n}",
    "variables": {
      "solutionInstanceId": "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266"
    }
  }'
Response samples
application/json
{
  • "data": {
    • "removeSolutionInstance": {
      • "clientMutationId": null
      }
    }
}