On this page:

Creating a Consumer Using Powershell

In this exercise we are going to use Powershell to create a widget that will do one thing in Tachyon - Quarantine a specific device. We will name our consumer QWidget. This could be used in an emergency situation to perform a quarantine of a specific device. This could especially be useful when an administrator leaves an organization and still retains the company laptop.  The former employee's user account can be disabled but what happens if that employee has knowledge of service account passwords?  This is the scenario that QWidget will be used for, that device can be quarantined and when the former employee returns the laptop the quarantine can be removed with Tachyon.  We will write an instruction to do the quarantine action but not require the approval workflow. For security we will lock down this instruction to only be able to be run by our QWidget principal.

Create the Instruction

First we will write the instruction that QWidget will be using to perform the quarantine. The first thing we will need to do is enroll our Code Signing Certificate on the Tachyon server and the workstation we will be using. We will then need to install TIMS on the workstation we will be using (1ETRNW71). If you do not remember how to perform these steps go to the Tachyon Operator course starting at this exercise.

Ex 1 - Tachyon v5.1 - Using - Creating Instructions and Fragments Using TIMS: Configuring TIMS prerequisites

1ETRNW71
  1. Logged in as 1ETRN\Tachyon_Admin1
  2. Open TIMS from the shortcut on the desktop (if it is not already open)
  3. In the Code Block type in the following
  4. Security.QuarantineDevice();
  5. In the Instruction Definition pane Comments field type in QWidget Quarantine
  6. In the Description field type in Provides quarantine for one device for QWidget
  7. In the InstructionType field change to Action. Since we do not want to use the approval workflow for our instruction, we will toggle that off. Click on Workflow in the ribbon and select No user approval from the drop-down. Click Ok
  8. In the Name field type in 1ETRN-QWidgetQuarantine
  9. In the ReadablePayload field type in QWidget Quarantine
  10. Click on Schema. Click the + sign to add a column. Leave the Column Name, Data Type and Length to defaults. Click Ok.
  11. In the ribbon click Code Signing and choose always sign then select the Code Signing certificate that we imported. Click OK
  12. Save the file as c:\tools\1ETRN-QWidgetQuarantine.xml - click Ok on the message about not running the instruction before saving. Since we are running TIMS in user context quarantine produces an error when invoked from TIMS.
  13. Minimize TIMS. Open the ConfigMgr Content Source shortcut on the desktop and copy the Instruction from c:\tools to that location. We will then be able to access the file from the Tachyon Server to upload.

Upload Into Tachyon and Move to Instruction Set

We could do all of the next steps on Postman or with our powershell that we will be writing for QWidget but for ease of learning we will do these manually.

1ETRNAP
  1. Log into 1ETRNAP as 1ETRN\AppInstaller this is an account that is an Instruction Set Administrator
  2. Open the Config Mgr Content Source shortcut from the Desktop and copy 1ETRN-QWidgetQuarantine.xml to c:\temp
  3. Open Chrome and navigate to the Settings Application
  4. Upload the Instruction and move it to an Instruction Set called QWidget

Create the Consumer

1ETRNAP
  1. Still logged into Chrome in the Settings application navigate to Configuration - Consumers and click on Add
  2. In the Name field type in QWidget
  3. In the Maximum simultaneous instructions type in 5
  4. This is how we can limit the number of instructions that are run at one time from each consumer. We may have a few Admins that want to use our consumer, so we will allow 5 at each time. This number will be different for each consumer.
    The next two fields would be where we configure our web service in order to send all of our responses to our consumer. QWidget will only get a return code for a successful quarantine, so we will not need to offload the responses. If nothing is configured here the responses will be available in the Explorer application.
  5. Check the Enabled box
  6. Click Add

Create the Account in AD

1ETRNDC
  1. Open Active Directory Users and Computers
  2. Create a user called QWidget
  3. Set the password to Passw0rd uncheck the box to require password change at next login and Check the box for password never expires

Create the User and Role in Tachyon

1ETRNAP
  1. Back in Chrome in the Settings Application navigate to Permissions - Users and add our QWidget user
  2. Navigate to Permissions - Roles and click on Add this will create our custom role for QWidget
  3. Name the role QWidget and put in a meaningful description
  4. Find the new QWidget role in the list and open it by clicking on the name of the role
  5. In the Permissions tab click Add in the far right
  6. Choose Add and in the Type field select Instruction Set. In the Name field select QWidget and check Actioner, Approver, Questioner, and Viewer click Add
  7. Click the Management Groups tab and Click Add select All Devices. Click Add
  8. Click on the Members tab and click Add. Select our QWidget user. Click Add.

Create QWidget

Now we will write the Powershell script that will actually be our Consumer. We will use a Windows Form to display an input box to ask for our Device name.

