Monday.com v2

Provides integration with monday.com, a work management platform where teams organize projects, tasks and processes on boards. Each board holds items (rows) and columns such as status, owner and due date, plus updates, files, users, workspaces and docs.

The Node reads and changes monday.com data from a Workflow through the monday.com GraphQL API, using templates generated from your account's schema. Use it to read boards and items into other systems, to create or update items and column values from incoming data, and to attach files to items and updates.

Revision History

0.0.0.3 - Initial release.

Connection

The Connection holds the API token, the optional API version and the request timeout. It also stores the GraphQL schema that templates and document validation use.

Setup Notes

1. In monday.com, open your avatar menu, select Developers → My access tokens, and then copy your personal API token. The token has the same access as your monday.com user.
2. Create the Connection, paste the token into ApiToken, and test the Connection. The test reads your own user profile.
3. Run Acquire Metadata on the Connection. Query and Mutate and their templates need the cached schema. Run it again after you change ApiVersion, or when monday.com adds fields you want to use.
4. If you use an app access token instead of a personal token, grant the scopes your operations need, for example boards:read, boards:write and updates:write. A missing scope fails with missingRequiredPermissions.

Free monday.com accounts are limited to 1,000 API calls a day.

This Node runs on Cloud Runtimes.

Methods

The Node exposes one Method for GraphQL queries, one for GraphQL mutations, and one for file uploads. Query and Mutate templates are generated from the cached schema, one per monday.com root field, except deprecated fields.

Query

Runs a GraphQL query document that selects exactly one root field and returns one row per item. Paging is automatic.

• List fields with page and limit, such as boards, items, users and updates, are read 100 rows at a time until a page returns fewer rows.
• To read a board's items, select exactly one board, for example boards(ids: [123]) { items_page { items { id name } } }. A document that reads items_page for any other number of boards is rejected. Each item becomes a row, and board fields are not included. items_page and items_page_by_column_values are read 500 items at a time, following monday.com's cursor.
• An empty result returns no rows and is not an error.
• The document must contain one query operation and is validated against the cached schema before any request is sent.
• The first page is read before the step completes, so an invalid document, an authentication failure or a monday.com error on the first page fails the step. A failure on a later page fails the step after the rows already returned. The Node also stops with an error after 10,000 pages, or if monday.com returns the same cursor twice.

Mutate

Runs a GraphQL mutation document that selects exactly one root field, once for each Items row.

• A monday.com error for one row, such as an invalid board ID or column value, produces a failed row, and later rows still run. The Message uses the form <code>: <message>, for example InvalidBoardIdException: The board does not exist. Please check your board ID and try again.
• A server error or rate limiting that persists after retries also produces a failed row, and later rows still run. A row with an invalid comma-separated list value produces a failed row without being sent.
• The first row runs before the step completes, so a timeout or network failure on it fails the step. From the second row on, a timeout or network failure produces a failed row instead; because the change may or may not have been applied, check the item before retrying it.
• An authentication failure, or reaching the monday.com daily call limit, stops the output.
• An empty Items input returns no rows and sends no requests.
• Mutations that take a file, such as add_file_to_column and add_file_to_update, are not available here; use UploadFile.

UploadFile

Uploads one file to an item's file column or to an update.

url requires monday.com access to the board. public_url is valid for one hour.

If monday.com rejects the upload, the Node returns a failed row with monday.com's errors. Missing Options values, an invalid OperationId, an authentication failure, the daily call limit, a timeout or a network failure fail the step instead. Rate-limited uploads are retried only when the Content stream can be read again from the start.

Usage Notes

• Lists of values are comma-separated text in templates, inputs and outputs. Wrap a value that contains a comma or quote in double quotes, and double any quotes inside it. Spaces are kept as entered. An empty value is an empty list, and "" is a list holding one empty value. Number and Boolean values must parse exactly, and Booleans must be lowercase true or false. Lists of objects stay as arrays.
• Templates remove paging arguments and select id and name on the returned row type where it has them. Templates select only the first fields of each type; edit the Query document to select others.
• Templates leave out nested paged lists, such as a board's updates_page, because the Node does not page lists inside a row. Select the plain list instead, for example updates, which returns monday.com's first page.
• The schema marks ids on the items field as optional, but monday.com requires it. Set ids in Variables, or read a board's items through boards and items_page.
• monday.com rate limits apply. Rate-limited and locked requests are retried up to three times, waiting as monday.com asks for up to 60 seconds each time, or 1 second when monday.com gives no wait time. The daily call limit is not retried.
• An ID in boards(ids:) that is not a number returns no boards rather than an error.
• Some root fields fail on accounts without the related product or permission, for example departments with USER_UNAUTHORIZED. The Node returns monday.com's error.

Known Issues

• Fields that use their own paging objects, such as audit_logs, board_automations, app_subscriptions and notifications, return their first page only. Lists nested inside a row, such as a board's activity_logs, are not paged either.
• An upload to an update that does not exist returns a failed row with DOWNSTREAM_SERVICE_ERROR: Internal server error, rather than a not-found message.
• monday.com does not document how long an items_page cursor stays valid. A very slow downstream Workflow might outlive a cursor, in which case monday.com's error is returned.