There are many ways to create Prismatic integrations. You can assemble one through the web app, through the Prismatic CLI, through calls to the Prismatic API, or by defining your integration as code in a YAML file.
We recommend that you assemble your first few integrations through the web app so you can acquaint yourself with triggers, action steps, inputs and outputs, configuration variables and credentials, but once you feel comfortable with these concepts we encourage you to explore creating integrations programmatically.
Anything you can add to an integration in the web app, you can add through YAML as well. Using YAML syntax, you can define an entire integration, including its trigger and action steps, and how data flows between the steps.
Advantages of Writing Integrations as Code
If you are a developer, regardless of if you fall on the Vim, Emacs, or VSCode side of the editor war, you are likely more productive in a text editor than you are in a web browser. You can grep over a codebase and make changes to your integrations more quickly in an editor than you can in a browser. In addition to yielding greater productivity, writing integrations as code gives you:
- A faster feedback loop. Make significant changes to multiple steps of an integration and test the integration from your terminal - no clicking required!
- The ability to store integrations in your source repository. Your integration can go through whatever spec writing, development, code review, and deployment cycle you currently use. You can develop your integration in tandem with your core product and its APIs.
- The option to update integrations as part of your CI/CD Pipeline. Is your integration dependent on updates to your APIs? You can plug your YAML-defined integrations into your CI/CD pipeline, so integrations are deployed alongside the rest of your code base.
Integration YAML File Anatomy
A YAML-defined integration contains five required sections: name, description, trigger, requiredConfigVars, and steps.
- name is a brief unique identifier, and the name of the integration. For example, "Queue 3D Print Job".
- description is an optional longer explanation of what the integration does. Your team members in the web app can search for integrations by name or description. For example, "This integration converts a completed .rocket file to AutoCAD format and queues a 3D print job."
- trigger defines how the integration should be invoked. It takes a required name, and optional description, outputs, and schedule, each of which are described in more detail below.
- requiredConfigVars describes the configuration variable keys and their default values that your integration uses.
- steps is an ordered list of actions your integration will execute. Each step takes a required name, an action to execute, and optional description and step inputs and outputs, described in more detail below.
Integration Triggers in YAML
An integration trigger defines when an instance of an integration should run. The integration can be triggered by a webhook, or on a schedule similar to a cron job. If a schedule is specified, the trigger will run on a schedule. If schedule is omitted, a webhook trigger will be created.
For More Information: Integration Triggers
Specifying a Scheduled Trigger in YAML
You can run integrations on a schedule using cron notation. For example, if you want instances of an integration to run at 03:00 AM every Sunday and Wednesday morning, you can configure a trigger to run at that time:
For More Information: Schedule Triggers
Capturing Webhook Trigger Output in YAML
If your trigger is invoked by a webhook, the body and header information of that output is accessible by referencing
To simplify output variable names, you can capture specific output and assign that to an output variable.
In this example, suppose a webhook contained a JSON payload body of
You can capture that
123 value like so:
Subsequent steps can then reference
For More Information: Webhook Triggers
Configuration Variables in YAML
Configuration variables are defined in the
requiredConfigVars portion of integration YAML files as key-value pairs:
Steps can reference these configuration variables using
Integration Action Steps in YAML
Integrations are comprised of multiple steps. A step requires a name (referenceable name), and an action to execute. Optionally, a step can take a description, and can reference inputs and produce outputs.
The step's action takes a key of an action, and the action's componentKey.
The componentKey is required, since action keys are not necessarily unique (AWS S3 and Azure file might both have a
Action keys and component keys can be found using the Prismatic CLI
For example, if you want to add a step that lists all objects of an S3 bucket, you can run this to get the action's key and componentKey:
You can then use those keys in a step:
JSONata syntax in inputs and outputs
us-east-1 is wrapped in single and double quotes, and
configVars.myBucketName is not wrapped in quotes at all.
This is because we want
configVars.myBucketName to be interpreted as variable, and
us-east-1 as a string.
Due to how YAML interprets strings,
awsRegion: "us-east-1" is equivalent to
We need to explicitly state that the quotation marks are intentional - we do that by wrapping quotation marks within quotation marks.
Multi-line Values in YAML
Importing a YAML-Defined Integration
To import a YAML-defined integration, use the Prismatic CLI
Exporting an Integration as YAML
An existing integration that was built via YAML or in the integration designer can be exported to a YAML file using the Prismatic CLI
Example Integration in YAML
The integration from the getting started tutorial pulled down "TODO" items from a list, and posted a message to Slack. That entire integration can be defined in a short YAML file:
Opening up the web app, we see that this YAML-defined integration created the appropriate trigger, steps, config vars and inputs.
After you feel comfortable defining basic integrations with YAML, we recommend you check out our Writing an Integration in YAML with Trigger Payloads, Inputs, and Outputs quickstart, where we examine how to handle webhook trigger payloads, code components, and knitting inputs and outputs throughout a YAML-defined integration.