reshuffle-monday-connector

Code | npm | Code sample

npm install reshuffle-monday-connector

Reshuffle Monday Connector

This package contains a Reshuffle connector for connecting to Monday.

A full documentation of Monday's API is available here.

Table of Contents

Configuration Options

Connector Events

Listening to Monday events

Connector Actions

Get Board - Retrieve a board details object from Monday

Get Board by name - Lookup a board id from its name.

Get Board Items - Retrieve all items for a specific board.

Get Group - Retrieve a group details object from Monday

Get Item - Retrieve an item details object from Monday

Create Item - Create a new item in a board

Update Item - Update an item's name in a board

Update Column Values - Update an item's column values

Query - Run a GraphQL query

SDK - Retrieve a full Monday sdk object

Configuration Options

To work with this connector, you'll need to get a token from here :

1. Log into your monday.com account.
2. Click on your avatar (picture icon) in the bottom left corner.
3. Select Admin from the resulting menu (this requires you to have admin permissions).
4. Go to the API section.
5. Generate a “API v2 Token”
6. Copy your token.

interface MondayConnectorConfigOptions {
  token: string
  baseURL?: string
  webhookPath?: string
}

The token is the only configuration value required if you just want to send data to Monday. If, however, you need to listen to events happening on your boards (e.g. creation or update of a task) - you'll need to provide the baseURL and optionally the webhookPath values as well.

baseURL is the URL where the running Reshuffle instance can be found (e.g. https://my-reshuffle.com)

webhookPath is an optional path to append to baseURL to create a full webhook path.

For example - providing the above baseURL and webhookPath='/mondayhook will result in a complete webhook path of https://my-reshuffle.com/mondayhook.

If you do not provide a webhookPath, Reshuffle will use the default webhook path for the connector which is /webhooks/monday.

You will need to register this webhook with Monday. See instructions.

Connector events

Listening to Monday events

To listen to events happening in Monday, create an event handler with the boardId, event type optional column id:

interface MondayConnectorEventOptions {
  boardId: string | number
  type:
    | 'IncomingNotification'
    | 'ChangeColumnValue'
    | 'ChangeSpecificColumnValue'
    | 'CreateItem'
    | 'CreateUpdate'
    | 'UpdateName' 
  columnId?: string // for type === ChangeSpecificColumnValue
}

Events require that an integration webhook be configured in Monday. The connector does not configure integrations automatically becuase at the moment it has no way of tracking which integrations are already configured in Monday. You can either configure an integration through the Monday UI or call createEventWebhook.

Connector actions

getBoard

Obtain details of a Monday board (or a list of boards). Use the Monday Board id as the parameter. _Note: To obtain the board_id, visit your board in the browser and copy the id from the last part of the URL e.g. if your board's url is https://my-company.monday.com/boards/123456789 - then your board id is 123456789

const boardId = '123456789'
const board = await connector.getBoard(boardId)

getBoardIdByName

Find a board Id by its name

const boardId = await connector.getBoardIdByName('My board')

getBoardItems

Get all the items in a board. The returned object has a name field with the name of the board, and an items object, with item data accessible by item Ids. Data for each item is an object including the item's name and values for each column.

const boardItems = await connector.getBoardItems(boardId)

getColumn

Query a column or a list of columns of a board by the board's Id

const column = await connector.getColumn(boardId)

getGroup

Query a group or a list of groups Monday uses groups to group items together inside a board.

const group = await connector.getGroup(groupId)

getItem

Query an item or a list of items

const item = await connector.getItem(itemId)

createItem

Creates a new item and adds it to the specified board.

| Parameter | Type | Required | | ------------- | ------ | -------- | | board_id | Int | Yes | | item_name | String | Yes | | column_values | JSON | No | | group_id | String | No |

Example of column_values

const column_values = JSON.stringify({
  [column_id]: 'example data',
  [column_id2]: 'another example',
})

const item = await connector.createItem(boardId, item_name, column_values, groupId)

updateItem

Update an item's name

const item = await connector.updateItem(boardId, groupId, 'Updated Item Name')

updateColumnValues

Update an specific item in a specific board with new values. The updaters object should include one update function for each column that needs to be updated, with property names being the titles for these columns. Each function receives the old value and should return the new value for that column.

await updateColumnValues(myBoardId, myItemId, {
  Name: (name: string) => name.toUpperCase,
  Phone: (phone: string) => phone.startsWith('+') ? phone : `+${phone}`,
})

createWebhook

Create a webhook. Note - using when you create an on handler the event will be created for you if you dont pass a webhookId

const webhookId = await connector.createWebhook(
  BOARD_ID,
  'https://example.com/monday-webhook',
  'create_item',
)

createEventWebhook

Create a webhook for an event. This action requires that the connector be configured with a baseURL.

const webhookId = await connector.createEventWebhook(
  BOARD_ID,
  'ChangeColumnValue'
)

deleteWebhook

Delete a webhook

const deletedWebhook = await connector.deleteWebhook(WEBHOOK_ID)

query

Run any GraphQL query

const res = await connector.query('query { users { name } }')

sdk

Returns an object providing full access to the Monday GraphQL API

const sdk = await connector.sdk()