Build your first workflow connector
In this guide, you will create, develop, test, and deploy a Workflow Connector using the project generated by the Stacksync CLI.
Each project includes a guide/ directory that documents the project structure and connector development model. You can follow these guides directly or provide them as context to an AI coding assistant.
✨ Build with an AI coding assistant
Paste this prompt into your AI coding assistant to build a Stacksync Workflow Connector.
Stacksync is an integration platform with a workflow automation tool. Builders can use the Stacksync Connector Development Kit (CDK) to create new Stacksync Workflow Connectors.
Every connector enables to connect to a system and can have several triggers or actions called modules. One connector has one or more modules. Each module has inputs and outputs. Modules are used in a workflow to automate tasks. Once the connector is built, the user can use the Stacksync workflow builder UI to create workflows that automate tasks between different applications.
Requirements:
- Application: <application name> // ask the user for the application name if not provided.
- Operations: <operations the connector must support> // ask the user or define this from web search if the user does not know.
- API documentation: <optional official documentation URL> // can be found via web search
- Additional requirements: <optional constraints>
Follow this process:
1. Search the Stacksync documentation at https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/overview and the other links available from this page. Explore thoroughly the Stacksync CLI and CDK documentation to understand how to create a connector and modules.
2. Research the application for which a connector should be built using its official API documentation. Determine the authentication method, base URL, required permissions, relevant endpoints, request and response schemas, pagination, and rate limits.
3. Check if the Stacksync CLI is already installed by running `stacksync --version`. If not, install it using the following command:
curl -fsSL https://cli.stacksync.com/install.sh | sh
4. Check if the user is authenticated with Stacksync by running `stacksync login`. If not, authenticate using the following command (the login will ask the user to connect via the web (or API token connection option is available) and to choose which Stacksync workspace to use):
stacksync login
5. Create the connector and enter the generated project:
stacksync workflow-connector create "<Application Name>"
cd <generated-project-directory>
6. Read the entire guide/ directory before changing any files.
Treat the guide/ directory as the source of truth for the project structure, CDK usage, connector architecture, module implementation, credentials, inputs, outputs, errors, and testing. Follow it exactly.
7. Update stacksync.yml with the correct connector metadata.
8. Implement the requested operations. Create additional modules when required:
stacksync workflow-module create "<Module Name>"
Keep generic_api_credentials as the connection type until the user provides the application-specific connection type. To create a generic_api_credentials connection, the user has to go in the UI > connections > create connection > generic_api_credentials. The user will need to provide the API key or the information to connect to the system vua the API depending on the authentication method of the application.
9. Start the connector locally:
stacksync workflow-connector run
// Once the connector is running, the modules will become available to use in the Stacksync workflow builder UI. Tell the user they can refresh the workflow builder UI to see the new module appearing in the list of available modules.
10. Instruct the user on how to test each module in the Stacksync workflow builder.
11. Stop after local testing. Do not deploy unless the user explicitly asks.
Ask only for information that cannot be determined from the official API documentation or the project guides. Do not invent endpoints, schemas, credentials, connection types, or tenant-specific values.
If the user is just exploring and does not know which system they want to build a connector for, suggest the user to create a connector for a popular application such as Salesforce or Postgres.Prerequisites
Stacksync CLI installed and authenticated
Python 3.10 or later
See Getting Started for installation and authentication instructions.
1. Create the Connector
Create a new Workflow Connector project:
stacksync workflow-connector create "My App"Move into the generated directory:
cd workflows-app-my-app2. Create a Module
The generated project includes a sample module named create_records under modules/, providing a working reference implementation.
You can modify the sample module or create a new one:
Remove the sample module when it is no longer required:
A module defines a capability exposed by the connector in the workflow builder.
3. Develop the Module
The guide/ directory explains how to:
Define inputs
Load dynamic options
Access connection credentials
Implement execution logic
Return outputs and errors
You can develop the module directly or with an AI coding assistant.
Using an AI Coding Assistant
Open the project in an AI-enabled editor and instruct the assistant to review the guide/ directory before making changes.
Describe:
The application or API to integrate
The operation the module should perform
The required inputs
The expected output
The authentication method
The included guides provide the implementation context required to follow Stacksync conventions.
Developing Directly
Review the guide/ directory and follow the instructions for each component of the module.
4. Run and Test
Start the connector locally:
Then test it from your Stacksync workspace:
Create or open a workflow.
Add an Action node.
Select the your connector and module from the list of moudles.
Configure the inputs and run the node.
While the local process is running, workflow requests execute against the code on your machine. Saved changes are applied immediately.
Press Ctrl+C to stop the process.
5. Deploy
Deploy the connector to your workspace:
After deployment, the connector is available in your workspace and can be used in workflows.
Last updated