Org-Deployed Instances

Generally, it's best to give your customers the ability to deploy instances themselves through the integration marketplace. However, there are situations where you may want to deploy an instance for a customer yourself:

• You may have a one-off integration that is specific to a single customer, and you don't want to add it to the marketplace.
• You may want a more white-glove deployment of your first few instances to ensure deployment goes smoothly.
• You may have an integration that your team uses internally that you don't want to expose to customers.

Creating a new instance

When you are satisfied with an integration and have published a version of it, you can create an instance of that integration for a customer.

Web App

Start by clicking the Customers link on the left-hand sidebar, and then select a customer. From the customer's page open the Instances tab. There, you will see any instances currently deployed to your customer, with information about when the instances were last run, what versions are deployed, etc.

To create a new instance, click the + Add Instance button on the top-right corner. Select the integration you wish to create an instance for, and give the instance an appropriate name and description. Labels from the integration are automatically recommended for an instance, but you can remove or add additional labels - labels help to keep your instances organized.

Once the instance is created, you will be prompted to configure any config variables required by the integration.

CLI

To create an instance for a customer, use the prism instances:create subcommand.

# Get the Customer ID
CUSTOMER_ID=$(
    prism customers:list \
        --columns id \
        --filter 'Name=^FTL Rockets$' \
        --no-header)

# Find the ID of the integration you want to deploy
INTEGRATION_ID=$(prism integrations:list --columns id --no-header --filter 'name=Acme Inc')

# Find the version ID of the latest available published version
VERSION_ID=$(prism integrations:versions ${INTEGRATION_ID} --latest-available --columns id --no-header)

# Connection config variables must be escaped
CREDENTIALS='[{\"name\":\"username\",\"type\":\"value\",\"value\":\"my.username\"},{\"name\":\"password\",\"type\":\"value\",\"value\":\"Pa$$W0Rd\"}]'

# Create an instance given a specific $VERSION_ID,
# a customer $CUSTOMER_ID and required config variables
# ("My Endpoint", "Do Thing?" and "Acme Basic Auth"):
prism instances:create \
    --name 'Acme Inc' \
    --description 'Acme Inc instance for Smith Rocket Co' \
    --integration ${VERSION_ID} \
    --customer ${CUSTOMER_ID} \
    --config-vars "[
        {
            \"key\": \"My Endpoint\",
            \"value\": \"https://example.com/api\"
        },
        {
            \"key\": \"Do Thing?\",
            \"value\": \"true\"
        },
        {
            \"key\": \"Acme Basic Auth\",
            \"values\": \"${CREDENTIALS}\"
        }
    ]" \
    --label 'Production' \
    --label 'Paid'

API

Use the createInstance mutation to deploy an instance to a customer:

mutation {
  createInstance(
    input: {
      name: "My Instance"
      description: "Deployment of my integration"
      integration: "SW50ZWdyYXRpb246ZDgwZjkyYmEtNTEyZS00N2IxLWEzMzgtZTAxOGE1OGNkMDRi"
      customer: "Q3VzdG9tZXI6MmM4YmUxZDgtOTU5Ny00MTI3LWI5MTUtYjBmMjc3Y2YyNWYw"
    }
  ) {
    instance {
      id
    }
  }
}

Creating an unconfigured instance

The embedded marketplace shows only integrations that have been explicitly added to marketplace. But, there are situations where you may want to provide a particular integration that is not part of marketplace to a customer. To do that, you will need to create an unconfigured instance for a customer and elect to show all instances to your customer. Your customer will be able to log in to marketplace and configure that instance for themselves.

To create an unconfigured instance, select the Skip configuration button when creating your instance.

An unconfigured instance will not be deployed until your customer enters their configuration information, and will not count towards your monthly instance count.

Setting integration version for an instance

When an integration is published, a new version of the integration is created. Instances of the integration can then be updated to use the new integration version. In the instance's configuration page, you'll see New Version Available if your instance can be updated.

To update your instance, click the Reconfigure button at the top right of the page, and then select the latest version from the Integration Version field.

You can pin instances to different integration versions

Not all instances need to run the same version of the integration. For example, one customer might be running a legacy version of a third-party app. They can continue to run "version X" of an integration until they upgrade their third-party app, at which point their instance can be upgraded to "version Y".

If an instance upgrade causes problems - suppose a new definition of an integration has a bug that an older one didn't have - you can always reconfigure the instance to run an older version of the integration by similarly clicking Reconfigure and choosing an older known working integration version.