Open Navigation

Create Solution Instance

Note: The Tray GraphQL API is a backend API only and calls must be invoked server-side. Client-side Javascript calls to the API should not be made as they will be blocked by CORS. Our demo app (built using https://www.apollographql.com/) is a good illustration of how you can create a UI which presents an End User with their available Solutions while making all API calls server-side.


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 an id
  2. Generate a one-time 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 Dealing with the Config Wizard
  5. Once the Solution Instance is configured for the End User, use Update Solution Instance to set the status to 'enabled'
Required tokenNotes
UserObtained after creating a user and authorizing a user
The User Token is a persistent token that should be securely stored in your application for future use

The mutation accepts the following arguments:

ArgumentRequiredNote
solutionIdYesObtained with List Solutions
instanceNameYes
authValuesNoCan be used to import End User authentications. See Importing Auths
configValuesNoCan be used to import external data. See Importing External Data

Basic Mutation

The following is a query which could be used in the GraphQL playground:

mutation {
createSolutionInstance(input: {
solutionId: "2d38b2ec-xxxx-xxx-xxxx-b4ec68084266",
instanceName: "slack channel email 1"
}) {
solutionInstance {
id
name
enabled
}
}
}

The response returns:

{
"data": {
"createSolutionInstance": {
"solutionInstance": {
"id": "18da9092-xxx-xxx-xxx-6e28f1ec7766",
"name": "slack channel email 1",
"enabled": false
}
}
}
}

The following shows an example of a javascript function (taken from server/api.js in our demo app) which carries out the dual task of creating an authorizationCode for a user and begins the process of creating a solution instance from a selected solution (both these steps are required when enabling an end user to choose a solution to begin configuring for their own use):

// POST Solution Instances
app.post('/api/solutionInstances', (req, res) => {
mutations.createSolutionInstance(
req.session.token,
req.body.id,
req.body.name,
)
.then(solutionInstance => {
return mutations.getGrantTokenForUser(
req.session.user.trayId,
).then(({payload}) => {
const solutionInstanceId = solutionInstance.data.createSolutionInstance.solutionInstance.id;
const authorizationCode = payload.data.generateAuthorizationCode.authorizationCode;
res.status(200).send({
data: {
popupUrl: `https://embedded.tray.io/external/solutions/${partnerId}/configure/${solutionInstanceId}?code=${authorizationCode}`
}
});
})
})
.catch(err => {
res.status(500).send(err)
});
});

This references two mutations (found in server/graphql.js in our demo app) such as:

createSolutionInstance: (userToken, solutionId, name) => {
console.log(userToken, solutionId, name);
const mutation = gql`
mutation {
createSolutionInstance(input: {solutionId: "${solutionId}", instanceName: "${name}", authValues: [], configValues: []}) {
solutionInstance {
id
}
}
}
`;
return generateClient(userToken).mutate({mutation});
},

and:

getGrantTokenForUser: (trayId, workflowId) => {
const mutation = gql`
mutation {
generateAuthorizationCode(input: {userId: "${trayId}"}) {
authorizationCode
}
}
`;
return masterClient.mutate({mutation})
.then(payload => {
return {
payload,
workflowId,
};
});
},

Advanced mutation returning Authentication ID

If you need to store the authentication id for a user it is possible to include this in the fields to be returned, as shown in the following mutation:

mutation {
createSolutionInstance(input: {
solutionId: "2bexxxx-xxx-xxx-xxxxxf3491",
instanceName: "some instance name",
configValues: [{ externalId: "external_test-email" , value: ""me@example.com"" }]
}) {
solutionInstance {
id
name
enabled
created
authValues {
externalId
authId
}
}
}
}

Advanced mutation returning webhook URL

Running a mutation such as the following in the GraphQL playground will show that it is possible to expose the webhook url of the underlying workflows upon which the Solution Instance is based:

mutation {
createSolutionInstance(input: {
solutionId: "2bexxx-xxxx-xxxx-xxxx-xxxxxxf3491",
instanceName: "some instance name",
authValues: [{ externalId: "external_sqs_authentication", authId: "aaa67786-xxx-xxx-xxx-97dedd1519b3" }],
configValues: [{ externalId: "external_user-email" , value: ""me@example.com"" }]
}) {
solutionInstance {
id
name
enabled
created
workflows {
edges {
node {
id
triggerUrl
sourceWorkflowId
}
}
}
}
}
}

This will produce a result such as:

{
"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": {
"edges": [
{
"node": {
"id": "98099de2-xxx-xxx-xxx-xxxxxb8ff7",
"triggerUrl": "https://6a4xxx-xxx-xxx-xxx-xxx-xxxe8eaa2.trayapp.io",
"sourceWorkflowId": "378xxx-xxx-xxx-xxx-xxx-xxx4fd6"
}
}
]
}
}
}
}
}
Was this article helpful?
Yes
No