Robert Resch 53043f4ee1
Add todo.remove_completed_items service call (#29929)
* Add todo.remove_completed_items service call

* Update source/_integrations/todo.markdown

Co-authored-by: Fletcher <fletcher.boyd@artifactory.org.au>

* Tiny tweak

---------

Co-authored-by: Fletcher <fletcher.boyd@artifactory.org.au>
Co-authored-by: Franck Nijhof <git@frenck.dev>
2023-11-20 22:41:29 +01:00

4.2 KiB

title, description, ha_domain, ha_release, ha_category, ha_quality_scale, ha_codeowners, ha_integration_type
title description ha_domain ha_release ha_category ha_quality_scale ha_codeowners ha_integration_type
To-do Instructions on how to use To-do Lists within Home Assistant. todo 2023.11
To-do List
internal
@home-assistant/core
entity

The To-do List integration provides todo list entities, allowing other integrations to integrate To-do Lists into Home Assistant. To-do lists are shown on the To-do list dashboard for tracking items and whether or not they have been completed.

{% include integrations/building_block_integration.md %}

Viewing and managing To-do lists

Each To-do list is represented as its own entity in Home Assistant and can be viewed and managed on a to-do list dashboard. You can find the to-do list dashboard in the main sidebar of your Home Assistant instance.

The state of a To-do List entity

The state of a To-do List entity is a number, which represents the number of incomplete items in the list.

Services

Some To-do List integrations allow Home Assistant to manage the To-do Items in the list. The services provided by some To-do List entities are described below or you can read more about Service Calls.

Service todo.get_items

Get to-do items from a to-do list. A to-do list target is selected with a target selector. The data payload supports the following fields:

Service data attribute Optional Description Example
status yes Only return to-do items with this status. needs_action, completed

This is a full example that returns all to-do items that have not been completed:

service: todo.get_items
target:
  entity_id: todo.personal_tasks
data:
  status:
    - needs_action

Service todo.add_item

Add a new To-do Item. A To-do list target is selected with a Target Selector and the data payload supports the following fields:

Service data attribute Optional Description Example
item no the name of the to-do Item. Submit income tax return

This is a full example of service call in YAML:

service: todo.add_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit Income Tax Return"

Service todo.update_item

Update a To-do Item. A To-do list target is selected with a Target Selector and the data payload supports the following fields:

Service data attribute Optional Description Example
item no The name of the to-do Item to update. Submit income tax return
rename yes The new name of the to-do Item. Something else
status yes The overall status of the To-do Item. needs_action or completed

At least one of rename or status is required. This is a full example of a service call that updates the status and the name of a to-do Item.

service: todo.update_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit income tax return"
  rename: "Something else"
  status: "completed"

Service todo.remove_item

Removing a To-do Item. A to-do list target is selected with a Target Selector, and the data payload supports the following fields:

Service data attribute Optional Description Example
item no The name of the to-do item. Submit income tax return

This is a full example of a service call that deletes a to-do Item with the specified name.

service: todo.delete_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit income tax return"

Service todo.remove_completed_items

Removes all completed to-do items. A to-do list target is selected with a Target Selector.

This is a full example of a service call that deletes all completed to-do items.

service: todo.remove_completed_items
target:
  entity_id: todo.personal_tasks