Terminal
Terminal/Skill
Helps write and edit Paragon Paragraph workflows in TypeScript, covering triggers, request steps, branching, and reusable steps.
By Paragon
Works with
npx skills add useparagon/paragon-ai-skills --skill paragraph-workflow-builderUse for workflow definitions in a Paragraph repo: files under src/integrations/<integration>/workflows/, triggers, steps, branching, and wiring to the Paragon dashboard. For integration config only (config.ts / inputs.ts), use the project skill paragon-paragraph-custom-integrations.
Official references
para new workflow --integration <integration> (e.g. hubspot, linear, or custom.myapp).src/integrations/<integration>/workflows/.readonly id as generated; Paragon maintains it.config.ts in workflowDisplayOrder so they appear in the Connect Portal and dashboard.Match the generated pattern in this repo:
Workflow<IIntegration, IPersona<typeof personaMeta>, InputResultMap> from @useparagon/core.IContext, IConnectUser, IPermissionContext, persona types, and InputResultMap / I…Integration from @useparagon/integrations/<name>.personaMeta from ../../../persona.meta (adjust depth if the workflow folder depth differs).define(integration, context, connectUser)
.nextStep(...) (this repo’s @useparagon/core surface).this.register({ … }) with an object whose keys are stable (they map to the workflow graph); every step used in the graph should appear here.Class fields (common)
| Member | Role |
|---|---|
name, description | Dashboard and Connect Portal copy |
inputs | Workflow-level user settings via createInputs({ … }) from the integration package |
defaultEnabled, hidden | Connect Portal behavior (see Paragon connect-portal docs) |
definePermissions | Optional ConditionalInput for workflow visibility |
id | Do not edit |
| Kind | Source |
|---|---|
Triggers: CronStep, EndpointStep, EventStep, IntegrationEnabledStep | @useparagon/core |
Core steps: RequestStep, ResponseStep, ConditionalStep, FunctionStep, FanOutStep, DelayStep, IntegrationRequestStep, … | @useparagon/core |
| Integration-specific actions and triggers | integration argument in define, e.g. integration.triggers.recordCreated({ … }), integration.actions.searchRecords({ … }, { … }) |
Optional step options (second arg on many integration actions, or step config): autoRetry, continueWorkflowOnError, description, etc., per defining workflows.
someStep.output… (template strings can interpolate like the Workflow Editor’s {{1.output…}}).context.getEnvironmentSecret("KEY").context.getInput(…) — integration-level inputs from that integration’s inputs.ts / exports; workflow-level from this.inputs (see defining workflows).connectUser.userId, connectUser.meta… (metadata typed from persona.meta.ts).triggerStep.nextStep(stepA).nextStep(stepB).conditionalStep.whenTrue(stepIfTrue).whenFalse(stepIfFalse) then continue with .nextStep(...) on the conditional as needed (see conditional branches).fanOutStep.branch(innerStep.nextStep(…)) — .branch is not chainable; then connect the fan-out’s continuation per docs (fan out branches).import * as Operators from '@useparagon/core/operator';ConditionalInput to ConditionalStep (and similar APIs such as pagination stopCondition).| Trigger | Use case |
|---|---|
EndpointStep | HTTP request trigger; set allowArbitraryPayload or validations; output: output.request (headers, body, params, file). |
CronStep | Scheduler; init params include cron and optional timezone (IANA string; types live in @useparagon/core). Some older docs may show different casing—prefer the installed package. |
EventStep | App Event from src/events; import the event module into the workflow file. |
IntegrationEnabledStep | Runs when user enables the integration. |
Details and examples: @useparagon/core glossary — Triggers.
RequestStep: full URL; you supply auth (e.g. Bearer) via authorization or headers; output output.response (statusCode, body, headers).IntegrationRequestStep: path relative to integration apiBaseUrl (or full URL); user’s integration auth applied automatically; same output.response shape.Pagination: optional pagination callback returning outputPath, pageToken, stopCondition (Operators). See request pagination and the glossary example.
ResponseStepOnly for workflows driven by an HTTP request trigger: set responseType, statusCode, and body (JSON or file). See glossary ResponseStep.
FunctionStepRuns sandboxed code: must be self-contained; pass data via parameters. Signatures and allowed libraries are in Paragon’s JavaScript libraries doc. Output: functionStep.output.result. Follow the pattern already used in the repo (string module-style code vs inline code) for consistency with neighboring workflows.
Put shared helpers under a top-level src/<something>/ folder not named integrations (e.g. src/common/), export step factories, import from workflows. See Reusing steps. For secrets inside shared code, patterns using Execution appear in the same doc page.
.nextStep chain (or branches/fan-out as designed).this.register({ … }) with unchanged keys if the workflow already exists in Paragon.@useparagon/integrations/...).config.ts workflowDisplayOrder includes this workflow class if it should show in the portal.For step parameter details not repeated here, prefer the live glossary: @useparagon/core.