![Page cover image](https://docs-prod.useparagon.com/~gitbook/image?url=https%3A%2F%2F2053411491-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MCJwlyhqtCdBfCLUO0d-1223115691%252Fuploads%252FRDY0LhCTCAZGXN6KZQf1%252FFrame%25201000002911%2520%282%29.png%3Falt%3Dmedia%26token%3Dbac1949e-7b75-466b-b26e-c06fac3292ae&width=1248&dpr=4&quality=100&sign=40cf5dc0&sv=1)
Getting Started with Paragraph
Paragraph allows you to author and maintain Paragon integrations as code, which can be synced with a Git repository to track revisions over time.
With Paragraph, your engineering team can:
Define all your integrations powered by Paragon as code, while still being able to view, edit, and debug from the dashboard
Version control all changes to your integrations in a Git repository, which can be used to bring code review, unit testing, and CI/CD to your development process
Use more advanced abstractions in Workflows, including reusable steps or modularizing workflow logic across integrations
Overview
Paragraph is a TypeScript-based framework for building your Paragon integrations in code. In a Paragraph project, you'll define:
Integrations that are available to your users
Connect Portal configuration, including User Settings and Field Mappings
Paragraph projects can be packaged and sent to Paragon for deployment using the Paragon CLI or from your CI/CD.
You can also continue to use the Paragon dashboard to edit your projects. By setting up Git Sync, you can sync back changes made in the Paragon dashboard to your Paragraph project, stored in a Git repository.
For a personalized onboarding to Paragraph, you can book time with our team to get started.
Installing the CLI
Installing the CLI and authorizing your account
To begin setting up Paragraph project, you'll need to install the Paragon CLI. You can install the CLI globally with npm:
Once installed, the CLI will be available as the alias para
. See for the full reference for available CLI commands.
You can link your Paragon account to the CLI by running:
Follow the CLI prompt to login to Paragon and authorize the CLI. When you successfully log in, you should see:
Authenticating with the CLI generates a CLI Key which is stored locally in ~/.paragon/credentials.json
. You can view and revoke CLI Keys in the dashboard in Settings > CLI Keys.
Starting a Paragraph Project
Exporting from Paragon
You can export a Paragraph project from your Paragon dashboard by using the CLI:
A project selector will appear to choose a project to export as a Paragraph project.
Initializing an empty project
Alternatively, you can initialize a new Paragon project with the CLI:
Cloning an existing project
If you are cloning an existing Paragraph repository that a teammate started, make sure to install dependencies in the project:
Creating a new integration
Create a new integration in Paragraph with the CLI:
A prompt will appear to select the integration you'd like to add. Once selected, a new folder for the integration will appear in your src/
folder.
Learn more about how to configure an integration in Defining Integrations.
Creating a new workflow
Start building a new workflow in an existing integration with the CLI:
Specify the name of the integration folder, e.g. salesforce
in the --integration
flag. A prompt will appear to title the workflow. A new TypeScript file will appear in the src/integrations/[integration]
subfolder.
Learn more about workflows and how to define and orchestrate steps in Defining Workflows.
Building and pushing
Once you are ready to push your changes back to the Paragon dashboard, you can use the CLI to validate your project and push to Paragon:
Learn more about handling build errors in Build and Push.
Once you see a message confirming that a build has been created, use the CLI to upload to the Paragon platform:
Try Git Sync to configure an integration between your Paragraph files stored in a Git repository and your Paragon project.
Git Sync keeps your Paragon project and Paragraph repository automatically in-sync.
Last updated