The connect boards column links an item on one board to one or more items on another board.

Via the API, the connect boards column supports read, filter, create, update, and clear operations.

Column Type	Implementation Type	Supported Operations
`board_relation`	`BoardRelationValue`	Read: Yes Filter: Yes Update: Yes Clear: Yes

Queries

Connect boards columns can be queried through the column_values field on items queries using an inline fragment on BoardRelationValue.

query {
  items(ids: [1234567890, 9876543210]) {
    column_values {
      ... on BoardRelationValue {
        linked_item_ids
        linked_items {
          id
        }
      }
    }
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `
  query($itemIds: [ID!]) {
    items(ids: $itemIds) {
      column_values {
        ... on BoardRelationValue {
          linked_item_ids
          linked_items {
            id
          }
        }
      }
    }
  }
`;

const variables = { itemIds: [9571351485, 9572374902] };
const response = await mondayApiClient.request(query, variables);

Fields

You can use the following fields to specify what information your BoardRelationValue implementation will return.

Field	Description
column `Column!`	The column the value belongs to.
display_value `String!`	The names of the linked items, separated by commas.
id `ID!`	The column's unique identifier.
linked_item_ids `[ID!]!`	The unique identifiers of linked items.
linked_items `[Item!]!`	The linked items.
text `String`	Always returns `null` for this column. Use `display_value` instead.
type `ColumnType!`	The column's type.
updated_at `Date`	The column's last updated date.
value `JSON`	Always returns `null` for this column. Use `linked_items` and `linked_item_ids` instead.

Filter

You can filter items by connect board values using the items_page object. The connect boards column supports the following operators:

Operators	Compare Values
`any_of`	Linked item IDs to filter by
`not_any_of`	Linked item IDs to exclude
`is_empty`	`[]`
`is_not_empty`	`[]`
`contains_text`	Partial or full item name as a string
`not_contains_text`	Partial or full item name as a string

Example

The following example returns all items connected to an item whose name contains the text "Test":

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "connect_boards"
            compare_value: ["Test"]
            operator: contains_text
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `
  query ($boardId: [ID!], $columnId: ID!, $operator: ItemsQueryRuleOperator!, $compareValue: CompareValue!) {
    boards(ids: $boardId) {
      items_page(
        query_params: {
          rules: [
            { column_id: $columnId, compare_value: $compareValue, operator: $operator }
          ]
        }
      ) {
        items { id name }
      }
    }
  }
`;

const variables = {
  boardId: 9571351437,
  columnId: "connect_boards",
  compareValue: ["Test"],
  operator: "contains_text",
};

const response = await mondayApiClient.request(query, variables);

Mutations

Create

Required scope:boards:write

You can create a connect boards column using the create_column mutation.

mutation {
  create_column(
    board_id: 1234567890
    title: "Related items (Board 9876543210)"
    column_type: board_relation
    defaults: {
      boardIds: [9876543210]
      allowMultipleItems: true
      allowCreateReflectionColumn: true
    }
  ) {
    id
    title
    type
  }
}

Update

🚧
Boards must already be connected before you can connect their items. You can't programmatically connect boards through the API.

You can update a connect boards column using the change_multiple_column_values mutation by passing a JSON string in the column_values argument.

To update the linked items, pass an array of linked item IDs.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"connect_boards\": {\"item_ids\": [\"44332211\", \"11223344\"]}}"
  ) {
    id
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 9571351437,
  itemId: 9571351485,
  columnValues: JSON.stringify({
    board_relation_mksr721a: { item_ids: [9393173469, 9393175000] }
  }),
};

const response = await mondayApiClient.request(query, variables);

Clear

You can clear a connect boards column by passing null or an empty object in the column_values argument.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"connect_boards\": null}"
  ) {
    id
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 9571351437,
  itemId: 9571351485,
  columnValues: JSON.stringify({
    board_relation_mksr721a: null
  }),
};

const response = await mondayApiClient.request(query, variables);