Solution Instances

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.

The query accepts the following filter criteria:

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

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
            }
        }
    }
}

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'

The mutation accepts the following arguments:

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:

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

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 Upgrade Solution Instance. This is explained in detail in Updating/Upgrading Solution Instances.

The mutation accepts the following arguments:

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
    }
  }
}

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.

The mutation accepts the following arguments:

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
    }
  }
}

Used to delete a Solution Instance.

The mutation accepts the following as inputs:

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: