Skip to main content

Instances

Overview#

An instance of an integration is a copy of an integration that has been configured for a customer. When the instance is created for a customer, config variables and credentials specific to that customer can be set. The combination of the instance and assigned config variables and credentials is referred to as a deployed instance.

How to Configure and Deploy an Instance

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 + 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.

Once the instance is created, you will be prompted to configure any config variables and credentials 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 Configuration tab. Here, you will find information about the instance's webhook URL (if it uses a webhook trigger), its deployed and enabled state, and configuration information associated with the instance.

On the bottom of the page you will see the Integration Configuration section. This is where you can set values for configuration variables and credentials 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. To edit config variable values, click the Reconfigure button on the top right of the page. 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, select options from a dropdown.

If your integration requires credentials, you can bind existing customer or organization credentials, or create new credentials by clicking the + Credential button.

Be sure to click SAVE AND DEPLOY on the upper part of the instance's page to save any changes you make.

For More Information: Configuration-Driven Integration Quickstart

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 on the top right of the page, and then select the latest version from the Integration Configuration section.

You can pin instances to different integration versions

Not all instances of an integration 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 and credentials associated with the instance. After configuring your instance, click the SAVE AND DEPLOY button in the upper-right of the instance Configuration tab.

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

Before instance can run, they need to be configured with instance-specific config variables and credentials. 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 button in the upper-right of the instance Configuration 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.

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 to simulate a webhook trigger payload. Click the RUN TEST button to invoke the test.

Alternatively, run prism instances:test ${INSTANCE_ID} from the command line.

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

Invoking Instances#

Integrations 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 with a webhook trigger, a webhook URL will be generated for you when you deploy the instance.

To invoke the instance 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 -L --data '{"examplePayloadKey": "examplePayloadValue"}' \  --header "Content-Type: application/json" \  'https://hooks.prismatic.io/trigger/SW5zdGFuY2U6ZDYzZTdlNmYtNzRkZS00MTI0LWE4M2QtNjM3ZGFkOTRkZTFh'

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.

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

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

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's page to see the logs and step outputs of each execution of the instance.

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 into the 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.

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.

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 Configuration 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.

Searching Instances Across Customers#

Click the 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 or integration by clicking the Filter link to the right of the search bar.

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.