Update Items

Modify item properties and column values in your boards.

Finding Column IDs

Column IDs are Board-Specific

Before updating column values, you must find your board's actual column IDs. Column IDs like status, text, or date in these examples are placeholders - replace them with your board's real column IDs.

Query your board to get column IDs:

ruby

response = client.board.query(
  args: { ids: [1234567890] },  # Replace with your board ID
  select: [
    "id",
    "name",
    {
      columns: ["id", "title", "type"]
    }
  ]
)

if response.success?
  board = response.body.dig("data", "boards", 0)

  puts "Columns for board '#{board['name']}':"
  board["columns"].each do |column|
    puts "  • #{column['title']}: '#{column['id']}' (#{column['type']})"
  end
end

Example output:

Columns for board 'Marketing Campaigns':
  • Name: 'name' (name)
  • Status: 'status' (color)
  • Owner: 'people' (people)
  • Due Date: 'date4' (date)
  • Priority: 'status_1' (color)
  • Text: 'text' (text)

Use these exact column IDs (e.g., date4, status_1) in your update calls, not the column titles.

Update Single Column Value

Update one column value at a time:

ruby

require "monday_ruby"

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
end

client = Monday::Client.new

# ⚠️ Replace 'status' with your actual column ID from the query above
response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "status",  # Your status column ID (e.g., 'status', 'status_1', etc.)
    value: JSON.generate({ label: "Done" })
  }
)

if response.success?
  item = response.body.dig("data", "change_column_value")
  puts "✓ Updated: #{item['name']}"
else
  puts "✗ Failed to update item"
end

Output:

✓ Updated: Marketing Campaign

Update Simple Column Values

For simple column types, use change_simple_value:

Text Column

ruby

# ⚠️ Replace 'text' with your actual text column ID
response = client.column.change_simple_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "text",  # Your text column ID
    value: "Updated text content"
  }
)

if response.success?
  item = response.body.dig("data", "change_simple_column_value")
  puts "Updated: #{item['name']}"
end

Number Column

ruby

response = client.column.change_simple_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "numbers",
    value: "42"
  }
)

Simple vs Complex

Use change_simple_value for text, numbers, and simple types. Use change_value for status, people, date, and other complex column types.

Update Multiple Columns

Update several column values at once:

ruby

require "json"

# ⚠️ Replace all column IDs with your board's actual column IDs
column_values = {
  status: { label: "Working on it" },  # Your status column ID
  text: "High Priority",  # Your text column ID
  numbers: 85  # Your numbers column ID
}

response = client.column.change_multiple_values(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_values: JSON.generate(column_values)
  }
)

if response.success?
  item = response.body.dig("data", "change_multiple_column_values")
  puts "✓ Updated multiple columns for: #{item['name']}"
end

Update Status Column

Change item status:

ruby

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "status",
    value: JSON.generate({ label: "Done" })
  }
)

if response.success?
  puts "✓ Status updated to 'Done'"
end

Using Status Index

If you know the status label index:

ruby

value = JSON.generate({ index: 1 })

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "status",
    value: value
  }
)

Update Date Column

Set dates with or without time:

Date Only

ruby

value = JSON.generate({ date: "2024-12-31" })

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "date",
    value: value
  }
)

Date and Time

ruby

value = JSON.generate({
  date: "2024-12-31",
  time: "14:30:00"
})

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "date",
    value: value
  }
)

Clear Date

ruby

value = JSON.generate({ date: nil, time: nil })

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "date",
    value: value
  }
)

Update People Column

Assign people to an item:

Single Person

ruby

value = JSON.generate({
  personsAndTeams: [
    { id: 12345678, kind: "person" }
  ]
})

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "people",
    value: value
  }
)

Multiple People

ruby

value = JSON.generate({
  personsAndTeams: [
    { id: 12345678, kind: "person" },
    { id: 87654321, kind: "person" }
  ]
})

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "people",
    value: value
  }
)

Include Teams

ruby

value = JSON.generate({
  personsAndTeams: [
    { id: 12345678, kind: "person" },
    { id: 99999999, kind: "team" }
  ]
})

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "people",
    value: value
  }
)

