Manage Subitems

Work with subitems (child items) to break down tasks into smaller, manageable pieces.

What are Subitems?

Subitems are child items that live under a parent item. They help you:

  • Break down large tasks into smaller steps
  • Track progress at a more granular level
  • Organize work hierarchically

Create a Subitem

Add a subitem to an existing item:

require "monday_ruby"

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

client = Monday::Client.new

response = client.subitem.create(
  args: {
    parent_item_id: 987654321,  # The parent item ID
    item_name: "Subitem Task"
  }
)

if response.success?
  subitem = response.body.dig("data", "create_subitem")
  puts "✓ Created subitem: #{subitem['name']}"
  puts "  ID: #{subitem['id']}"
  puts "  Created: #{subitem['created_at']}"
else
  puts "✗ Failed to create subitem"
end

Output:

✓ Created subitem: Subitem Task
  ID: 7092811738
  Created: 2024-07-25T04:00:04Z

Create Multiple Subitems

Break down a task into multiple steps:

parent_item_id = 987654321
subtasks = [
  "Design mockups",
  "Get feedback",
  "Revise design",
  "Final approval"
]

created_subitems = []

subtasks.each do |task_name|
  response = client.subitem.create(
    args: {
      parent_item_id: parent_item_id,
      item_name: task_name
    }
  )

  if response.success?
    subitem = response.body.dig("data", "create_subitem")
    created_subitems << subitem
    puts "✓ Created: #{subitem['name']}"
  end

  sleep(0.3)  # Rate limiting
end

puts "\nCreated #{created_subitems.length} subitems"

Output:

✓ Created: Design mockups
✓ Created: Get feedback
✓ Created: Revise design
✓ Created: Final approval

Created 4 subitems

Create Subitem with Column Values

Set column values when creating a subitem:

# Note: Replace column IDs with your board's actual column IDs
response = client.subitem.create(
  args: {
    parent_item_id: 987654321,
    item_name: "Design Phase",
    column_values: {
      status: {  # ⚠️ Your status column ID
        label: "Working on it"
      },
      date4: {  # ⚠️ Your date column ID
        date: "2024-12-15"
      }
    }
  }
)

if response.success?
  subitem = response.body.dig("data", "create_subitem")
  puts "✓ Subitem created with column values"
end
Finding Column IDs

Subitems live on a subitems board. Query that board’s columns to get the correct column IDs. See Create Items guide for details.

Query Subitems

Retrieve subitems for a parent item:

response = client.subitem.query(
  args: { ids: [987654321] }  # Parent item ID
)

if response.success?
  items = response.body.dig("data", "items")
  subitems = items.first&.dig("subitems") || []

  puts "Found #{subitems.length} subitems:"
  subitems.each do |subitem|
    puts "  • #{subitem['name']} (ID: #{subitem['id']})"
  end
end

Query with Custom Fields

Get additional details about subitems:

response = client.subitem.query(
  args: { ids: [987654321] },
  select: [
    "id",
    "name",
    "created_at",
    "state",
    {
      column_values: ["id", "text", "type"]
    }
  ]
)

if response.success?
  items = response.body.dig("data", "items")
  subitems = items.first&.dig("subitems") || []

  subitems.each do |subitem|
    puts "\n#{subitem['name']}"
    puts "  ID: #{subitem['id']}"
    puts "  State: #{subitem['state']}"
    puts "  Created: #{subitem['created_at']}"

    if subitem["column_values"]
      puts "  Column Values:"
      subitem["column_values"].each do |col|
        next if col["text"].nil? || col["text"].empty?
        puts "    • #{col['id']}: #{col['text']}"
      end
    end
  end
end

Query Multiple Parent Items

Get subitems for multiple items at once:

parent_item_ids = [987654321, 987654322, 987654323]

response = client.subitem.query(
  args: { ids: parent_item_ids },
  select: ["id", "name", "created_at"]
)

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

  items.each do |item|
    subitems = item["subitems"] || []
    puts "\nParent: Item #{item['id']}"
    puts "  Subitems: #{subitems.length}"

    subitems.each do |subitem|
      puts "    • #{subitem['name']}"
    end
  end
end

Update Subitem Values

Subitems are regular items, so use the item/column update methods:

# Update a subitem's column value
subitem_id = 7092811738

response = client.column.change_value(
  args: {
    board_id: 1234567890,  # The subitems board ID
    item_id: subitem_id,
    column_id: "status",  # ⚠️ Your status column ID
    value: JSON.generate({ label: "Done" })
  }
)

if response.success?
  puts "✓ Subitem updated"
end

Get Subitems Board ID

Find the board ID for subitems:

