Updating Config Variables Programmatically
If you're programmatically updating an instance, you're likely updating the instance's config variable values. There are two mutations that you can use to update instance config variables:
-
updateInstancelets you update multiple properties of an instance (like name, description, config variables, etc.). Note, though, that this mutation sets values for all config variables whether or not you specify a value for them. If you omit a config variable from the mutation, its value will be reset to its default value (ornullif no default is configured). Use this mutation with caution.Setting config variables withupdateInstanceWhen you programmatically set config variables using the updateInstance mutation, all config variables must be given a value. If you omit a config variable, that config variable will be set to its default value (even if it was previously set).
If you'd like to set just a subset of config variables while leaving the others alone, use the updateInstanceConfigVariables mutation, described below.
-
updateInstanceConfigVariableslets you safely update specific instance config variables, while leaving the other config variables untouched. Use this mutation if you would like to modify one (or a few) values.
Updating Config Variables with updateInstance
Before the updateInstance mutation, let's query the instance for its current config variables.
Each config variable is tied to a requiredConfigVariable which has a key (like Acme Inventory Endpoint) and a defaultValue.
Non-connection config variables also have a value property, which is the customer-specific value you'd like to set for that config variable (like https://app.acme.com/api).
If your config variable is a connection, which usually represents a username, password, API key, OAuth 2.0 connection, the shape is a bit different. It'll be comprised of a set of inputs that have a name, type, and value.
query ($instanceId: ID!) {
instance(id: $instanceId) {
name
configVariables {
nodes {
id
value
meta
requiredConfigVariable {
key
collectionType
dataType
defaultValue
}
inputs {
nodes {
name
type
value
}
}
}
}
}
}
{
"instanceId": "SW5zdGFuY2U6MWY0NmRmM2MtM2FjMi00ODMwLWExODEtZjNhN2FmN2RkNTRi"
}
If you run the query above, you'll get back something similar to the JSON below. Note that the different config variables each returned something slightly different, depending on the type of config variable they represent:
Acme Inventory Endpointis a plain string and returned avalueof""(empty string).Sync Inventory Item Metadata?is a boolean toggle and returned avalueof"false".Inventory Field Mappingis a key-value list, and returned avalueof"[]"(empty array).Acme Inventory User/Passis a connection with twoinputs-usernameandpasswordwhich have blank values of their own.
{
"data": {
"instance": {
"name": "Acme Inventory",
"configVariables": {
"nodes": [
{
"id": "EXAMPLE",
"requiredConfigVariable": {
"key": "Inventory Field Mapping",
"collectionType": "KEYVALUELIST",
"dataType": "STRING",
"defaultValue": "[]"
},
"value": "[]",
"inputs": {
"nodes": []
}
},
{
"id": "EXAMPLE2",
"requiredConfigVariable": {
"key": "Sync Inventory Item Metadata?",
"collectionType": null,
"dataType": "BOOLEAN",
"defaultValue": "false"
},
"value": "false",
"inputs": {
"nodes": []
}
},
{
"id": "EXAMPLE3",
"requiredConfigVariable": {
"key": "Acme Inventory User/Pass",
"collectionType": null,
"dataType": "CONNECTION",
"defaultValue": null
},
"value": null,
"inputs": {
"nodes": [
{
"name": "password",
"type": "VALUE",
"value": ""
},
{
"name": "username",
"type": "VALUE",
"value": ""
}
]
}
},
{
"id": "EXAMPLE4",
"requiredConfigVariable": {
"key": "Acme Inventory Endpoint",
"collectionType": null,
"dataType": "STRING",
"defaultValue": ""
},
"value": "",
"inputs": {
"nodes": []
}
}
]
}
}
}
}
Once we know the shape of the config variables (which ones are strings, which ones are key-value lists, and which ones are connections, etc), we can send back a config variable object that matches that shape. We use values to set connection config variables, and for connections and key-value lists we serialize the name-value or key-value pairs as JSON strings:
mutation ($instanceId: ID!, $configVariables: [InputInstanceConfigVariable]) {
updateInstance(input: {id: $instanceId, configVariables: $configVariables}) {
instance {
id
name
configVariables {
nodes {
requiredConfigVariable {
key
}
value
inputs {
nodes {
name
value
}
}
}
}
}
errors {
field
messages
}
}
}
{
"instanceId": "SW5zdGFuY2U6MWY0NmRmM2MtM2FjMi00ODMwLWExODEtZjNhN2FmN2RkNTRi",
"configVariables": [
{
"key": "Acme Inventory User/Pass",
"values": "[{\"name\":\"username\",\"type\":\"value\",\"value\":\"my.username\"},{\"name\":\"password\",\"type\":\"value\",\"value\":\"Pa$$W0Rd\"}]"
},
{
"key": "Acme Inventory Endpoint",
"value": "https://app.acme.com/api"
},
{
"key": "Sync Inventory Item Metadata?",
"value": "true"
},
{
"key": "Inventory Field Mapping",
"value": "[{\"key\":\"qty\",\"value\":\"Quantity\"},{\"key\":\"usd\",\"value\":\"Price\"}]"
}
]
}
Updating Config Variables with updateInstanceConfigVariables
This mutation lets you set values for a subset of config variables, while keeping the others untouched.
In this example, we set a string value for a config variable named My String, a list of values for a list config variable named My List, and a couple of values for a connection config variable named Amazon S3 Connection which has a couple of connection inputs:
mutation ($instanceId: ID!, $configVariables: [InputInstanceConfigVariable]) {
updateInstanceConfigVariables(
input: {id: $instanceId, configVariables: $configVariables}
) {
instance {
id
}
errors {
field
messages
}
}
}
{
"instanceId": "SW5zdGFuY2U6MWY0NmRmM2MtM2FjMi00ODMwLWExODEtZjNhN2FmN2RkNTRi",
"configVariables": [
{
"key": "My String",
"value": "My Value"
},
{
"key": "My List",
"value": "[\"Value 1\",\"Value 2\"]"
},
{
"key": "Amazon S3 Connection",
"values": "[{\"name\":\"accessKeyId\",\"type\":\"value\",\"value\":\"MyAccessKey\"},{\"name\":\"secretAccessKey\",\"type\":\"value\",\"value\":\"MySecretAccessKey\"}]"
}
]
}
Importing an OAuth 2.0 Connection
If you are migrating to Prismatic from your own service or another integration platform, you may want to import your customers' OAuth 2.0 access and refresh tokens so that they do not need to re-authenticate.
To do that, you'll need to first deploy an instance of an integration.
Then, get an instance's config variables.
Identify the id of the config variable that represents an OAuth 2.0 connection.
Using that config variable id, along with the accessToken and refreshToken from the system you're migrating from you can import the OAuth 2.0 connection:
mutation (
$configVarId: ID!,
$accessToken: String!,
$refreshToken: String!,
$refreshAt: DateTime!,
$expiresIn: Int!
$additionalTokenFields: String
) {
updateOAuth2Connection(
input: {
id: $configVarId,
status: "active",
accessToken: $accessToken,
refreshToken: $refreshToken,
tokenType: "bearer",
refreshAt: $refreshAt,
expiresIn: $expiresIn,
additionalTokenFields: $additionalTokenFields
}
) {
instanceConfigVariable {
refreshAt
status
meta
}
errors {
field
messages
}
}
}
{
"configVarId": "SW5zdGFuY2VDb25maWdWYXJpYWJsZTpmMWI4ZGQzNi0yMzg0LTQ5MWUtOTE3ZC1iNTU1YjJiNzI2MmQ=",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiLwn5GNIFByaXNtYXRpYyIsIm5hbWUiOiLwn5GOIFRyYXkuaW8iLCJpYXQiOjE1MTYyMzkwMjJ9.xYUuI8BHov7C-E-ENa2Ox6z_L6StR1UjTuOqCaCnGTk",
"refreshToken": "super-secret-refresh-token",
"refreshAt": "2000-01-01T00:00:00.000Z",
"expiresIn": 60,
"additionalTokenFields": "{\"url\":\"https://example.com\",\"tenantId\":\"12345\"}"
}
Note: you can set refreshAt to the UTC datetime when the token should next be refreshed, or you can set it to a date in the past (like the example above) to force an immediate refresh of the token.
User-level OAuth 2.0 connections can be imported similarly using the updateUserLevelOAuth2Connection.
Note that your config variable ID will start with VXN... instead.
Deploying an Instance Through the API
An instance needs to be deployed in order for your new configuration to take effect. To deploy an instance, use the deployInstance mutation:
mutation ($instanceId: ID!) {
deployInstance(input: {id: $instanceId}) {
instance {
name
enabled
deployedVersion
lastDeployedAt
}
errors {
field
messages
}
}
}
{
"instanceId": "SW5zdGFuY2U6ODgyOTQwM2MtOGZkYS00ZGMwLTg3OGYtYWI5MWNhMmVmMTVj"
}