monday_crm_integration

Send Drupal Webform submissions directly into monday.com boards via the GraphQL API. Each submission becomes a tracked board item with field-to-column mapping you control.

The relay is implemented as a Webform handler plugin you attach to any Webform. Each attachment gets its own configuration: which board to target, how Drupal field values map to monday.com columns, how the item name should be built, and what happens when monday.com is unreachable.

Features

• Per-webform configuration. Attach the "monday.com — Create board item" handler to as many Webforms as you like. Each attachment is configured independently — different boards, different mappings, different failure behaviour.
• YAML column mapping. Map Drupal Webform field keys to monday.com column IDs using a compact YAML block. Supports text, email, long_text, phone, status, and dropdown column types. Empty column_id means "collect this field but don't relay it."
• Webform-token item names. Build the monday.com item title from any submitted value using standard Webform tokens ([webform_submission:values:full_name], etc.). Falls back to a sensible default when the template resolves to empty.
• Two failure modes.
  • Validation-blocking: if monday.com is unreachable, the user sees a customisable error message and can retry. Submission is not saved until the relay succeeds.
  • Fire-and-forget: user always sees the confirmation; failures are logged with redacted diagnostics. Best when the form is critical to user experience and the relay is "nice to have."
• Per-handler phone country. The country shortname sent with phone column values is configurable per webform — useful for sites with audience in a specific region.
• Lead-source default tagging. Optionally set a constant status-column value on every item from a given webform (e.g. mark all submissions as "Website inquiry" so they're distinguishable from manually-created board items).
• Token kept out of config. The monday.com API token is read from Drupal's Settings API, not from config — so the token doesn't end up in config:export output, doesn't get committed to repos, and doesn't appear in failure logs.

When and why to use this module:

• You run a Drupal site and use monday.com to track leads, applications, projects, or any other workflow that has an inbound "create" step.
• You want the relay to live inside your Drupal site (auditable PHP code) rather than in a third-party automation service.
• You need different forms to feed different boards with different field mappings.
• You need fine-grained control over what happens when monday.com is briefly unreachable.

Post-Installation

1. Enable the module: drush en monday_crm_integration.
2. Add your monday.com API token to settings.php (or your environment-specific settings file):
   

   $settings['monday_crm_integration']['api_token'] = getenv('MONDAY_API_TOKEN');

   The actual token value should live in an environment variable, not in the file. You can read more about generating a monday.com API token in monday.com's developer documentation.

3. Open any Webform you want to relay → Settings → Emails / Handlers → Add handler → choose monday.com — Create board item.
4. Configure the handler:
   • Monday board ID (numeric, visible in the board URL on monday.com)
   • Item name template (Webform tokens supported; leave empty for the default "Submission from {webform label}")
   • Drupal field → Monday column mapping (YAML; see the handler's inline help)
   • Phone column country shortname (ISO 3166-1 alpha-2, default JP)
   • Lead source default (optional — set a constant status column on every item)
   • Failure handling — block-on-failure vs fire-and-forget, plus a custom user-facing error message
5. Save the handler. Submit a test entry on the webform. Check the monday.com board for the created item; check admin/reports/dblog if something didn't land.

There is no global configuration page — every setting lives on the handler-attachment form. This is intentional: different webforms typically need different boards, different mappings, and different failure behaviour.

To discover the monday.com column IDs you need for the mapping, use the bundled MondayClient::getBoardColumns() helper from a custom drush command or controller, or read them off monday.com's column-settings UI.

Additional Requirements

• Drupal core ^11
• PHP 8.3 or higher
• Webform ^6.3
• A monday.com account with API access (any paid plan includes API access).
• A MONDAY_API_TOKEN environment variable populated with a monday.com API token.

Supporting this Module

This module is maintained by das.gautam at Genero. Bug reports and feature requests are welcome via the issue queue on this project page.

Community Documentation

External documentation, walkthroughs, and demo recordings will be linked here as they're produced. In the meantime, the module's README on git.drupalcode.org documents the install path, the YAML mapping format, and the failure-mode semantics in more detail.