Creating your own cmdlet from a 1E Platform instruction

This article contains a walkthrough example of using the 1E PowerShell Toolkit to turn a useful 1E Platform instruction into a PowerShell cmdlet for re-use. It also explains how to take any of the 1E Platform's hundreds of powerful inbuilt agent methods and automatically wrap them in a new platform instruction and/or PowerShell cmdlet with just a couple of simple commands.

The 1E Platform source instruction

The 1E Platform source instruction is designed to retrieve all certificates on machines which expire within a certain number of days. The number of days can be passed as a parameter to the instruction.

This is quite straightforward to create using the Tachyon Instruction Management Studio (TIMS) and leveraging the platform's powerful built-in functions. In this case, we invoke the Security.GetCertificates() method and then filter to show only certificates which expire within the specified number of days.

Notice how 1E Platform results can be queried as if they were database tables. We can easily select the columns we want to return and the criteria for their retrieval.

Run in the test lab with a value of 80 days, we see that one certificate is due to expire on April 7, 2021.

We are now ready to deploy our instruction. When the file is saved, it will be automatically signed by a certificate, as you can see above. This ensures that instructions are secure and tamper-proof and can only be authored by appropriately privileged users who have access to the required signing certificate.

Publishing the instruction to the 1E Platform

Now that we have our signed instruction, we need to upload it to the 1E Platform. While we can use the platform UI to quickly and easily bring the instruction into the platform, we can also do this with the 1E PowerShell Toolkit.

We use the Publish-1EInstruction cmdlet to upload the instruction and assign it to an instruction set. In this example, the set is AJM.

Publish-1EInstruction

We did not specify the instruction file or instruction set on the command line, so we are now prompted to supply a value for them both.

Invoking the instruction 

We can now easily invoke the instruction, using the Invoke-1EInstruction cmdlet.

Invoke-1EInstruction 1E-Exchange-GetCertificates

We will be prompted for a TargetScope, since we did not supply a value on the command line.

The TargetScope parameter defines how we will select the target devices which will receive and process the instruction. In this case, we simply specify a string which is shorthand for fqdn like %urth%. In our test lab, this targets all devices.

The TargetScope parameter doesn't just accept simple strings; you can define a scope expression instead. Scope expressions are very powerful. You can select devices by name, partial name, by device attributes, such as operating system type and version, and many other criteria. You can also combine these criteria using AND, OR, and NOT to create precisely targeted instructions. For more information on using -TargetScope, refer to Scope and filter expressions.

Notice that we now get two results back. This is because, previously, we were just testing the instruction on our local machine. Now, we have deployed it to our estate and we have picked up another machine with an expiring certificate.

You can see how we were also prompted for the number of days parameter. Instruction parameters are automatically mapped to PowerShell parameters so that you can either directly specify them on the PowerShell command line or supply them as part of a PowerShell prompt.

Turning the instruction into a reusable cmdlet

We can now turn this instruction into a reusable cmdlet which we can then simply import and run, just like any other PowerShell cmdlet. This gives you the enormous power and flexibility of hundreds of platform instructions as part of your PowerShell environment.

We use the New-1ECmdLet cmdlet. We provide the name of the platform instruction and then the name of the cmdlet we'd like to create from it.

Now we can simply import and use the cmdlet, just like any other PowerShell cmdlet. Note how the parameters are automatically prompted for.

Leveraging the power of the 1E Platform via cmdlets

Although your generated cmdlet is simple to use, it inherits the enormous power and flexibility of the 1E Platform. As you can see, generated cmdlets support many optional parameters which leverage platform features.

Using the -ResultFilter parameter to filter cmdlet results

For example, you can use the 1E Platform's powerful result filtering option to select only results you want to see. Let's have a closer look at the information returned from the cmdlet. This is easy, just assign to a PowerShell variable and then send to the PowerShell format-list cmdlet.

We can see here that one certificate is found in the Personal store of a device and two others are coming from the Trusted store on another device. If we just want to see the results for certificates in the Personal stores of all devices, we can easily do it by creating the instruction with an optional parameter. All generated cmdlets leverage the full power of the 1E Platform, therefore, we can run the cmdlet using the parameter -ResultFilter and a value of "StoreName=Personal". As you can see, we only receive back results where the filter matches.

Automatically creating a platform instruction from an inbuilt method

Our example began with a platform instruction that was authored using the TIMS tool; however, you can create instructions yourself directly from PowerShell.

At the beginning of this article, we saw how a platform instruction was created to retrieve certificates. It used a built-in platform method called Security.GetCertificates(). Refer to The 1E Platform source instruction.

You can use the PowerShell Toolkit to automatically create new platform instructions from inbuilt methods. To do this, we use the new-1EInstructionXmlForMethod cmdlet. We specify the name of the built-in method that we want to be turned into an instruction, in this case, Security.GetCertificates.

The instruction XML file has been automatically created for us. Because we did not author this file using the TIMS authoring tool, we need to sign it before we can upload it to the platform. This is easy, using the protect-1Einstructionxml cmdlet.

Protect-1EInstructionXML 1E-Exchange-Security.getcertificates.xml

We can now upload the instruction to the platform.

Publish-1EInstruction

We can then run it.

Invoke-1EInstruction 1E-Exchange-Security.GetCertificates

Note that because we simply wrapped the Security.GetCertificates() method in an instruction, it had no parameters by default. Therefore, it returns all certificates on all target devices. We can leverage the full power of the 1E Platform to filter these results, and we can also turn this instruction into a PowerShell cmdlet, just like we did previously.

Finding out more about inbuilt methods

You can use the get-1Emethodinfo cmdlet to list all inbuilt methods you can use with the 1E PowerShell Toolkit. This cmdlet can also return detailed information on method parameters and results. For more information, refer to Instruction XML management cmdlets.

Conclusions

In this article, we've shown how easy it is to leverage the power of the 1E Platform. It was easy to query and return the data we wanted, and then, using the 1E PowerShell Toolkit, create cmdlets for reuse that leverage the power of the framework. 

We could also easily create new platform instructions, directly from any inbuilt method. This can save hours or even days of work developing complex scripts to retrieve information from devices.

As well as being quick and easy, this process is also scalable, secure, and performant. No PowerShell remoting infrastructure or permissions are required, yet the 1E Platform's flexible and granular role-based access controls ensure that only appropriately privileged users can initiate actions through the platform using the 1E PowerShell Toolkit.