Change Column Metadata

Update column settings, titles, and configuration.

Change Column Title

Rename a column:

require "monday_ruby"

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

client = Monday::Client.new

response = client.column.change_title(
  args: {
    board_id: 1234567890,
    column_id: "text_1",  # The column's ID
    title: "Project Notes"  # New title
  }
)

if response.success?
  column = response.body.dig("data", "change_column_title")
  puts "✓ Column renamed to: #{column['title']}"
else
  puts "✗ Failed to rename column"
end

Output:

✓ Column renamed to: Project Notes

Change Column Metadata

Update column settings and configuration:

require "json"

# Update column description
response = client.column.change_metadata(
  args: {
    board_id: 1234567890,
    column_id: "status",
    column_property: "description",
    value: "Current task status (Not Started, In Progress, Done)"
  }
)

if response.success?
  column = response.body.dig("data", "change_column_metadata")
  puts "✓ Column metadata updated"
end

Update Column Description

Add or update a column's description:

def update_column_description(client, board_id, column_id, description)
  response = client.column.change_metadata(
    args: {
      board_id: board_id,
      column_id: column_id,
      column_property: "description",
      value: description
    }
  )

  if response.success?
    column = response.body.dig("data", "change_column_metadata")
    puts "✓ Description updated for: #{column['title']}"
    true
  else
    puts "✗ Failed to update description"
    false
  end
end

# Usage
update_column_description(
  client,
  1234567890,
  "status",
  "Track task completion status"
)

Update Status Column Labels

Configure status (color) column labels:

# First, get current column settings
query_response = client.column.query(
  args: { ids: [1234567890] },
  select: ["id", "title", "settings_str"]
)

boards = query_response.body.dig("data", "boards")
columns = boards.first&.dig("columns") || []
status_column = columns.find { |col| col["id"] == "status" }

# Parse current settings
current_settings = JSON.parse(status_column["settings_str"])

# Modify labels
current_settings["labels"] = {
  "0" => "Not Started",
  "1" => "In Progress",
  "2" => "Review",
  "3" => "Done",
  "4" => "Archived"
}

# Update column metadata
response = client.column.change_metadata(
  args: {
    board_id: 1234567890,
    column_id: "status",
    column_property: "labels",
    value: JSON.generate(current_settings["labels"])
  }
)

if response.success?
  puts "✓ Status labels updated"
end

Column Settings

Different column types have different metadata properties. Use column.query with settings_str to see available options for each column type.

Rename Multiple Columns

Update titles for several columns:

def rename_columns(client, board_id, renames)
  updated_count = 0

  renames.each do |column_id, new_title|
    response = client.column.change_title(
      args: {
        board_id: board_id,
        column_id: column_id,
        title: new_title
      }
    )

    if response.success?
      column = response.body.dig("data", "change_column_title")
      updated_count += 1
      puts "✓ Renamed: #{column['title']}"
    else
      puts "✗ Failed to rename: #{column_id}"
    end

    sleep(0.3)  # Rate limiting
  end

  updated_count
end

# Usage
renames = {
  "text" => "Task Description",
  "numbers" => "Estimated Hours",
  "date4" => "Target Completion"
}

count = rename_columns(client, 1234567890, renames)
puts "\n✓ Renamed #{count} columns"

Update Dropdown Options

Modify dropdown column options:

require "json"

# Define new dropdown options
dropdown_labels = {
  "1" => "High Priority",
  "2" => "Medium Priority",
  "3" => "Low Priority",
  "4" => "No Priority"
}

response = client.column.change_metadata(
  args: {
    board_id: 1234567890,
    column_id: "dropdown",
    column_property: "labels",
    value: JSON.generate(dropdown_labels)
  }
)

if response.success?
  puts "✓ Dropdown options updated"
end

Add Column Descriptions in Bulk

Add helpful descriptions to all columns:

def add_column_descriptions(client, board_id, descriptions)
  updated_count = 0

  descriptions.each do |column_id, description|
    response = client.column.change_metadata(
      args: {
        board_id: board_id,
        column_id: column_id,
        column_property: "description",
        value: description
      }
    )

    if response.success?
      updated_count += 1
      puts "✓ Updated: #{column_id}"
    else
      puts "✗ Failed: #{column_id}"
    end

    sleep(0.3)
  end

  updated_count
