Add or remove tag

How the Add or remove tag action adds or removes a device tag – always, or depending on a condition.

Add or remove tag adds a tag to a device or removes it again – always, or depending on a condition. Use it, for example, to keep a tag that describes a device's state up to date automatically. The device doesn't need to be online.

Configuration fields

Field	Type	Required	Default	Description
Action	selection	Yes	Add tag	Add tag or Remove tag does exactly that. With Add or remove based on a condition, the Add the tag when … otherwise remove it field decides
Tag	text	Yes	—	The tag to add or remove, for example `maintenance`. Supports variables `${{ … }}`. You cannot save the automation without a tag
Target device (optional)	text	No	empty (This device)	Leave it empty to tag the run's own device. Otherwise enter a device ID or insert a variable that holds one. Device names do not work
Add the tag when … otherwise remove it	condition	Yes, with Add or remove based on a condition	—	Only shown for Add or remove based on a condition. Rows that compare a variable with a value, combined with All or Any, just like a step condition. If the condition matches, the tag is added; otherwise it is removed

The tag condition is not the same as the step's general Condition. The general condition decides whether the step runs at all. If it is not met, the step is skipped and the tag stays as it is. To add a tag only in some cases and otherwise leave it alone, use Add tag with a general condition.

Platform support

The action runs in octoja and works the same on every operating system.

Outputs

Output	Description
`tag`	The tag with variables resolved
`matched`	`true` when the step should add the tag, `false` when it should remove it
`action`	Action: `added`, `removed` or `unchanged`

Result behaviour

The step only deals with tags that were set by hand. It never removes a tag with the same name that a tag rule applied, and such a tag does not count as present. So the step can add a manual tag next to it. Case does not matter: Maintenance counts as the existing tag maintenance.

Situation	Result
The tag should be added, and the device does not have it yet	Succeeded, `action` = `added`
The tag should be removed, and the device has it	Succeeded, `action` = `removed`
The tag is already in the desired state	Succeeded, `action` = `unchanged`
Tag is empty after resolving	Failed: "No tag was specified for the add/remove-tag step."
Target device (optional) is not a valid device ID	Failed: "The target device could not be resolved to a valid device ID."
The target device does not exist or was deleted	Failed: "The target device was not found."

You can safely run the step again and again: it only changes the device when the tag really has to change. A variable octoja cannot resolve stays in the tag name as literal text.

Device tags (trigger.deviceTags) in conditions are captured when the run starts. If this step adds or removes a tag, later steps in the same run do not see that change.

See also: Create an automation · Configure Tag Rules

Was this helpful?

Still need help? Ask the team