Update Timeline Column

Set timeline start and end dates:

ruby

value = JSON.generate({
  from: "2024-01-01",
  to: "2024-03-31"
})

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "timeline",
    value: value
  }
)

Set dropdown selection:

ruby

value = JSON.generate({ labels: [123] })  # Label ID

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "dropdown",
    value: value
  }
)

Update Link Column

Add URL links:

ruby

value = JSON.generate({
  url: "https://example.com",
  text: "Example Website"
})

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "link",
    value: value
  }
)

Bulk Update Items

Update multiple items efficiently:

ruby

def bulk_update_status(client, board_id, item_ids, status_label)
  updated_items = []

  item_ids.each do |item_id|
    response = client.column.change_value(
      args: {
        board_id: board_id,
        item_id: item_id,
        column_id: "status",
        value: JSON.generate({ label: status_label })
      }
    )

    if response.success?
      item = response.body.dig("data", "change_column_value")
      updated_items << item
      puts "✓ Updated: #{item['name']}"
    else
      puts "✗ Failed to update item #{item_id}"
    end

    # Rate limiting: pause between requests
    sleep(0.3)
  end

  updated_items
end

# Usage
item_ids = [987654321, 987654322, 987654323]
items = bulk_update_status(client, 1234567890, item_ids, "Done")

puts "\n✓ Updated #{items.length} items"

Update with Create or Get

Update existing or create new column value:

ruby

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "status",
    value: JSON.generate({ label: "Custom Status" }),
    create_labels_if_missing: true
  }
)

if response.success?
  puts "✓ Status updated (label created if needed)"
end

Customize Response Fields

Get detailed information about the updated item:

ruby

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "status",
    value: JSON.generate({ label: "Done" })
  },
  select: [
    "id",
    "name",
    "state",
    {
      column_values: ["id", "text", "type"]
    }
  ]
)

if response.success?
  item = response.body.dig("data", "change_column_value")

  puts "Updated: #{item['name']}"
  puts "Column Values:"

  item["column_values"].each do |col_val|
    next if col_val["text"].nil? || col_val["text"].empty?
    puts "  • #{col_val['id']}: #{col_val['text']}"
  end
end

Clear Column Value

Remove a column's value:

ruby

response = client.column.change_value(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_id: "status",
    value: JSON.generate({})
  }
)

if response.success?
  puts "✓ Column value cleared"
end

Error Handling

Handle common update errors:

ruby

def update_column_safe(client, board_id, item_id, column_id, value)
  response = client.column.change_value(
    args: {
      board_id: board_id,
      item_id: item_id,
      column_id: column_id,
      value: value
    }
  )

  if response.success?
    item = response.body.dig("data", "change_column_value")
    puts "✓ Updated: #{item['name']}"
    true
  else
    puts "✗ Failed to update column"
    puts "  Status: #{response.status}"

    if response.body["errors"]
      response.body["errors"].each do |error|
        puts "  Error: #{error['message']}"
      end
    end

    false
  end
rescue Monday::AuthorizationError
  puts "✗ Invalid API token"
  false
rescue Monday::InvalidRequestError => e
  puts "✗ Invalid request: #{e.message}"
  false
rescue Monday::Error => e
  puts "✗ API error: #{e.message}"
  false
end

# Usage
value = JSON.generate({ label: "Done" })
success = update_column_safe(
  client,
  1234567890,
  987654321,
  "status",
  value
)

Complete Example

Update multiple columns with full error handling:

ruby

require "monday_ruby"
require "dotenv/load"
require "json"

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
end

client = Monday::Client.new

# IMPORTANT: First, get your board's column IDs:
# See "Finding Column IDs" section at the top of this guide

# Update multiple columns at once
# ⚠️ Replace all column IDs with your board's actual column IDs
column_values = {
  status: { label: "Working on it" },  # Your status column ID
  text: "Updated task description",  # Your text column ID
  date4: { date: "2024-12-31", time: "17:00:00" },  # Your date column ID
  people: {  # Your people column ID
    personsAndTeams: [
      { id: 12345678, kind: "person" }  # Replace with actual user ID
    ]
  }
}