1ETRNW102
  1. Click on Start - type in Power and select Powershell ISE when the suggestions appear to open the Powershell Integrated Scripting Environment.
  2. In the Powershell ISE type the following in your code block
  3. Add-Type -AssemblyName System.Windows.Forms
    Add-Type -AssemblyName System.Drawing
    This will add the assembly for the Windows Form we will use to display a window in powershell
  4. Under those two lines add a blank line and type in the following
  5. $tachyon = "Tachyon.1etrn.local"
    This variable will be used to build our URL to make our call to the Consumer API. This variable could also be used to test for someone accidentally entering the name of the tachyon server. We would want to exit the widget if someone tries to quarantine the actual server for an additional layer of security.
  6. Add a blank line to the bottom of the code block and enter the following
  7. $form = New-Object System.Windows.Forms.Form
    $form.Text = 'QWidget'
    $form.Size = New-Object System.Drawing.Size(500,250)
    $form.StartPosition = 'CenterScreen'
    This block of code determines the size of the window that opens in pixels - enclosed in ( ), the placement on the screen, and the text it displays at the top
  8. Click Run at the top. You should see the return in the bottom pane. It won't be very exciting yet until we add some additional code. Ensure that you have no errors.
  9. Under those lines add a blank line and type in the following
  10. $OKButton = New-Object System.Windows.Forms.Button
    $OKButton.Location = New-Object System.Drawing.Point(150,120)
    $OKButton.Size = New-Object System.Drawing.Size(75,23)
    $OKButton.Text = 'OK'
    $OKButton.DialogResult = [System.Windows.Forms.DialogResult]::OK
    $form.AcceptButton = $OKButton
    $form.Controls.Add($OKButton)
    This bit of code controls the look and placement of our OK button
  11. Under the last line of code add a blank line and type in the following
  12. $CancelButton = New-Object System.Windows.Forms.Button
    $CancelButton.Location = New-Object System.Drawing.Point(220,120)
    $CancelButton.Size = New-Object System.Drawing.Size(75,23)
    $CancelButton.Text = 'Cancel'
    $CancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel
    $form.CancelButton = $CancelButton
    $form.Controls.Add($CancelButton)
    This bit of code controls the look and placement of our cancel button
  13. Click Run ensure there are no errors.
  14. Under the last line of code create a blank line and type in the following
  15. $label = New-Object System.Windows.Forms.Label
    $label.Location = New-Object System.Drawing.Point(75,20)
    $label.Size = New-Object System.Drawing.Size(290,20)
    $label.Text = 'Enter the Device Name to Quarantine:'
    $form.Controls.Add($label)
    This bit of the code controls the size and placement of the text - this is what tells the user what needs to be entered in the box that will be displayed with the next bit of code.
  16. Under the last line hit enter to create a blank line and then enter the following
  17. $textBox = New-Object System.Windows.Forms.TextBox
    $textBox.Location = New-Object System.Drawing.Point(75,50)
    $textBox.Size = New-Object System.Drawing.Size(289,100)
    $form.Controls.Add($textBox)
    This controls the size and placement of the box the user will enter in the device name
  18. Under the last line add a blank space and type in the following
  19. $form.Topmost = $true
    $form.Add_Shown({$textBox.Select()})
    $result = $form.ShowDialog()
    This bit of code makes the window that opens be the window on top of any other open windows
  20. Click Run at the top and now you should be able to see our form. Type something in the text box and click OK. Notice nothing in our bottom pane.
  21. Add a blank line and enter the following in our code block
  22. if ($result -eq [System.Windows.Forms.DialogResult]::OK)
    {
        $x = $textBox.Text
        $xarray = $x.split(" ") 
    We are using the powershell spit with no delimeter because Tachyon is expecting an array here and there is a limitation in powershell that a single value cannot be an array.
  23. Click Run. Did you get an error? That is because our closing curly brace is lower in our code. Add a closing curly brace and on the next line type in Echo $xarray then click run again.
  24. Type something in the box and click Ok. Note the return, our xarray variable is set to what we typed into the box
  25. This starts our IF block when the user selects OK. 
  26. Now we will add the rest of our code under the last line of our code block but first delete the closing curly brace and the Echo line that you added for testing.
  27.     $URI = "https://$tachyon/consumer/Instructions/Targeted"
        $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    	$headers.add("X-Tachyon-Consumer", "QWidget")
    	$headers.add("Content-Type","Application/Json")
        $body = @{
    				DefinitionId = "216"
    				InstructionTtlMinutes = "120"
    				ResponseTtlMinutes = "120"
    				Devices = $xarray
    
    }
    	$json = $body | ConvertTo-Json
    
        Invoke-WebRequest -URI $URI -Method Post -UseDefaultCredential -Body $json -Headers $headers
       
    }
  28. In Postman run your request to pull your Instruction Definition IDs and replace 216 in your code block if your QWidget Instruction Definition ID is not 216.
  29. The next lines build our Web Call into Tachyon. The next line is setting our URI for the API endpoint we are going to request to create our action. We then build our two headers (remember those from the Postman exercises). Finally, we are building the Body of our request (this should look familiar from Postman) setting the instruction definition we will use and limiting our coverage to the device we are entering into the form. We then are converting those to a json. The final line is the actual request to the API.
  30. Save the file as c:\sources\QWidget.ps1
