Integrations

Overview

An integration is comprised of component action steps that execute one after another in series. Multiple steps of an integration can come from the same component action. For example, two steps could be HTTP GET actions that fetch data from two different endpoints.

Integrations are triggered either on a schedule, or via a webhook invocation.

Integrations are created by your organization. You can publish versions of your integrations, and then deploy instances of those integrations to one or more of your customers.

We recommend that you follow our Getting Started tutorial to first acquaint yourself with integration development.

Creating an Integration

To create a new integration in the web app, click Integrations from the left-side menu, and then click the + Integration button in the upper-right. Give your new integration an appropriate name and description.

Listing and Searching Integrations

To view all of the integrations your organization has created, click the Integrations link on the left-hand sidebar.

You can search for specific integrations by name by typing a part of the name in the upper search bar, or you can search by description by clicking the Filter button to the right of the search bar.

The Integration Designer

After creating a new integration or selecting one from your list of integrations, you will find yourself in the integration designer. Here, you can build, test, and publish integrations.

The integration designer contains four important features:

  1. The integration's trigger is in the upper-left. Integrations need to know when to run. Sometimes you will want them to run on a schedule, like once a day on weekdays or on the hour every hour. Other times you will want to invoke the integration via a webhook. By clicking on the trigger card at the top left, you will be prompted to configure how you want to trigger your integration.
  2. A list of steps are found below the trigger. Steps take input, like an endpoint to poll or S3 bucket to utilize. They execute, and then generate output for subsequent steps to reference. Steps are run in the order that they appear in the designer.
  3. The step config pane allows you to configure inputs and outputs of steps, as well as alter the step name to a name of your choosing.
  4. The testing pane provides a sandbox for testing your integration. Here, you can configure test variables and credentials, and view output of your integration as you test it.
Create your first few integrations using the integration designer

We recommend that you create your first few integrations through the integration designer. Then, when you feel comfortable with creating integrations, adding action as steps, creating config variables and credentials, etc., you can move to programmatically creating integrations through the prism CLI tool, or through our API.

Required Configuration Variables in Integrations

If you want to configure required config variables for your integration, click the Required Config Variables tab from the integration designer. Here, you can declare names and optional default values of configuration variables that are required for your integration.

Once config variables are enumerated in this list, they are accessible to actions within your integration. If you have config vars defined at the customer or organization level with the same name, you can import those variables' values when you create instances of this integration.

For More Information: Required Configuration Variables in Integrations

Integration Triggers

Integration triggers allow you to define when an instance of an integration should run. There are two types of triggers: schedule triggers and webhook triggers. If you would like your integration to run on a predefined regular basis, you should use a schedule trigger. If you would like to invoke your integration from another system, you should use a webhook trigger.

Schedule Triggers

Scheduled triggers follow cron job notation to determine how often to execute. For example, a trigger of */5 8-16 * * 1-5 would cause your integration to run every five minutes during business hours (8:00-16:55), Monday through Friday. * * * * * would cause your integration to run every minute, always.

You can configure a cron schedule by clicking the trigger on the top of the integration designer, and entering your cron schedule in the step config pane.

For More Information: Cron Calculator

Webhook Triggers

When an integration is published and an instance of the integration is created, a webhook URL is associated with that instance. Executing HTTP POST requests on that webhook URL results in the instance being triggered to run.

The webhook URL is printed on the instance's page in the web app, or can be viewed by running

prism instances:list --extended --output json

JSON-formatted arguments can be passed through HTTP headers to the webhook URL, and used as inputs for the actions of the integration like this

curl -d '{"renderId":51266,"s3Bucket":"test-customer-renders","status":"complete"}' \
--header "Content-Type: application/json" \
--request POST \
'https://hooks.prismatic.io/trigger/EXAMPLE1FjMmUtOWNiZS00MmI3LTllYzEtMDQzYjY5ZDkxNThj'

Note that the payload of the POST request is available as output of the integration's trigger, shown on the left. Steps can then reference outputs.trigger.all.body.ARGUMENT_KEY as their inputs.

Posting Binary Data with Webhook Triggers

If you have binary data (like an image or PDF) that you would like to post as part of your webhook invocation, you can pass that binary data in as part of your request. For example, if you have an image, my-image.png, you could invoke a test of an integration with:

curl --request POST \
--header 'Content-Type: image/png' \
--data-binary '@/path/to/my-image.png' \
'https://hooks.prismatic.io/trigger/EXAMPLEuY2U6MmE2ODg4NTEtM2EwZS00NjAzLTljMDAtY2FmMGNlNDc3ZDBj'

The binary file can be accessed by subsequent steps by referencing outputs.trigger.all.body.