response = client.column.change_multiple_values(
  args: {
    board_id: 1234567890,
    item_id: 987654321,
    column_values: JSON.generate(column_values)
  },
  select: [
    "id",
    "name",
    "state",
    {
      column_values: ["id", "text", "type", "value"]
    }
  ]
)

if response.success?
  item = response.body.dig("data", "change_multiple_column_values")

  puts "\n✓ Item Updated Successfully\n"
  puts "#{'=' * 50}"
  puts "Name: #{item['name']}"
  puts "ID: #{item['id']}"
  puts "State: #{item['state']}"

  puts "\nUpdated Column Values:"
  item["column_values"].each do |col_val|
    next if col_val["text"].nil? || col_val["text"].empty?
    puts "  • #{col_val['id']}: #{col_val['text']} (#{col_val['type']})"
  end

  puts "#{'=' * 50}"
else
  puts "\n✗ Failed to update item"
  puts "Status code: #{response.status}"

  if response.body["error_message"]
    puts "Error: #{response.body['error_message']}"
  end
end

Update Based on Current Value

Read current value before updating:

ruby

# First, get the current item
query_response = client.item.query(
  args: { ids: [987654321] },
  select: [
    "id",
    "name",
    {
      column_values: ["id", "text", "value"]
    }
  ]
)

if query_response.success?
  item = query_response.body.dig("data", "items", 0)
  current_status = item["column_values"].find { |cv| cv["id"] == "status" }

  # Update based on current value
  new_status = if current_status&.dig("text") == "Working on it"
                 "Done"
               else
                 "Working on it"
               end

  # Update the status
  update_response = client.column.change_value(
    args: {
      board_id: 1234567890,
      item_id: 987654321,
      column_id: "status",
      value: JSON.generate({ label: new_status })
    }
  )

  if update_response.success?
    puts "✓ Status toggled to: #{new_status}"
  end
end

Conditional Updates

Update only if condition is met:

ruby

def update_if_status(client, board_id, item_id, current_status, new_column_values)
  # Query current item
  response = client.item.query(
    args: { ids: [item_id] },
    select: [
      "id",
      {
        column_values: ["id", "text"]
      }
    ]
  )

  return false unless response.success?

  item = response.body.dig("data", "items", 0)
  status = item["column_values"].find { |cv| cv["id"] == "status" }

  # Check condition
  return false unless status&.dig("text") == current_status

  # Perform update
  update_response = client.column.change_multiple_values(
    args: {
      board_id: board_id,
      item_id: item_id,
      column_values: JSON.generate(new_column_values)
    }
  )

  update_response.success?
end

# Usage
updated = update_if_status(
  client,
  1234567890,
  987654321,
  "Working on it",
  { status: { label: "Done" }, text: "Completed successfully" }
)

puts updated ? "✓ Updated" : "✗ Condition not met"

Update Items ​

Finding Column IDs ​

Update Single Column Value ​

Update Simple Column Values ​

Text Column ​

Number Column ​

Update Multiple Columns ​

Update Status Column ​

Using Status Index ​

Update Date Column ​

Date Only ​

Date and Time ​

Clear Date ​

Update People Column ​

Single Person ​

Multiple People ​

Include Teams ​

Update Timeline Column ​

Update Dropdown Column ​

Update Link Column ​

Bulk Update Items ​

Update with Create or Get ​

Customize Response Fields ​

Clear Column Value ​

Error Handling ​

Complete Example ​

Update Based on Current Value ​

Conditional Updates ​

Next Steps ​

Update Items

Finding Column IDs

Update Single Column Value

Update Simple Column Values

Text Column

Number Column

Update Multiple Columns

Update Status Column

Using Status Index

Update Date Column

Date Only

Date and Time

Clear Date

Update People Column

Single Person

Multiple People

Include Teams

Update Timeline Column

Update Dropdown Column

Update Link Column

Bulk Update Items

Update with Create or Get

Customize Response Fields

Clear Column Value

Error Handling

Complete Example

Update Based on Current Value

Conditional Updates

Next Steps