Low-Code Integration Designer

When you build an integration, you can build it in the low-code designer, or as a TypeScript project in your favorite IDE using the Code-Native SDK. This article covers how to build an integration with the low-code designer.

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

The integration designer contains four important features:

1. Several configuration menus let you edit your integration's name, description, and other metadata, publish a version of your integration, add it to your integration marketplace, deploy an instance to a customer, and more.
2. The step configuration drawer lets you configure steps of your integration, change runtime/webhook configuration, etc.
3. The testing drawer lets you run tests of your integration, supply your integration with sample payloads, and see results of your integration test runs.
4. The majority of the page is taken up by the integration editor pane. Here, you can add steps to your integration, create branches and loops, and generally arrange the flow of your integration. You can also create multiple flows - each flow has a trigger and series of steps to be executed.

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.

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.

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:

Assigning labels to an integration

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

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:

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:

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.

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.

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

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.

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.

Integration metadata

You can attach metadata to your integration programmatically, which is helpful if there are properties that you'd like to assign to your integration that are not covered by integration category or labels.

Metadata must always be JSON-formatted, and is readable and editable only through the Prismatic GraphQL API.

To set metadata on an integration, invoke the updateIntegration mutation and assign your integration a metadata value:

mutation setIntegrationMetadata {
  updateIntegration(
    input: {
      id: "SW50ZWdyYXRpb246MGVjNDlhZmYtNjE2YS00NmU2LWExMTQtN2RjOThjY2Q1MzU4"
      metadata: "{\"price\": 100, \"compatible_plans\": [\"professional\", \"enterprise\"]}"
    }
  ) {
    integration {
      metadata
    }
    errors {
      field
      messages
    }
  }
}

That metadata can be read as a property of an integration record:

query getIntegrationMetadata {
  integration(
    id: "SW50ZWdyYXRpb246MGVjNDlhZmYtNjE2YS00NmU2LWExMTQtN2RjOThjY2Q1MzU4"
  ) {
    name
    metadata
  }
}

A few notes on metadata:

• metadata must be a valid JSON string
• The maximum length of metadata is 4096 characters
• Metadata is accessible via the API, but not surfaced in the UI
• Metadata is not exported as part of an integration's YAML definition.

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.

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