The blank lines are there easily read the code. In production, you should not add these spaces as they serve no purpose in your code and just end up making your code larger.

Your Code Block for QWidget should look like this

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing
$tachyon = "Tachyon.1etrn.local"

$form = New-Object System.Windows.Forms.Form
$form.Text = 'QWidget'
$form.Size = New-Object System.Drawing.Size(500,250)
$form.StartPosition = 'CenterScreen'

$OKButton = New-Object System.Windows.Forms.Button
$OKButton.Location = New-Object System.Drawing.Point(150,120)
$OKButton.Size = New-Object System.Drawing.Size(75,23)
$OKButton.Text = 'OK'
$OKButton.DialogResult = [System.Windows.Forms.DialogResult]::OK
$form.AcceptButton = $OKButton
$form.Controls.Add($OKButton)

$CancelButton = New-Object System.Windows.Forms.Button
$CancelButton.Location = New-Object System.Drawing.Point(220,120)
$CancelButton.Size = New-Object System.Drawing.Size(75,23)
$CancelButton.Text = 'Cancel'
$CancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel
$form.CancelButton = $CancelButton
$form.Controls.Add($CancelButton)

$label = New-Object System.Windows.Forms.Label
$label.Location = New-Object System.Drawing.Point(75,20)
$label.Size = New-Object System.Drawing.Size(290,20)
$label.Text = 'Enter the Device Name to Quarantine:'
$form.Controls.Add($label)

$textBox = New-Object System.Windows.Forms.TextBox
$textBox.Location = New-Object System.Drawing.Point(75,50)
$textBox.Size = New-Object System.Drawing.Size(289,100)
$form.Controls.Add($textBox)

$form.Topmost = $true
$form.Add_Shown({$textBox.Select()})
$result = $form.ShowDialog()

if ($result -eq [System.Windows.Forms.DialogResult]::OK)
{
    $x = $textBox.Text
    $xarray = $x.split(" ")

 $URI = "https://$tachyon/consumer/Instructions/targeted"
    $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
	$headers.add("X-Tachyon-Consumer", "QWidget")
	$headers.add("Content-Type","Application/Json")
    $body = @{
				DefinitionId = "216"
				InstructionTtlMinutes = "120"
				ResponseTtlMinutes = "120"
				Devices = $xarray

}
	$json = $body | ConvertTo-Json

    Invoke-RestMethod -URI $URI -Method Post -UseDefaultCredentials -Body $json -Headers $headers
   
}

Using QWidget

In this exercise we will actually use our new Consumer - QWidget from 1ETRNW102 and Quarantine 1ETRNW101.  We will perform this via the desktop shortcut.  We will also run QWidget from within the Powershell ISE so that you can also see the data that is returned.  Our web form does not display the return details as it is not necessary for the functionality of QWidget.

1ETRNW101
  1. Log into 1ETRNW101 and make sure the device can get to the internet and Ping the Config Mgr Server 1ETRNCM
1ETRW102
  1. Create a Desktop Shortcut to c:\sources\qwidget.ps1
  2. Right click the shortcut and choose Run with Powershell when the command window opens type in and hit enter
  3. Enter 1ETRNW101.1etrn.local in the box. Click Ok
1ETRNW101
  1. Make sure that you cannot access the internet or the Configuration Manager Server
1ETRNW102
  1. In the powershell ISE, with QWidget still in the code block click the run button.  When QWidget opens type in 1ETRNW73.1etrn.local and click Ok

1ETRNW102
  1. Open the Explorer Application and ask the question Are my devices quarantined?
  2. You should see that 1ETRNW101 and 1ETRNW73 are quarantined
1ETRNW71
  1. Issue the action to take 1ETRNW101 out of quarantine
  2. Open Live Mail and authenticate with the code in the InBox
1ETRNW102
  1. Open the Explorer Application and Navigate to Notifications and approve the request to remove the device from Quarantine
If you try to use QWidget again to quarantine more than 5 devices you may need to cancel your inflight QWidget Quarantine.  This is controlled by our Consumer settings - max simultaneous instructions).  We have ours set to 5, in this lab it probably will not impact you but in production will need to adjust this based on what type of consumer you are creating.  You also may need to adjust your durations this one is set to stay on the switch for two hours, again you may need to adjust depending on the specifics of your consumer.

Extra Credit

  1. Using Powershell write a script that does all of the steps that you have just done manually (creates the consumer, creates the instruction and instruction set, creates the role and gives permissions to that instruction set.
  2. Create another powershell that does one item in Tachyon (a good one to think about is free form tagging).  This type of widget would be handy for a service desk to use.  Think about devices that have the same issue and is being reported by multiple users, to multiple analysts. When you are waiting for a vendor supplied hotfix it makes sense to free form tag the devices that will need the hotfix. You could potentially have multiple service desk analysts doing the tagging with TWidget, and then you will have a list for targeting when the hotfix is supplied.

Lab Summary

In this exercise we learned how to use Powershell to accept some data from a user and then take action on that device in Tachyon. We could easily have taken any other action in Tachyon by using different instructions.