end

# Usage
descriptions = {
  "status" => "Current status of the task",
  "people" => "Person responsible for this task",
  "date4" => "When this task is due",
  "numbers" => "Estimated budget in USD"
}

count = add_column_descriptions(client, 1234567890, descriptions)
puts "\n✓ Added descriptions to #{count} columns"

Error Handling

Handle metadata update errors:

def change_column_title_safe(client, board_id, column_id, new_title)
  response = client.column.change_title(
    args: {
      board_id: board_id,
      column_id: column_id,
      title: new_title
    }
  )

  if response.success?
    column = response.body.dig("data", "change_column_title")
    puts "✓ Renamed to: #{column['title']}"
    true
  else
    puts "✗ Failed to rename 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
success = change_column_title_safe(
  client,
  1234567890,
  "text",
  "New Column Name"
)

Get Updated Column Info

Retrieve column details after update:

response = client.column.change_title(
  args: {
    board_id: 1234567890,
    column_id: "text",
    title: "Project Description"
  },
  select: [
    "id",
    "title",
    "description",
    "type",
    "settings_str"
  ]
)

if response.success?
  column = response.body.dig("data", "change_column_title")

  puts "Column Updated:"
  puts "  ID: #{column['id']}"
  puts "  Title: #{column['title']}"
  puts "  Type: #{column['type']}"
  puts "  Description: #{column['description']}" if column['description']
end

Complete Example

Set up complete column metadata:

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

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

client = Monday::Client.new

board_id = 1234567890

puts "\n📝 Configuring Board Columns\n#{'=' * 50}\n"

# 1. Rename columns
column_renames = {
  "text" => "Task Description",
  "numbers" => "Budget (USD)",
  "status" => "Task Status"
}

puts "Renaming columns..."
column_renames.each do |column_id, new_title|
  response = client.column.change_title(
    args: {
      board_id: board_id,
      column_id: column_id,
      title: new_title
    }
  )

  if response.success?
    puts "  ✓ #{column_id} → #{new_title}"
  end

  sleep(0.3)
end

# 2. Add descriptions
column_descriptions = {
  "text" => "Detailed description of the task and requirements",
  "numbers" => "Estimated budget in US Dollars",
  "status" => "Current completion status of the task",
  "people" => "Team member assigned to this task",
  "date4" => "Target completion date for this task"
}

puts "\nAdding descriptions..."
column_descriptions.each do |column_id, description|
  response = client.column.change_metadata(
    args: {
      board_id: board_id,
      column_id: column_id,
      column_property: "description",
      value: description
    }
  )

  if response.success?
    puts "  ✓ #{column_id}"
  end

  sleep(0.3)
end

# 3. Configure status labels
puts "\nConfiguring status labels..."
status_labels = {
  "0" => "Not Started",
  "1" => "Planning",
  "2" => "In Progress",
  "3" => "Review",
  "4" => "Done"
}

response = client.column.change_metadata(
  args: {
    board_id: board_id,
    column_id: "status",
    column_property: "labels",
    value: JSON.generate(status_labels)
  }
)

if response.success?
  puts "  ✓ Status labels configured"
end

puts "\n#{'=' * 50}"
puts "✓ Column configuration complete"
puts "#{'=' * 50}"

Output:

📝 Configuring Board Columns
==================================================

Renaming columns...
  ✓ text → Task Description
  ✓ numbers → Budget (USD)
  ✓ status → Task Status

Adding descriptions...
  ✓ text
  ✓ numbers
  ✓ status
  ✓ people
  ✓ date4

Configuring status labels...
  ✓ Status labels configured

==================================================
✓ Column configuration complete
==================================================

Validate Column Title

Check for valid column titles before updating:

def valid_column_title?(title)
  return false if title.nil? || title.empty?
  return false if title.length > 255

  true
end

new_title = "Updated Column Name"

if valid_column_title?(new_title)
  response = client.column.change_title(
    args: {
      board_id: 1234567890,
      column_id: "text",
      title: new_title
    }
  )
else
  puts "Invalid column title"
end

Next Steps

• Create columns
• Update column values
• Query column values
• Query boards