Skip to content

Commit 2f9b146

Browse files
Petro31c0ffeeca7
Petro31
and
c0ffeeca7
authored
Add template migration examples (#42149)
Co-authored-by: c0ffeeca7 <[email protected]>
1 parent c8cc7bc commit 2f9b146

File tree

1 file changed

+356
-0
lines changed

1 file changed

+356
-0
lines changed

‎source/_integrations/template.markdown‎

Lines changed: 356 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2792,3 +2792,359 @@ The blueprint can now be used for creating template entities.
27922792
Event `event_template_reloaded` is fired when Template entities have been reloaded and entities thus might have changed.
27932793

27942794
This event has no additional data.
2795+
2796+
## Legacy template deprecation migration guide
2797+
2798+
Legacy template entities are deprecated and will be removed in Home Assistant 2026.6.0. The deprecated template entities will produce a repair that guides you through the migration.
2799+
2800+
### Migrating a legacy sensor into a new template section
2801+
2802+
This example covers how to migrate a legacy template sensor into modern syntax.
2803+
2804+
Take the example `configuration.yaml` file
2805+
2806+
{% raw %}
2807+
```yaml
2808+
# configuration.yaml
2809+
sensor:
2810+
# SNMP Configuration
2811+
- platform: snmp
2812+
host: 192.168.1.32
2813+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
2814+
2815+
# Legacy template configuration
2816+
- platform: template
2817+
sensors:
2818+
my_light_count:
2819+
friendly_name: Total lights on
2820+
unique_id: sa892hfa9sdf8
2821+
value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
2822+
```
2823+
2824+
{% endraw %}
2825+
To get started with the migration:
2826+
2827+
1. Remove the `sensor` template definition from the `configuration.yaml` `sensor:` section.
2828+
2829+
Delete the following YAML from `configuration.yaml` file.
2830+
2831+
{% raw %}
2832+
```yaml
2833+
# Legacy template configuration
2834+
- platform: template
2835+
sensors:
2836+
my_light_count:
2837+
friendly_name: Total lights on
2838+
unique_id: sa892hfa9sdf8
2839+
value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
2840+
```
2841+
{% endraw %}
2842+
2843+
Make sure to keep all the other platforms in the sensor section. Your `configuration.yaml` file would look like this after the change:
2844+
2845+
```yaml
2846+
# configuration.yaml
2847+
sensor:
2848+
# SNMP Configuration
2849+
- platform: snmp
2850+
host: 192.168.1.32
2851+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
2852+
```
2853+
2854+
1. Add the modern syntax provided by the repair.
2855+
2856+
The repair would provide the following YAML.
2857+
2858+
{% raw %}
2859+
```yaml
2860+
template:
2861+
- sensor:
2862+
- default_entity_id: sensor.my_light_count
2863+
name: Total lights on
2864+
unique_id: sa892hfa9sdf8
2865+
state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
2866+
```
2867+
{% endraw %}
2868+
2869+
This YAML should be added to the `template:` section inside `configuration.yaml`.
2870+
2871+
{% raw %}
2872+
```yaml
2873+
# configuration.yaml
2874+
sensor:
2875+
# SNMP Configuration
2876+
- platform: snmp
2877+
host: 192.168.1.32
2878+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
2879+
2880+
# Copied example
2881+
template:
2882+
- sensor:
2883+
- default_entity_id: sensor.my_light_count
2884+
name: Total lights on
2885+
unique_id: sa892hfa9sdf8
2886+
state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
2887+
```
2888+
{% endraw %}
2889+
2890+
If you are migrating multiple template entities, ensure there is only 1 `template:` section. Do not keep duplicate `template:` sections.
2891+
2892+
{% raw %}
2893+
```yaml
2894+
# configuration.yaml
2895+
sensor:
2896+
# SNMP Configuration
2897+
- platform: snmp
2898+
host: 192.168.1.32
2899+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
2900+
2901+
template:
2902+
2903+
# Migrated sensor
2904+
- sensor:
2905+
- default_entity_id: sensor.my_light_count
2906+
name: Total lights on
2907+
unique_id: sa892hfa9sdf8
2908+
state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
2909+
2910+
# Migrated cover
2911+
- cover:
2912+
- default_entity_id: cover.garage
2913+
name: Garage Cover
2914+
state: '{{ is_state(''binary_sensor.relay'', ''on'') }}'
2915+
2916+
# Migrated light
2917+
- light:
2918+
- default_entity_id: light.skylight
2919+
name: Skylight
2920+
state: '{{ is_state(''binary_sensor.crank'', ''on'') }}'
2921+
```
2922+
{% endraw %}
2923+
2924+
1. Restart Home Assistant by going to **Settings** three dotted menu and selecting **Restart Home Assistant**. Or reload template entities by going to **Developer tools** **YAML** tab and selecting the **Template entities** reload button.
2925+
2926+
### Migrating a legacy sensor into an existing template section
2927+
2928+
This example covers how to migrate a legacy template sensor into modern syntax.
2929+
2930+
Take the example `configuration.yaml` file
2931+
2932+
{% raw %}
2933+
```yaml
2934+
# configuration.yaml
2935+
sensor:
2936+
# SNMP Configuration
2937+
- platform: snmp
2938+
host: 192.168.1.32
2939+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
2940+
2941+
# Legacy template configuration
2942+
- platform: template
2943+
sensors:
2944+
my_light_count:
2945+
friendly_name: Total lights on
2946+
unique_id: sa892hfa9sdf8
2947+
value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
2948+
2949+
template:
2950+
# Existing modern template
2951+
- binary_sensor:
2952+
- name: Bright Outside
2953+
state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
2954+
```
2955+
{% endraw %}
2956+
2957+
To get started with the migration:
2958+
2959+
1. Remove the `sensor` template definition from the `configuration.yaml` `sensor:` section.
2960+
2961+
Delete the following YAML from `configuration.yaml` file.
2962+
2963+
{% raw %}
2964+
```yaml
2965+
# Legacy template configuration
2966+
- platform: template
2967+
sensors:
2968+
my_light_count:
2969+
friendly_name: Total lights on
2970+
unique_id: sa892hfa9sdf8
2971+
value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
2972+
```
2973+
{% endraw %}
2974+
2975+
Make sure to keep all the other platforms in the sensor section. Your `configuration.yaml` file would look like this after the change:
2976+
2977+
{% raw %}
2978+
```yaml
2979+
# configuration.yaml
2980+
sensor:
2981+
# SNMP Configuration
2982+
- platform: snmp
2983+
host: 192.168.1.32
2984+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
2985+
2986+
template:
2987+
# Existing modern template
2988+
- binary_sensor:
2989+
- name: Bright Outside
2990+
state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
2991+
```
2992+
{% endraw %}
2993+
2994+
1. Add the modern syntax provided by the repair.
2995+
2996+
The repair would provide the following YAML.
2997+
2998+
{% raw %}
2999+
```yaml
3000+
template:
3001+
- sensor:
3002+
- default_entity_id: sensor.my_light_count
3003+
name: Total lights on
3004+
unique_id: sa892hfa9sdf8
3005+
state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
3006+
```
3007+
{% endraw %}
3008+
3009+
This YAML should be added to the `template:` section inside `configuration.yaml`.
3010+
3011+
{% raw %}
3012+
```yaml
3013+
# configuration.yaml
3014+
sensor:
3015+
# SNMP Configuration
3016+
- platform: snmp
3017+
host: 192.168.1.32
3018+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
3019+
3020+
template:
3021+
# Existing modern template
3022+
- binary_sensor:
3023+
- name: Bright Outside
3024+
state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
3025+
3026+
# Copied example
3027+
- sensor:
3028+
- default_entity_id: sensor.my_light_count
3029+
name: Total lights on
3030+
unique_id: sa892hfa9sdf8
3031+
state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
3032+
```
3033+
{% endraw %}
3034+
3035+
In this example, `configuration.yaml` already had a `template:` section. When copying the YAML, make sure to avoid adding double `template:` sections.
3036+
3037+
1. Restart Home Assistant by going to **Settings** three dotted menu and selecting **Restart Home Assistant**. Or reload template entities by going to **Developer tools** **YAML** tab and selecting the **Template entities** reload button.
3038+
3039+
### Migrating a sensor from an included file to an included file
3040+
3041+
This example covers how to migrate a legacy template sensor into modern syntax when the sensor exists in an included `sensors.yaml` file.
3042+
3043+
Take the example configuration. It's a configuration that is split between 3 files, `configuration.yaml`, `sensors.yaml`, and `templates.yaml`.
3044+
3045+
```yaml
3046+
# configuration.yaml
3047+
sensor: !include sensors.yaml
3048+
template: !include templates.yaml
3049+
```
3050+
3051+
{% raw %}
3052+
```yaml
3053+
# sensors.yaml
3054+
3055+
# SNMP Configuration
3056+
- platform: snmp
3057+
host: 192.168.1.32
3058+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
3059+
3060+
# Legacy template configuration
3061+
- platform: template
3062+
sensors:
3063+
my_light_count:
3064+
friendly_name: Total lights on
3065+
unique_id: sa892hfa9sdf8
3066+
value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
3067+
```
3068+
3069+
{% endraw %}
3070+
3071+
{% raw %}
3072+
```yaml
3073+
# templates.yaml
3074+
3075+
# Existing modern template
3076+
- binary_sensor:
3077+
- name: Bright Outside
3078+
state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
3079+
```
3080+
{% endraw %}
3081+
3082+
To get started with the migration:
3083+
3084+
1. Remove the `sensor` template definition from the `sensors.yaml` section.
3085+
3086+
Delete the following YAML from `sensors.yaml` file.
3087+
3088+
{% raw %}
3089+
```yaml
3090+
# Legacy template configuration
3091+
- platform: template
3092+
sensors:
3093+
my_light_count:
3094+
friendly_name: Total lights on
3095+
unique_id: sa892hfa9sdf8
3096+
value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
3097+
```
3098+
3099+
{% endraw %}
3100+
Make sure to keep all the other platforms in the sensor file. Your `sensors.yaml` file would look like this after the change:
3101+
3102+
3103+
```yaml
3104+
# sensors.yaml
3105+
3106+
# SNMP Configuration
3107+
- platform: snmp
3108+
host: 192.168.1.32
3109+
baseoid: 1.3.6.1.4.1.2021.10.1.3.1
3110+
```
3111+
3112+
2. Add the modern syntax provided by the repair.
3113+
3114+
The repair would provide the following YAML.
3115+
3116+
{% raw %}
3117+
```yaml
3118+
template:
3119+
- sensor:
3120+
- default_entity_id: sensor.my_light_count
3121+
name: Total lights on
3122+
unique_id: sa892hfa9sdf8
3123+
state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
3124+
```
3125+
3126+
{% endraw %}
3127+
This YAML should be added to the `templates.yaml` file.
3128+
3129+
{% raw %}
3130+
```yaml
3131+
# templates.yaml
3132+
3133+
# Existing modern template
3134+
- binary_sensor:
3135+
- name: Bright Outside
3136+
state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
3137+
3138+
# Copied example
3139+
- sensor:
3140+
- default_entity_id: sensor.my_light_count
3141+
name: Total lights on
3142+
unique_id: sa892hfa9sdf8
3143+
state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
3144+
```
3145+
3146+
{% endraw %}
3147+
3148+
In this example, `configuration.yaml` already has a `template: !include templates.yaml`. When copying the yaml, make sure to avoid adding the `template:` section inside `templates.yaml`.
3149+
3150+
1. Restart Home Assistant by going to **Settings** three dotted menu and selecting **Restart Home Assistant**. Or reload template entities by going to **Developer tools** **YAML** tab and selecting the **Template entities** reload button.

0 commit comments

Comments
 (0)