Integration Steps

Actions, like downloading a file from an SFTP server or posting a message to Slack, are added as steps of an integration. Steps are executed in order, and outputs from one step can be used as inputs for a subsequent step.

The left portion of the integration designer lists a trigger, followed by the steps that constitute your integration.

Steps are executed in order. If one step fails, the integration test or instance stops, and if configured to do so, an alert monitor is triggered to alert your team members of the instance's failure.

Adding Actions as Steps of Integrations

To add a step to an integration, click the icon underneath the trigger or another action.

Select the action you would like to add to your integration. You can begin to type the name of the action you would like to add to filter the list of actions available.

Step Inputs and Outputs

Once you have added an action step to your integration, you will likely need to configure some inputs for that step. Some inputs are required, and denoted with a * symbol, while others are optional. Inputs can be plain strings, configuration variables, outputs from previous steps, or a combination of those things strung together.

You can enter your input in simple mode, where variables are referenced by tapping = and then optionally autofilling a variable name like configVars.VARIABLE_NAME or outputs.STEP_NAME.OUTPUT_NAME, or using JSONata notation.

Step outputs can be similarly configured to create reusable output variables.

For More Information: Component Action Inputs, Component Action Outputs

Changing Step Names

By default steps are uniquely named after the action they invoke (so, they're named things like httpget, httpget_1, deleteobject, etc.). To override that default name, click the Details tab in the step config pane.

Like using descriptive variable names in a program, renaming steps allows you to give your steps descriptive names. For example, rather than a step being called deleteobject you can name it delete_3d_render_from_s3. We recommend giving your steps descriptive names so your team members can read through integrations and understand their purpose more readily.

Note that once you change a step's name, you need to update any reference to that step's output outputs.STEP_NAME.

Reordering Steps

Steps are executed in serial. To reorder steps, click and drag a step up or down.

Testing Integrations

The integration designer provides a sandbox for testing integrations from the bottom-right Testing pane. There, you can invoke an integration, configure test credentials and config vars, and view test logs in real time.

You can test your integration after you configure required config variables and credentials by clicking the RUN TEST button.

Test Config Variables

If your integration requires configuration variables, you can specify testing values for those variables under the Config variables tab of the Testing pane. If you specified default values for your required config variables, you will have the option to copy those values in here.

Test Credentials

If your integration requires credentials, you can use organization-level credentials to test your integration. We recommend that you create testing, non-production credentials for integration sandbox tests. Click the Credentials tab in the Testing pane, and choose the appropriate credentials to use for each of your steps.

Test Run Outputs

After running an integration test, each step in the left-hand side of the integration designer will display the output of that step. This is helpful for debugging and verifying the flow of data within your integration.

Test Run Logs

Output for your test run is displayed under the Runner tab in the Testing pane. If any of your steps log output or throw errors, you will see those logs and errors in this window.

Integration Attachments

Your team can save and share integration-related documents alongside an integration by clicking on the Attachments tab from the integration designer page.

Publishing Integrations

By publishing an integration, you mark it ready for deployment to customers.

Click the Publish button on the top-right corner of your integration designer screen. You will be prompted to enter optional comments about this version of your integration:

Take note of the version of your integration that is created.

Versioning Integrations

Each publication of your integration is saved as a distinct version. Published integrations are versioned for several reasons:

  1. You can test changes to integrations with small audiences, without forcing changes on all customers at once.
  2. Customers may require different versions of an integration. For example, one integration version may be compatible with "version 3.0" of your software, while another integration version may be compatible with "version 4.0". You will want to deploy Prismatic integrations that are compatible with your software implementations.
  3. A third-party vendor might change their API, forcing you to change your integration. Some of your customers might have an old version of the third-party vendor's software, and some customers might have the new version.
  4. Mistakes happen. Reverting to a previous version should be straight-forward, and it is with versioning.

Versions of your integration can be found under the Version History tab of the integration designer.

Forking Integrations

Sometimes you will want to make a copy of an integration and modify the copy. This is called forking an integration.

From the integration designer, open the Settings tab and then click FORK INTEGRATION. Give your forked integration a new name and description and then click ADD.

View Deployed Instances

To view all instances of an integration that have been deployed, click the Instances tab from the integration's integration designer screen. This screen will display instance version, and information about when the instance was last run and its enabled status.

Deleting Integrations

Deleting an integration will delete all instances of that integration

Use caution when deleting an integration. Deletion of an integration also deletes all deployed instances of that integration.

From the integration designer page, click the Settings tab. Click the Delete Integration button on the bottom of the page and confirm by clicking REMOVE INTEGRATION.

Last updated on