# Query the parent item to get subitems board reference
response = client.item.query(
  args: { ids: [987654321] },
  select: [
    "id",
    "name",
    {
      board: ["id", "name"]
    }
  ]
)

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

  puts "Item: #{item['name']}"
  puts "Board: #{board['name']} (ID: #{board['id']})"
  puts "\nSubitems will be on a related subitems board"
end

Delete Subitems

Subitems are items, so use the item delete method:

subitem_id = 7092811738

response = client.item.delete(subitem_id)

if response.success?
  puts "✓ Subitem deleted"
end

Complete Example

Create and manage a project with subitems:

require "monday_ruby"
require "dotenv/load"

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

client = Monday::Client.new

# First, create a parent item
parent_response = client.item.create(
  args: {
    board_id: 1234567890,
    item_name: "Website Redesign Project"
  }
)

parent_item = parent_response.body.dig("data", "create_item")
puts "✓ Created parent item: #{parent_item['name']}"

# Define project phases as subitems
phases = [
  "Research & Planning",
  "Design Mockups",
  "Development",
  "Testing & QA",
  "Launch"
]

# Create subitems for each phase
puts "\nCreating project phases..."
phases.each do |phase_name|
  response = client.subitem.create(
    args: {
      parent_item_id: parent_item["id"],
      item_name: phase_name
    },
    select: ["id", "name", "created_at"]
  )

  if response.success?
    subitem = response.body.dig("data", "create_subitem")
    puts "  ✓ #{subitem['name']}"
  end

  sleep(0.3)
end

# Query all subitems
puts "\nQuerying created subitems..."
query_response = client.subitem.query(
  args: { ids: [parent_item["id"]] },
  select: ["id", "name"]
)

if query_response.success?
  items = query_response.body.dig("data", "items")
  subitems = items.first&.dig("subitems") || []

  puts "\n" + "=" * 50
  puts "Project: #{parent_item['name']}"
  puts "Phases: #{subitems.length}"
  puts "\nSubitems:"
  subitems.each_with_index do |subitem, index|
    puts "  #{index + 1}. #{subitem['name']} (ID: #{subitem['id']})"
  end
  puts "=" * 50
end

Output:

✓ Created parent item: Website Redesign Project

Creating project phases...
  ✓ Research & Planning
  ✓ Design Mockups
  ✓ Development
  ✓ Testing & QA
  ✓ Launch

Querying created subitems...

==================================================
Project: Website Redesign Project
Phases: 5

Subitems:
  1. Research & Planning (ID: 7092811740)
  2. Design Mockups (ID: 7092811741)
  3. Development (ID: 7092811742)
  4. Testing & QA (ID: 7092811743)
  5. Launch (ID: 7092811744)
==================================================

Count Subitems

Count how many subitems an item has:

response = client.subitem.query(
  args: { ids: [987654321] },
  select: ["id", "name"]
)

if response.success?
  items = response.body.dig("data", "items")
  subitems = items.first&.dig("subitems") || []

  puts "This item has #{subitems.length} subitems"
end

Filter Parent Items by Subitem Count

Find items with or without subitems:

# Query multiple items
response = client.item.query(
  args: { ids: [987654321, 987654322, 987654323] },
  select: [
    "id",
    "name",
    {
      subitems: ["id"]
    }
  ]
)

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

  items_with_subitems = items.select do |item|
    subitems = item["subitems"] || []
    subitems.length > 0
  end

  puts "Items with subitems: #{items_with_subitems.length}"
  items_with_subitems.each do |item|
    subitem_count = item["subitems"].length
    puts "  • #{item['name']} (#{subitem_count} subitems)"
  end
end

Error Handling

Handle common subitem errors:

def create_subitem_safe(client, parent_item_id, subitem_name)
  response = client.subitem.create(
    args: {
      parent_item_id: parent_item_id,
      item_name: subitem_name
    }
  )

  if response.success?
    subitem = response.body.dig("data", "create_subitem")
    puts "✓ Created: #{subitem['name']}"
    subitem["id"]
  else
    puts "✗ Failed to create subitem"
    nil
  end
rescue Monday::AuthorizationError
  puts "✗ Invalid API token"
  nil
rescue Monday::Error => e
  puts "✗ API error: #{e.message}"
  nil
end

# Usage
subitem_id = create_subitem_safe(client, 987654321, "New Subitem")

Best Practices

Use Subitems For

  • Breaking down large tasks into steps
  • Tracking sub-components of a feature
  • Managing checklist items
  • Organizing hierarchical work

Avoid Subitems For

  • Deep nesting (subitems can’t have their own subitems)
  • Unrelated tasks (use groups or separate items instead)
  • Cross-board relationships (use connect boards column)
Edit this page
Last updated
Built with Docyard