Custom Connectors Overview
Overview
Prismatic is extensible and allows developer users to develop their own custom connectors. Connectors that Prismatic users develop are proprietary to their organization and are private.
Connectors are Node.js/TypeScript projects that accomplish specific tasks or connect to an outside service. Connectors comprise:
- Connections which contain information such as passwords, API keys, or OAuth 2.0 connection information. Your customers fill in their authentication information for connections when they deploy your integration.
- Actions which are purpose-built functions that you can use in your integration. You might build "Create Widget" or "List Gadgets" actions in a custom connector, and each action can be used as a step within an integration.
- Triggers determine when an integration should run and how it should handle requests. You might create a custom trigger that configures webhooks in a third-party application when a customer configures an instance of your integration and responds to webhook requests from the third-party appropriately.
- Data Sources fetch data dynamically during the config wizard experience. For example, you might create a data source that fetches a list of projects in a CMS and presents the projects as a dropdown menu in the config wizard.
Sample connector code is referenced throughout these docs.
For a sample connector that wraps an HTTP-based API, see our quickstart on Wrapping an API in a Custom Connector.
Custom connector library
Prismatic provides a Node.js package, @prismatic-io/spectral, which provides TypeScript typing and some utility functions. Source code for Spectral is available on GitHub.
Node.js Version Support: While many versions of Node.js may work for connector development, we recommend using the latest LTS (long-term support) version of Node.js. You can find the latest LTS version on the Node.js download page.
The terms connector and component are used interchangeably in the Prismatic platform. Generally, if a component connects to a third-party API, we call it a connector. But, not all components connect to external APIs. The Change Data Format component, for example, converts data between common formats (JSON, XML, etc), and the Math component provides a variety of math utility functions, but neither component makes a network request to a third-party app.
Customer users and custom components
If you use the embedded workflow builder, your customers may want to build their own custom components and use them in their workflows. These private components are scoped to the customer and are not visible to other customers. This is beneficial when customers need to build custom components specific to their business (for example, to wrap their own API).
The development of customer-scoped custom components follows the same process as organization-wide custom components.
For a customer user to publish a custom component, you must create a customer user account and assign them the "Admin" role. The customer user must be able to log into Prismatic to authenticate the Prism CLI tool for publishing custom components. A customer user cannot use a signed JWT to publish custom components.
Once a customer user has logged into Prismatic, they can authenticate the Prism CLI tool by running prism login and then publish a component scoped to their customer with prism components:publish, as an organization team member would.
To publish a component as an organization team member for a specific customer, run prism components:publish --customer <CUSTOMER ID> using an ID that you can fetch by running prism customers:list --columns "id,name".