Skip to main content

Building Basics

When you build an integration, you can build it in the low-code designer, or as a TypeScript project in your favorite IDE. We call an integration built with code a code-native integration (or CNI).

An integration built with the low-code builder consists of a series of steps that execute one after another in series. Each step runs an action - a small bit of code designed to perform a specific task. Actions can be things like "HTTP - GET" to fetch the contents of a webpage from the internet, or "Amazon S3 - Put Object" to save a file to Amazon S3. You can use a combination of actions from common built-in components and your own custom components to build an integration.

A code-native integration is a set of flows written in TypeScript that run when a trigger fires.

An integration is started when its trigger fires. Triggers can either follow a schedule, or can be invoked via a webhook URL.

Integrations should be developed to be configuration-driven, so they can be deployed to multiple customers with potentially different configurations. That is accomplished by leveraging config variables, and have configuring steps to reference those variables.

Many integrations have a single flow. That is, they have a single trigger that fires, and a single set of steps that are executed one after another. Prismatic also supports grouping multiple related flows together into a single deployable integration. For example, if you have a third-party service (Acme ERP) that sends data via a variety of webhooks to your integrations, it probably makes sense to have a single Acme Corp integration that you or your customers deploy that is made up of several logical flows. Each flow has its own trigger, though they all share config variables.

When an integration is completed, it can be published. Customers can then enable the integration for themselves through the integration marketplace, or your team members can deploy an instance of the integration on the customer's behalf. Regardless of who enables an instance of the integration - your team member or your customer - the person deploying the instance configures the instance with customer-specific config variables.

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

Creating a new integration​

To create a new integration in the web app, click Integrations from the left-side menu, and then click the + Add Integration button in the upper-right.

When you create a new integration you have a few options:

  • You can create a blank integration from scratch by selecting Quickstart.
  • Behind the scenes, integrations are saved as YAML definitions. You can load a YAML file from your clipboard or from a file by selecting Import.
  • You can start from an existing template - you can create your own template, or you can select a Prismatic-built example template.
Configure a new integration

You will be prompted to give your integration a name and to select a trigger for the first flow of your integration. The trigger is what will cause one of your integration's flows to run, and you can change your trigger at any time.

Add integration in Prismatic app

For more information: Building Integrations, Testing Integrations

Integration templates​

Some of your integrations will look similar to one another. For example, if you are importing opportunities and accounts from a dozen CRM vendors, the steps that fetch data will be unique, but the steps that send data to your app will always look the same. Rather than developing those common steps over and over, it saves time to create an integration template that you and your team can start from when you build additional similar integrations.

To turn your integration into a template, first publish a version of your integration. Then, open the Integration details modal and select Available as Template.

Create a new template of an integration

You can choose if the template is just for org users, or if you offer embedded designer you can make the template available to customer integration builders.

Assigning an icon to an integration​

Integrations can be assigned icons, to make them more presentable in the integration marketplace. To assign an icon to an integration from the integration designer by clicking the icon to the left of your integration's name:

Add icon to integration in Prismatic app

Square PNG images that are at least 400 pixels wide look best as integration icons.

Integration labels​

Labels help you keep your integrations organized.

You can assign any number of labels to an integration from within the integration designer by opening the Integration details menu:

Assign labels to integration in Prismatic app

You can search for integrations by label. Note: for consistency, labels are always lower-cased.

Labels applied to published integration versions appear in the version dropdown menu on an instance configuration page.

Versions and labels for instance configuration in Prismatic app

Listing and searching integrations​

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

All integrations for organization in Prismatic app

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, category, labels or marketplace availability by clicking the Filter button to the right of the search bar.

Filter integrations in Prismatic app

Categorizing integrations​

Integrations can be assigned a "category" for easy sorting and filtering. For example, you might have a dozen "ERP" integrations, a few "Inventory Management" integrations, etc. Assigning each integration a category allows your team, as well as your customers in the integration marketplace to view integrations sorted by category.

You can set a category for an integration by clicking the Integration details button on the top-left of the integration designer:

Set category for integration in Prismatic app

Publishing an integration​

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

To publish an integration, first open the Version history tab on the left side of the page. If you have unpublished changes you'll see an Unpublished Draft listed among the integration's versions. Type a note about the changes you made to the integration, and then click Save & Publish to release a new version of your integration:

Publish integration in Prismatic app

Integration versions can be marked Available or Unavailable by toggling the blue toggles to the right of integration versions. Marking an integration version Unavailable prevents that version from being deployed as an instance to a customer.

Deploying an integration​

Once an integration has been published, an instance of the integration can be configured and deployed to a customer. See the instances article for information on deploying instances of integrations.

You can also enable your customers to deploy integrations themselves, using Prismatic's integration marketplace.

Viewing deployed instances​

To view all instances that have been deployed, click the Instances tab from the integration designer screen. This screen will display customers to which this integration has been deployed.

List of deployed instances in Prismatic app

The version of this integration that is deployed to each customer is shown within this drawer.

