diff --git a/source/_integrations/shopping_list.markdown b/source/_integrations/shopping_list.markdown index f5e2926cc89..ecca2f9b0be 100644 --- a/source/_integrations/shopping_list.markdown +++ b/source/_integrations/shopping_list.markdown @@ -3,6 +3,7 @@ title: Shopping List description: Instructions on how to integrate a Shopping list into Home Assistant using Intent. ha_category: - Intent + - To-do List ha_release: '0.50' ha_config_flow: true ha_quality_scale: internal diff --git a/source/_integrations/todo.markdown b/source/_integrations/todo.markdown new file mode 100644 index 00000000000..e9a37a4184f --- /dev/null +++ b/source/_integrations/todo.markdown @@ -0,0 +1,97 @@ +--- +title: To-do List +description: Instructions on how to use To-do Lists within Home Assistant. +ha_domain: todo +ha_release: 2023.11 +ha_category: + - To-do List +ha_quality_scale: internal +ha_codeowners: + - '@home-assistant/core' +ha_integration_type: 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](/docs/scripts/service-calls/). + +### Service `todo.create_item` + +Add a new To-do Item. A To-do list `target` is selected with a [Target Selector](/docs/blueprint/selectors/#target-selector) and the `data` payload supports the following fields: + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | --------| +| `summary` | no | A short summary or subject for the To-do Item. | Submit Income Tax Return +| `status` | yes | The overall status of the To-do Item. | `needs_action` or `completed` + +This is a full example of service call in YAML: + +```yaml +service: todo.create_item +target: + entity_id: todo.personal_tasks +data: + summary: "Submit Income Tax Return" + status: "needs_action" +``` + +### Service `todo.update_item` + +Update a To-do Item. A To-do list `target` is selected with a [Target Selector](/docs/blueprint/selectors/#target-selector) and the `data` payload supports the following fields: + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | --------| +| `uid` | yes | The Unique identifier of the To-do Item to update. | `bY1PVzZkni1qQQlkanTvBA` +| `summary` | yes | A short summary or subject for the To-do Item. | Submit Income Tax Return +| `status` | yes | The overall status of the To-do Item. | `needs_action` or `completed` + +To-do Items can be identified using either a `uid` or `summary`. This is a full example of +a service call that updates the status of a To-do Item based on the name. + +```yaml +service: todo.update_item +target: + entity_id: todo.personal_tasks +data: + summary: "Submit Income Tax Return" + status: "completed" +``` + +### Service `todo.delete_item` + +Delete a To-do Item. A To-do list `target` is selected with a [Target Selector](/docs/blueprint/selectors/#target-selector) and the `data` payload supports the following fields: + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | --------| +| `uid` | yes | The Unique identifier of the To-do Item to update. | `bY1PVzZkni1qQQlkanTvBA` +| `summary` | yes | A short summary or subject for the To-do Item. | Submit Income Tax Return + +To-do Items can be identified using either a `uid` or `summary`. This is a full example of +a service call that delete's a To-do Item with the specified name. + +```yaml +service: todo.delete_item +target: + entity_id: todo.personal_tasks +data: + summary: "Submit Income Tax Return" +``` \ No newline at end of file