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:

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:

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

# ⚠️ 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

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:

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:

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:

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

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

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

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

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

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

# 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:

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"

Edit this page

Last updated 5 hours ago

Was this page helpful?