We're proud to introduce a new instance configuration option - User-Level Configuration (ULC).
What is ULC? ULC helps when multiple users of a single customer all need an integration. It allows you to configure a single instance of an integration for a customer, but collect configuration from multiple users and execute using user-specific configuration.
Why use ULC? ULC is handy if your integration requires user-specific config variables and credentials. For example, suppose your app needs to write data to several users' private Dropbox folders. With ULC, you can collect connection information for several users within a customer, and integrate with each of their individual Dropbox accounts.
How does ULC work? At a high level, a single instance of an integration is deployed to a customer, and is configured with some customer-wide config variables. Individual users within the customer, then, go through a ULC config wizard and supply user-specific credentials and config variables. When the instance runs, it pulls in user-specific configuration depending on some rules you set.
Read more about ULC in our docs.
You can now persist data between instances of the same integration. This is handy if your customers need to share some state, or if you need to persist a customer mapping for preprocess flows.
Source code for the
@prismatic-io/prism CLI tool and the embedded marketplace library,
@prismatic-io/marketplace, have been added to public repositories on GitHub.
prism wraps the Prismatic API and provides users a way to perform CRUD (create, read, update, delete) operations on a variety of Prismatic resources (components, integrations, instances, customers, etc.) from the command line.
Having it publicly available provides a great reference for developers looking to wrap the Prismatic API themselves.
The two projects join the custom component SDK,
@prismatic-io/spectral, which was already publicly available:
Our list of built-in components continues to grow. A full catalog is available here. This past month, we added:
We've overhauled the way deploy-time configuration management works, making it much more flexible and dynamic.
It's a wizard now, so you can split complex configuration pages in a way that's intuitive to your customers. Any existing configuration pages will simply become part of a one page wizard, so everything will continue to work as-is.
Read more about the configuration wizard designer on the Building Integrations docs page.
You've probably noticed that the Prismatic UI has gotten a facelift! Based on everything we've learned over the last couple of years, we've improved the UI to feel better and be more intuitive.
You can now access additional information about the currently running execution from your custom component including:
- The name and ID of the running instance
- The name, ID and external ID of the customer the instance is deployed to
- Webhook URLs for all flows of the running instance
This is handy if you need to know information about the current run context, or if you're building actions that configure or delete webhooks in a third-party app.
To access new
context properties, update your custom component's
Read more about the expanded context parameter.
Our list of built-in components continues to grow! A full catalog is available here. This past month, we added:
- DigitalOcean - Manage your Droplets, Kubernetes clusters, and other DigitalOcean services.
- GitHub - Manage users, repositories, licenses, and more on GitHub
- Hash - Compute hashes of strings using common hash functions
- Phrase - Phrase is a translation management platform for software projects
- Pipedrive - Manage leads, companies, activities, and more on the Pipedrive platform
- Rippling - Rippling makes it easy to manage your company's Payroll, Benefits, HR, and IT—all in one, modern platform
You now have more control over the UI elements that appear to your customers in your embedded marketplace. If you would like to hide the Back to Marketplace link, or the Test, Executions, Logs, or Monitors tabs on an instance configuration screen you can!
@prismatic-io/marketplace version to
3.1.0, and add a
screenConfiguration code block to your marketplace.
We have five new components this month (including a component to Prismatic itself - how meta!).
- IMAP - Fetch and manage email via IMAP
- Intercom - Manage companies, contacts and tags on the Intercom platform
- Microsoft Sharepoint - Interact with sites, drives, and items within Microsoft Sharepoint
- Pretty Good Privacy (PGP) - Create and translate encrypted messages
- Prismatic - Interact with the Prismatic API to manage customers, integrations, instances, etc.
A full catalog is available here.
We've made several improvements to the custom component development experience. To highlight a few:
- You can now
cleanyour reusable inputs, which helps ensure type safety and catches problems with inputs before they reach the
- You can now add a global error handler to your component, which helps you capture and display more informative errors if they're thrown.
- The improved testing harness gives you more flexibility when unit testing your actions and triggers.
prismCLI tool can now fetch existing integration connections (including OAuth 2.0 access tokens) and store them in environment variables, so you can use them for unit testing.
Update to the latest
@prismatic-io/spectral 6.x version to take advantage of these new features!
Sometimes a step in an integration throws an error. This can be caused by a variety of external factors - temporary network connectivity issues, brief third-party API outages, etc.
You can now configure how the integration runner handles errors on each step. You can choose to stop the instance execution (that's the current default behavior), you can ignore the error and continue the run, or you can choose to wait and retry the step at a later time.
Read more in our docs.
This new trigger is handy for cleaning up configuration created by the integration. For example, you can remove webhook configuration in third-party apps, or update our own API so your team knows that a customer removed an integration.
You can now set values for configuration variables from your app within your embedded marketplace. This is helpful if you know some information about your customer (their API key, a special endpoint they use, data mapping configuration, etc), and would like to set a config variable value so they don't need to.
Read more about Dynamically Setting Config Variables in Marketplace in our docs.
We added some new components to our catalog in April. This past month, we added:
Some popular SaaS applications append URL paths to the webhooks that they're configured to use.
So, given a webhook endpoint
https://hooks.prismatic.io/trigger/EXAMPLE== they might send data to
You can now send data to webhook triggers four ways:
- Request body
- Request headers
- URL parameters
- URL path (added)
Check out our Integration Triggers article for more information.
Instance-specific endpoints (meaning all flows in an instance share one webhook URL) and shared endpoints (meaning all instances of an integration share one webhook URL) are now easier to configure, test and troubleshoot. Check out our Endpoint Configuration article for details and our Using Shared Webhooks and Preprocess Flows for an example of how to use shared endpoints.
Instance webhook triggers can now be invoked using the GET HTTP verb in addition to the POST verb.
Some third-party apps (notably Dropbox among others) verify that a webhook endpoint is ready to receive requests with a GET request. They then send webhook payloads with POST requests. This change was made to support the initial verification GET requests.
You can now filter the integrations that you show in your embedded marketplace by category or label. This gives you the flexibility to show specific types of integrations to specific users or customers.
To get started with filtering your embedded marketplace, update your @prismatic-io/marketplace package to version 1.1.2, and add a
filters attribute to your
prismatic.showMarketplace() invocation - see docs for details.
You can now create custom themes for your embedded marketplace for both dark and light mode users of your application. Check out our embedded marketplace docs for information on how to theme your embedded marketplace to match your app's dark and light mode look-and-feel.
It's now easier to integrate with SOAP-based APIs. For quick one-off calls, you can use our built-in SOAP component to fetch WSDL definitions and make requests to an API's SOAP methods. For more complex SOAP APIs, you can leverage our custom component SDK's SOAP client utility functions to wrap SOAP methods into a series of component actions.
We've revamped the way that components connect to third-party apps and services. The new concept is called connections, and they make authentication simpler, more flexible, and easier to support.
We'll be updating our built-in components to use connections in the coming weeks, and credentials will eventually be phased out in favor of connections (but don't worry - credentials won't be sunset immediately!).
For a full run-down how connections improve integration development and support and customer self-deployment, check out our blog announcement. Here's a quick summary:
- Component developers have more flexibility when declaring what information their components need to connect to a third party. They can define custom connections that include any number of fields, like username, password, API key, tenant ID, endpoint URL or other fields that are unique to the service they're integrating with.
- The OAuth 2.0 flow got much simpler and cleaner for both integration builders and customers who deploy the integration - customers just see a single button to click when they need to authenticate with OAuth.
- Authorization got simpler in general - connections live within the integration designer or a deployed instance. You don't need to create credentials from the organization or customer settings pages, nor juggle credential types. Components know what connections they're compatible with, and can only be paired with those connection config variables.
- Connections are easier to support. You can now configure alert monitors to notify you when connections (OAuth or otherwise) expire or fail to authenticate in an integration.
We created new components for three popular SaaS apps this month:
- BambooHR - Keep track of employees' HR needs
- Xero - Create and manage invoices, items, accounts, payments and more objects within a Xero account
- Zoom - Manage Zoom users, meetings and webinars
A full catalog of all of our components is available here.
The loop component has been improved to facilitate easily looping over a paginated API. Many third-party APIs limit the number of records you can fetch at once, and let you load a batch (page) of records at a time. You can now more easily loop over paged records that you fetch from an external API, and you can break out of a loop whenever you've paged over all available records.
Check out our quickstart for a tutorial on how to loop over pages of records in an integration.
We have a bunch of new built-in components this month. A full catalog is available here. This past month, we added:
- Asana - Manage users, projects, and teams in your Asana workspace
- Monday - Manage boards, items, and columns inside your Monday account
- Microsoft Project - Make queries to reporting data from a Project Web App instance
- New Relic - Easily manage metrics, logs, and events
- Tableau - Manage projects and workbooks in your Tableau site
- Zendesk - Manage Tickets and users in Zendesk
Customers on enterprise plans can now stream logs and metrics to external logging services (like DataDog or New Relic). This is useful, since you likely already use a logging service to collect logs from your various applications. Now, your integration logs can live alongside the rest of your applications' logs.
Read more on our logging article.
You can now reference multiple config variables, step results, and static strings for step input using templated inputs. This lets you concatenate config variables, text, and step results together, without needing an additional step to do the concatenation. It's helpful for dynamically generating URLs, queries, messages, and more.
Update: As of 2022-05-25, "Expression inputs" have been renamed "Template inputs"
Our list of built-in components continues to grow. A full catalog is available here. This past month, we added:
- AWS Glue - Perform data transformation through AWS Glue
- AWS Lambda - Manage and invoke AWS Lambdas
- Firebase - Create, read, update, and delete documents in a Firebase Cloud Firestore database collection
- Google Calendar - Manage calendars and events in Google Calendar
- Hubspot - Manage objects and associations in the Hubspot CRM platform
- Jira - Manage Jira issues, comments, projects and users
- Mailchimp - Interact with email campaign lists and e-commerce resources
- Microsoft Excel - Parse and build xlsx files (spreadsheets)
- Microsoft Teams - Manage the teams, groups, channels, and messages associated with your Microsoft Teams account
- Redis - Manage items in a Redis database
The vast majority of integrations are triggered in one of two ways: they either run on a schedule (i.e "At 15 minutes past each hour") or they're invoked by an HTTP request to a webhook.
Not all apps and services that you integrate with are the same, though, and some require additional functionality or validation. For example, Salesforce outbound messages (webhooks) require a special XML-formatted acknowledgement (ACK) response to a webhook request, and Amazon's Simple Notification Service (SNS) requires that integrations send an HTTP POST request to AWS to confirm an SNS subscription.
With those considerations in mind, we've extended our custom component SDK to allow you to write your own triggers for your components. Your triggers can handle things like:
- Replying to webhook requests with custom responses
- Validating webhook headers and payload data
- Transforming and processing XML, CSV, or proprietary data formats so the rest of your integration can easily reference data that comes in
If you've written your own actions, writing a trigger will feel very familiar. Check out our docs on writing triggers to get started, or take a look at our quickstart that details how we wrote the Salesforce trigger.
The general webhook trigger is now more configurable. You can now specify the HTTP code, headers, response type, and response body that the webhook trigger returns to a webhook caller. This helps you handle APIs that require custom responses, and allows you to redirect webhook callers as needed.
We've significantly enhanced Prismatic's embedded marketplace experience, enabling you to provide your customers a seamless, native integration experience with minimal engineering effort.
You can now embed Prismatic's integration marketplace into your application with just a few lines of code. You can choose to display the sleek marketplace UX directly within your application or as a popover, and apply custom theming to make your integration marketplace look native to your application.
The embedded marketplace showcases your integration offerings and allows customers to self-activate and configure the integrations they need. Just as previously, you can specify which integrations appear in your marketplace, which ones can be self-activated, and define each integration's configuration screen.
Your customers do not need to juggle another set of credentials to access your embedded marketplace. Instead, you can sign JSON web tokens (JWTs) for your users, which can be used to automatically authenticate them for the marketplace.
Check out our docs to get started.
You now have more control over how webhook endpoints are configured for deployed instances. You already had the option to create a webhook endpoint for each flow of each deployed instance (Instance and Flow-Specific). You can now select two other configuration options:
- Instance-Specific: Create a single webhook endpoint for each instance. Identify which of the instances' flows should run based on data in the webhook request.
- Shared: Create a single webhook that is shared by all customers who have a particular integration. Route the webhook request to a flow in a specific customer's instance based on data in the webhook request.
Both of these additional configuration options allows you to route webhook requests to a particular customer and flow based on the data that comes in to the webhook. If the data that comes in needs additional processing, or if you need to look up a flow's name or customer's ID, you can assign one of your integration's flows to be a Preprocess Flow - a flow that's run when a webhook is invoked and aids in making sure the request gets to the right place.
You can now invite third-party vendors to log in to Prismatic with limited access to your integrations, custom components, and customers. This is helpful if you need to collaborate on a new integration with a third-party vendor. You can grant them view or edit access to a particular integration or set of custom components, which allows them to test the integration against their app or service. You can debug and iterate faster on integration and custom component development, and can have one central place to view logs and test runs. You can also view logs of each test a third-party vendor performs to give you a sense of how their side of the integration development is progressing.
Permissions are granular - third-party users only see what they've been given permissions to see. So, if you're integrating with two competing companies, or even with one of your competitors, they are not given insight into the other integrations, custom components, or customers you have in your Prismatic account.
Read more about the third-party user role in our docs.
Prismatic now provides full support for multi-flow integrations!
Integrations can now include multiple flows. (A flow is a trigger and a series of steps.) This enables you to provide your customers with a complex third-party integration that performs multiple related tasks, but is packaged and deployed as a single integration.
For example, you might integrate with an ERP that sends a variety of data via webhooks to your application (a webhook when inventory is updated, a webhook when customer info is updated, and so on). Rather than constructing integrations with complex branches or assembling multiple integrations, you can now create a single integration with flows that handle each type of webhook payload. You would create a flow to handle inventory updates, another flow to handle customer updates, and deploy all of those flows together as a single instance to a customer.
Each flow has its own trigger (so it gets its own webhook URL), and flows are tested and run independently of one another.
When customers or customer-facing teams deploy a multi-flow integration, they configure and deploy all of the flows at once using a single configuration screen.
Your existing integrations will continue to operate as expected. Please note:
- The Selected Test Run dropdown has been moved to the input reference selector. When configuring an input for a step, you can select which test run to preview outputs for within the Reference tab.
- Prismatic's CLI, Prism, has been updated to version 3.0.0 to account for this change.
To install the latest Prism, run:
npm install --global @prismatic-io/prism
- The YAML that defines integrations has been updated. See the Integrations docs article.
You can now configure integration flows with triggers that are invoked when an instance is deployed to a customer. This is helpful if you have a set of “initialization” tasks that need to be completed once to set up a customer’s instance.
A deploy-time flow could enable features in a third-party app, set up third-party users or permissions, create a directory structure in a file storage system, or even set up webhooks in a third-party application to point to the instance’s other flows.
Check out our deploy trigger docs for more info.
We've continued to expand our built-in component offering. A full catalog is available here. This month, we added:
- Airtable - List, create, delete, and update records in an Airtable Base
- Amazon SES - Send email through Amazon's Simple Email Service (SES)
- Google Drive - Manage files that are stored in a Google Drive account
- Google Sheets - Create, read and modify spreadsheets in a Google Drive account
- Mongo DB - Create, read, update and delete documents inside a NoSQL MongoDB collection
- Microsoft Power BI - Interact with datasets and data schemas within Microsoft's data visualization and business analytics service
- MySQL - Query and manage data in a MySQL database
- Shopify - Interact with Shopify's Access Service API
- Stripe - Interact with Stripe's payment platform
The Shopify and Stripe components were both generated from OpenAPI definitions using Prism's component generator tool.
You can now configure authorization settings per action (as opposed to per component). This is helpful if you are building a component with multiple actions and only some of your actions require authorization.
Read about how to upgrade your component to use per-action authorization on our Spectral 3.x Upgrade Guide.
Several new components have been added to our catalog of built-in components:
- Amazon DynamoDB - Create, update, fetch, or delete items in an Amazon DynamoDB database
- Amazon SNS - Manage subscriptions, topics, and messages within Amazon SNS
- Amazon SQS - Send, receive and manage messages within an Amazon SQS queue
- AMQP - Send and receive messages on an AMQP-based message broker
- Apache Kafka - Publish messages to an Apache Kafka event stream
- Customer.io - Manage customers on the Customer.io platform
- Microsoft SQL Server - Query and manage data in a Microsoft SQL Server Database
- MQTT - Send and receive messages on an MQTT-based queue
- PostgreSQL - Query and manage data in a PostgreSQL database
Prismatic's custom component TypeScript library,
@prismatic-io/spectral, has been expanded and updated to improve the developer experience for building custom components.
Updated syntax for creating components, actions, and inputs helps to catch common errors at compile time (rather than runtime), and new utility functions help to guarantee that you pass the correct variable types to third party SDKs and APIs.
Versioning has been improved for components, integrations, and instances to give you more fine-grained control over exactly what code is deployed to customers.
Components are now assigned an integer version that increments each time the component is published. If a custom component is at "version 3" and you publish a new component definition, that new definition gets "version 4". This allows you to update or extend components without unintentionally impacting existing integrations that use them, ensuring your integrations remain stable. Integration builders can then update the component versions used in their integrations, or roll back to a previous versions when desired, and will be notified when newer versions of components are available.
Integration versioning has been improved, giving you more control over what versions of integrations you deploy to customers. When you publish new changes to an integration, similar to components, your integration is assigned a new version number. Then, when you deploy an instance to a customer, you can choose which version of the integration to use. That means you can have some customers on version 1, and others on version 2 as needed, giving you control over which customers have what, and allowing you to test a new integration version with a small subset of your customer base before deploying it broadly.
Rolling back an instance deployment is a breeze - if you deploy a new version of an integration to a customer and something seems off, you can easily roll back your instance to a known working version of the integration with just a couple of clicks.
As always, updating customers' instances can be scripted, so you don't need to manually deploy a new version of an integration to each customer.
APIs often have hundreds of unique endpoints that you can interact with. With the release of Prism version 1.0.8, you can now generate a custom component from a WSDL or OpenAPI file. That means you can have a custom component for a third-party service with hundreds of actions with a single CLI command.
Read more on our Writing Custom Components article.
It's now easier for your customers to manage instances of integrations that have been deployed to them. Customer users with admin permissions can update config variables and credentials that are associated with their instances. So, if their config or credentials for a third-party service change, they can log in and make the change without needing your help.
For more information on customer user roles and permissions, see the users article.
Organizations with an enterprise plan can now create a custom theme for the Prismatic web application. This takes Prismatic’s white-label capabilities to the next level by allowing you to customize the color scheme and other UI elements to match your branding. Once you apply a custom theme, it will be displayed for both your team members and customers.
For more information, see our custom theming docs.
It's now much easier to configure instances of your integrations to run on a unique schedule for each of your customers. For example, Customer A could be set up to run the integration each day at 4:00PM, while Customer B could be set up to run the integration hourly, depending on their needs.
For more information, check out our integrations article.
Significant improvements have been made to credentials, integration configuration and instance deployment.
Integration builders now have the ability to create an easy-to-use configuration page for customer-facing teams. Builders can define config variable names, give hints as to what sort of data is expected, add headers, etc., giving their customer-facing teams an intuitive experience when it comes to deploying an integration.
This ultimately makes for easier and faster deployment of integrations, without the need for developer intervention. Read more about setting up config variables on our integrations article, and about the new instance configuration experience on the instances article.
Small amounts of data (state) can now be stored between instance executions. This is handy if you want to save some information about one instance execution to use later in a subsequent execution.
Prismatic handles several common state persistence scenarios for you through the new Persist Data and Process Data components. Check out the Integrations article to learn how to leverage state persistence in your integrations, or read the Writing Custom Components article to incorporate state persistence into your custom components.
Organizations with a professional or enterprise plan can now configure instances to automatically retry if an execution fails. You can control how many times an instance attempts to run with the same input, and how long it should wait between failed attempts. If you have an integration that relies on a flaky third-party API, for example, this minimizes interruptions for both your customers and your team.
You can also replay - manually retry - a specific failed execution of an instance.
You can now choose to invoke your instances synchronously or asynchronously. When you invoke an instance synchronously, your request says open until the instance completes, and results from the instance's run are returned as an HTTP response.