Forking an integration​

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, click the icon on the top left of the page. Then, click Duplicate Integration. Give your forked integration a new name and description and then click ADD.

Deleting an integration​

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, click the Integration details button on the left of the page. Then, select Remove integration.

Integration attachments​

Your team can save and share integration-related documents alongside an integration by clicking on the Documentation & attachments button on the left side of the integration designer.

Add attachments to integration in Prismatic app

Internal integration documentation​

It's helpful to share documentation, specs and notes about an integration with your team members. You can add internal (non-customer-facing) notes and documentation to an integration by clicking the Documentation & attachments button on the left-hand side of the integration designer. Here, you can share notes, links, and other documentation with your team members.

Add internal documentation to integration in Prismatic app

YAML definition​

Behind the scenes, integrations are represented in YAML. You can view the YAML that defines your integration's flows, steps, inputs, connections and config variables by clicking Integration details button at the top-left of the integration designer, and selecting View YAML.

YAML for integration in Prismatic app

If you are exporting the integration and importing it in a different region (US -> EU, for example), make sure you click a latest component versions button, as component versions may not match between regions.

Tip: Spot changes to integrations

The YAML present in this drawer corresponds to the integration that is currently being displayed. You can view the YAML of a previous version of the integration by first opening the VERSION HISTORY drawer and selecting an older integration version.

If you want to spot differences between an older version of your integration and the current version, you can compare the YAML definition of the older version with the YAML definition of the current version using your favorite diff tool (VSCode has a great built-in diff tool).

Exporting an integration​

Once you've opened the Integration details modal in the integration designer, you can click Copy to clipboard to copy the integration's YAML definition into your clipboard, so you can paste it into an editor of your choice. You can also click Save to file to download a copy of your integration.

If you are using Prismatic's command line tool, prism, you can use the integrations:export subcommand to similarly export the YAML definition of your integration.

Importing an integration​

If you have a YAML definition of your integration saved in your clipboard, you can click Load from clipboard to replace your current integration with the definition that you have copied. Or, you can save a modified YAML file to your computer, and load the YAML definition by clicking Load from file and selecting the file you saved.

If you are using prism, you can use the integrations:import subcommand to import a YAML definition of your integration.

Renaming flows and config variables in YAML definitions​

Use caution when modifying flow names or config variable names in YAML

If you modify the name of a flow or config variable in the YAML definition, you should include a renameAttributes section in your YAML.

Your integration is made of flows, steps, config variables, and some other metadata, and can be represented as a YAML file. When a YAML file is imported, the Prismatic API attempts to match flows and config variables in the YAML with flows and config variables in the existing integration. If a match is found, the existing config variable or flow will remain. If no match is found, a new config variable or flow will be created and the old flow or config variable will be removed.

This presents problems if you want to rename flows or config variables in your YAML definition:

  • If you rename a flow, the Prismatic API will not be able to match the flow in the YAML with a flow in the existing integration, and will create a new flow and delete the old one. Your integration will functionally be the same, but the flow's ID behind the scenes will be different. Instances of your integration will be assigned new webhook URLs for the renamed flow when the instance is updated to the latest integration version. Different webhook URLs can cause issues if you already have webhooks configured using the old flow's URL.
  • If you rename a config variable, the Prismatic API will not be able to match the config variable in the YAML with the config variable in the existing integration, and will create a new config variable and delete the old one. This will cause issues if you have already configured instances of your integration. When a customer updates their instance, their old config variables will be removed and new ones will need be reconfigured (this includes OAuth 2.0 connections - the customer user will need to reauthenticate their connection).

To ensure that the Prismatic API matches the flow or config variable in the YAML with the flow or config variable in the existing integration, you should include a renameAttributes section in your YAML. This section includes requiredConfigVars and flows sections, which outline the old and new names of config variables and flows, respectively.

configPages:
  - elements:
      - type: configVar
        value: SFDC Connection
      - type: configVar
        value: SFDC Record Type
    name: Page 1
    userLevelConfigured: false
definitionVersion: 7
endpointType: flow_specific
flows:
  - description: ""
    endpointSecurityType: customer_optional
    isSynchronous: false
    name: SFDC Data Import
    steps: []
name: SFDC Integration
requiredConfigVars:
  - key: SFDC Record Type
    description: ""
    dataType: string
    orgOnly: false
    defaultValue: ""
  - key: SFDC Connection
    description: ""
    dataType: string
    orgOnly: false
    defaultValue: ""
renameAttributes:
  requiredConfigVars:
    - newName: SFDC Connection
      oldName: Salesforce Connection
    - newName: SFDC Record Type
      oldName: Salesforce Record Type
  flows:
    - newName: SFDC Data Import
      oldName: Salesforce Data Import

In the above example, we renamed the flow Salesforce Data Import to SFDC Data Import, and renamed the config variable Salesforce Connection to SFDC Connection and Salesforce Record Type to SFDC Record Type. With this block included, the Prismatic API will know to match the old flow and config variable names with the new flow and config variable names, and will not replace flows or config variables with new ones.