Description

n8n-nodes-formaloo

This package provides n8n nodes for integrating with Formaloo, a form builder platform.

Nodes

Formaloo Trigger

• Node Name: Formaloo Trigger
• Type: Trigger
• Description: Triggers workflows when forms are submitted or updated in Formaloo
• Events Supported:

– Form Submit
– Row Update
– Payment Completed
– All Events

Formaloo Action

• Node Name: Formaloo
• Type: Action
• Description: Submit data to Formaloo forms with advanced field type handling
• Operations:

– Submit Form: Submit data to a specific Formaloo form with automatic field type conversion

Credentials

The nodes require Formaloo API credentials with the following fields:

• Secret API: Your Formaloo secret API key (used for JWT authentication)
• API Key: Your Formaloo API key (used for API requests)

These credentials are used to:
1. Generate JWT tokens for authentication
2. Make API requests to Formaloo endpoints
3. Create and manage webhooks

Prerequisites

• A Formaloo account with API access
• Your Formaloo Secret API key
• Your Formaloo API key

Compatibility

• Minimum n8n version: 0.1.0
• Tested with n8n version: 1.17.0+
• Node.js version: 20.15 or higher

Installation

Follow the installation guide in the n8n community nodes documentation.

Alternatively, you can install manually:

1. Install the package:

   npm install n8n-nodes-formaloo
   

2. Add the nodes to your n8n instance by copying the dist folder to your n8n custom nodes directory.

Usage

Setting up the Trigger Node

1. Add a “Formaloo Trigger” node to your workflow
2. Configure your Formaloo API credentials
3. Select the form you want to monitor
4. Choose the event type (form submit, row update, etc.)
5. The node will create a webhook in Formaloo and trigger your workflow when events occur

Setting up the Action Node

1. Add a “Formaloo” node to your workflow
2. Configure your Formaloo API credentials
3. Select the form you want to submit to
4. Add form fields with their IDs and values
5. The node automatically handles field type conversion for complex fields

For new users, check out the Try it out documentation to get started with n8n.

Field Types

Unsupported Field Types

The following field types are currently not supported and will be filtered out from the field selection:

• matrix – Matrix fields
• table – Table fields
• lookup – Lookup fields
• user – User fields
• profile – Profile fields
• linked_rows – Linked rows fields
• repeating_section – Repeating section fields

Multiple Choice Fields

For Multiple Select fields, use comma-separated values to select multiple options:

Example:

Field Value: "Option 1, Option 2, Option 3"

Note: Make sure to use the exact option titles as they appear in your Formaloo form.

City/Country Fields

For City and Country fields, the node automatically searches and maps your input to the correct Formaloo option:

Example:

Field Value: "New York" or "United States"

The node will automatically find the matching city/country and submit the correct slug.

API Endpoints

The nodes use the following Formaloo API endpoints:

• Forms List: GET https://api.formaloo.me/v3.0/forms/
• Form Details: GET https://api.formaloo.me/v3.0/forms/{formSlug}/
• Webhooks: POST/GET/DELETE https://api.formaloo.me/v3.0/forms/{formSlug}/webhooks/
• Form Submit: POST https://api.formaloo.me/v3.0/form-displays/slug/{formSlug}/submit/
• Field Options: GET https://api.formaloo.me/v3.0/fields/{fieldSlug}/
• City/Country Search: GET https://api.formaloo.me/v4/fields/{fieldSlug}/choices/?search={searchValue}

Resources

• n8n community nodes documentation
• Formaloo API Documentation
• Formaloo Website

Development

Local Development

1. Clone the repository and install dependencies:

   git clone https://github.com/formaloo/n8n-nodes-formaloo.git
   cd n8n-nodes-formaloo
   npm install
   

2. Build and test locally:

   npm run build
   npm run lint:n8n
   npm run start
   

This will build the package and start n8n with your custom node loaded at http://localhost:5678

Alternative (manual):

   npm run build
   N8NCUSTOMEXTENSIONS=$(pwd) npx n8n start
   

Windows:

   set N8NCUSTOMEXTENSIONS=%CD% & npx n8n start
   

3. After making changes, rebuild and restart n8n:

   npm run build
   

Available Scripts

• npm run build – Build TypeScript to JavaScript
• npm run dev – Watch mode (auto-rebuild on changes)
• npm run start – Build and start n8n for testing
• npm run lint – Check code quality
• npm run lint:n8n – Validate the package with the current n8n node CLI
• npm run lintfix – Auto-fix linting issues
• npm run format – Format code with Prettier

Publishing

Publishing to npm

Releases are published only by .github/workflows/publish.yml. It installs dependencies with npm ci, builds, runs the n8n node validation, and publishes with npm provenance.

Before the first release, configure an npm Trusted Publisher for n8n-nodes-formaloo with GitHub Actions owner formaloo, repository n8n-nodes-formaloo, and workflow filename publish.yml. No npm access token is required.

To release, update the package version, merge it to master, then publish a GitHub Release for the matching tag (for example, v1.7.1). The workflow publishes that release to npm.

Version History

1.5.0

• Current version
• ResourceLocator with search functionality for form selection
• Improved form loading performance
• Enhanced error handling with pairedItem support
• Migrated to httpRequestWithAuthentication
• Backward compatibility with deprecated functions

Previous Versions

• See git tags and GitHub releases for detailed version history

License

MIT