Device tags

Device tags were previously known as coverage tags.

Device tags are an extremely useful mechanism for applying metadata to devices, which will help you effectively manage devices. In this example, we define a tag, then we apply it to our domain database server, and then we target this device using a scope expression.

Defining the device tag and value

We start by defining the device tag and value. We will create a new device tag called DomainRole and assign it the initial value DatabaseServer. We do this using the add-1EDeviceTag cmdlet as shown below:

Copy
Add-1EDeviceTag -name DomainRole -value DatabaseServer

Device tags can have multiple values per tag. In this scenario, we could have chosen to add more values, such as DomainController, DNSServer, or whatever made sense from our management perspective.

Setting the device tag on the target devices

We now want the platform to set the device tag on the targeted devices. We choose to set the DomainRole tag with a value of DatabaseServer, targeting the device whose fqdn contains urth-sql. This is our lab database server.

To set the device tag, invoke the instruction as shown below.

Copy
Invoke-1EInstruction 1E-Explorer-TachyonCore-SetCoverageTag -tag_name DomainRole -tag_value DatabaseServer -targetscope urth-sql -Nowait

The scope you specify will define the devices that are to receive the tag. In this example, we have chosen a device that is running SQL Server. It will, therefore, receive the DomainRole tag with the value of DatabaseServer.

We specify the -nowait parameter because this is an action and not a question. Accordingly, it will require approval. By specifying -nowait, we regain control immediately with the instruction Id returned.

Currently the instruction refers to device tags as coverage tags. This is the name by which they were known in earlier releases and has been preserved for instruction compatibility.

The instruction defined two parameters whose names contain embedded spaces, Tag Name and Tag Value. PowerShell does not allow parameters to contain spaces; therefore, underscores are used instead. When you specify a parameter of Tag_Name or Tag_Value, it is automatically translated before being sent to the platform to replace the underscore with a space again.

If you had not specified either or both of these properties, you will be prompted for them by PowerShell in the normal way.

Approving the device tag set instruction

The instruction approver will now receive an email requesting that the instruction be approved, or the will see a notification in the 1E Platform. The approver receives a token (FWUM6 in the screenshot below) that will allow the instruction to be approved.

If workflow is configured for self-approval, because you are your own approver, you can directly approve the instruction and provide the token.

If workflow is configured for a separate approver (default configuration) you will need to approve the instruction in a separate PowerShell session.

If the platform is configured for Windows authentication, this session requires one of the following:

  • You are logged on to Windows as the approver using the runas command to start the session under alternate credentials.
  • You are authenticated as an appropriate alternate principal by using the -Credential option to the set-1Eserver cmdlet to supply appropriate alternate credentials. These credentials should correspond to those of a valid approver on the 1E Platform.

    If the platform is configured for platform-neutral authentication, then this session requires that you either interactively authenticate with alternate credentials using the set-1EServer cmdlet or that you authenticate using an appropriate certificate non-interactively. Refer to Platform server management cmdlets.

You approve the instruction using the approve-1Einstruction cmdlet.

Copy
approve-1Einstruction -id 1324 -token FWUM6

The instruction will now execute and set the device tag on the specified devices. In this case, only one device, URTH-SQL receives the tag. This way, we have now marked our lab database server.

Confirming the instruction approval

As the approver, you will have received a follow-up email confirming that the instruction was approved. Note that by default, a comment has been added that the instruction was approved by the 1E PowerShell Toolkit. You could have overridden the default comment by providing a -comment parameter when you approved the instruction above.

Confirming that the device tag has been set

You can use the platform instruction 1E-Explorer-TachyonCore-GetCoverageTag to determine if the device tag was set correctly. We target our entire lab machine base here (as all contain FQDNs with the string URTH in them), and we request to drill down to the detailed results, as this instruction is an aggregating one.

Copy
Invoke-1EInstruction 1E-Explorer-TachyonCore-GetCoverageTag -tag_name DomainRole -targetscope urth -drilldown

We can see that the URTH-SQL device has accepted and set the device tag.

Using the device tag to define the scope of an instruction

If we now want to send an instruction that targets only the database servers in our estate, we can use the device tag to do this.

We can use the Get-1ERespondingDevice cmdlet to see which devices would be associated with a defined device tag and value. We specify a target scope expression that uses the tagtxt entity to define the device tag and value. Within the square brackets, we define the tag name (DomainRole) and tag value (DatabaseServer).

Copy
Get-1ERespondingDevice -TargetScope tagtxt=[DomainRole=DatabaseServer]

You can see that only our database server is returned. This means that any instruction that we invoke in the platform can now accept a scope expression which refers to this device tag. When the instruction is invoked, only devices containing the matching tag and value respond.

For example, we can ask what memory chips are installed on any database server.

Copy
Invoke-1EInstruction 1E-Explorer-TachyonCore-InstalledMemoryDetails -TargetScope tagtxt=[DomainRole=DatabaseServer]

Conclusion

Device tags provide a powerful and flexible mechanism for managing devices through the 1E Platform. As you can see, it's easy to use the 1E PowerShell Toolkit to manage and set device tags and then target devices precisely.