Skip to main content

Instances

An instance of an integration is a copy of an integration that has been configured for a specific customer. When the instance is configured for a customer, config variables and connections to third-party apps and services specific to that customer are set. The combination of the instance and assigned config variables and connections is referred to as a deployed instance.

You can deploy instances of the integrations you create for your customers, or your customers can enable instances themselves through the integration marketplace.

Creating Instances#

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.

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.

Create instance in Prismatic app

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

Configuring Instances#

After creating a new instance or clicking into an existing instance, you will find yourself in the instance's Summary tab. Here, you will find information its deployed and enabled state. Clicking the Reconfigure button at the top right will take you to the Configuration Wizard.

This is where you can set values for configuration variables for your deployed instance. If your integration developers set default values for the config variables, those will be set initially, but you can override them if you choose. Depending on config variable type, you'll have the option to toggle boolean values, enter string values, enter JSON or XML for a code config variable, or select options from a dropdown.

Configure instance in Prismatic app

Be sure to click Save and deploy on the last page of the Configuration Wizard to save any changes you make.

For More Information: Configuration-Driven Integration Quickstart

Configuring Connections#

A connection is a special config variable that contains information on how to connect to a third party API. It might include an API key, username, password, or endpoint URL.

You can enter connection configuration information in the configuration screen like you would any other config variable. If the connection is an OAuth 2.0 connection, either a specially selected button or a button that says Connect will bring you to an external OAuth provider, so the integration in Prismatic can interact with the external API on behalf of your customer.

Dropbox OAuth 2.0 connection

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.

Set instance version in Prismatic app
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.

Deploying Instances#

A deployment of an instance is a combination of the instance and the config variables associated with the instance. After configuring your instance, click the Save and deploy button on the last page of the Configuration Wizard.

Once an instance is deployed, any triggers that are marked as deploy triggers are executed. Note: the instance will still deploy even if a deploy trigger fails to run to completion. We recommend adding an alert monitor to instances you deploy, so you can be alerted if an execution (a deploy flow included) fails to run to completion.

Why aren't instances deployed automatically when they are created?

Before instance can run, they need to be configured with instance-specific config variables. Once they are configured, they can be deployed.

Enabling and Disabling Instances#

If you would like to stop a deployed instance from executing, click the Pause Instance link at the right side of the green bar on the Summary tab to disable the instance. When disabled, your instance will not execute on a cron schedule (if configured to use scheduled triggers), nor respond to webhook invocations.

Pause instance in Prismatic app

To re-enable a disabled instance, click Unpause Instance.

Testing Instances#

You can invoke an instance outside of its cron schedule to ensure it functions properly. To run a test of an instance, open the Test tab. You can fill in a test payload body and custom HTTP headers to simulate a webhook trigger payload. Click the Save & Run Test button to invoke the test.

Alternatively, look up the ID of a flow in an instance with prism instances:flow-configs:list ${INSTANCE_ID} and then run prism instances:flow-configs:test ${FLOW_ID} from the command line.

Test instance in Prismatic app

Logs from the test can be found by clicking the Logs tab.

Invoking Instances#

Integrations' flows can be configured one of two ways: you can either set up your integration to run on a schedule, or you can invoke them through a webhook.

Invoking Instances with Webhook Triggers#

If you choose to invoke your instance's flows with a webhook trigger, webhook URLs will be generated for each flow you when you deploy the instance:

Invoke instance with webhook triggers in Prismatic app

To invoke an instance's flow programmatically, you can send a POST request to the webhook URL with an optional payload. Here's an example using curl, though you can use any language you like:

curl 'https://hooks.prismatic.io/trigger/EXAMPLE==' \  --location \  --header "Content-Type: application/json" \  --data '{"examplePayloadKey": "examplePayloadValue"}'

Webhook Trigger API Keys#

Instances can be configured to only run when an API key is passed in with the POST request. To do that, click Reconfigure and then click the pencil icon near the API Key field. You can specify your own API key, or choose to have one generated for you.

Configure webhook trigger API for instance in Prismatic app

If your instance has an API key, pass in an additional Api-Key header as part of your POST request:

curl 'https://hooks.prismatic.io/trigger/EXAMPLE==' \  --location \  --header "Content-Type: application/json" \  --header "Api-Key: 5cc74e1546382c52a8e93dce6795a5d4" \  --data '{"examplePayloadKey": "examplePayloadValue"}'

Viewing Instance Execution Results#

It's useful for debugging purposes to be able to see execution results of instance invocations. Click the Executions tab from an instances page to see the logs and step outputs of each execution of the instance.

Instance execution results in Prismatic app

If an instance failed to run to completion for whatever reason, you can review the data that was passed in to the instance when it was invoked, and that can help you to debug instances.

Results for all instances and all customers can be found by clicking the Explore > Executions link on the left-hand sidebar, and results for a specific customer can be found by clicking into a Customer, and then selecting their Executions tab.

Instance Execution Retry and Replay#

Integrations can be configured to automatically retry in the event that an instance fails to run to completion. Information about instance retries can be found on the execution results pages. There, you will see when the instance last ran, and when it will attempt to run again.

Instance execution details in Prismatic app

An

icon beside an execution indicates that the execution was an automatic retry of an instance execution that failed.

To manually retry (i.e. "Replay") an invocation of an instance, click the

icon beside any execution run. The instance will be run again with the same webhook payload that caused it to run initially.

Adding Alert Monitors to Instances#

Instance alert monitors allow you to notify your team when a variety of things occur, including failed instance executions, slow executions, instances in unexpected disabled states, etc. They can be found by clicking the Monitors tab from the instance's page.

For more information: Creating Alert Monitors.

Viewing Instance Logs#

Logs for an instance can be viewed by clicking the Logs tab from the instance's page.

You can search log message text through the Search Logs search bar on the top of the page, and you can filter logs by Log Severity or date range by clicking the Filter link to the right of the search bar.

Filter instance logs in Prismatic app

For More Information: Logging, Log Retention

Deleting Instances#

Deleting an instance removes the instance and any associated data. Before choosing to delete an instance, consider if you want to disable the instance from running instead.

If you choose to delete the instance, scroll to the bottom of the instance's Details tab. Click the Delete instance button, and type the name of the instance in the input field to confirm that you want to delete the instance. Click Remove instance.

Delete instance in Prismatic app

Searching Instances Across Customers#

Click the Explore > Instances link on the left-hand sidebar to view all instances for all customers. You can search instance names through the Search Instances search bar on the top of the page. You can further filter instances by description, integration or labels by clicking the Filter link to the right of the search bar.

Search instances across customers in Prismatic app

How do I filter instances by customer?

To view instances for a specific customer, click the Customers link on the left-hand sidebar and select a customer. Select the Instances tab to view instances for that customer.