Christmas is the most wonderful time of year: presents, Glühwein*, kissing your beloved under the mistletoe. The fancy decoration, x-mas tree, and the stunning music … don’t we all love it? (*German for mulled wine)
Unfortunately, COVID-19 has prevented most of this. On the positive side, people get creative during lockdown, and we took the chance to demonstrate the possibilities of ScriptRunner in combination with an IOT Box.
Disclaimer: The scripts and examples are built for demo purposes and are not production ready, so proceed at your own risk!
1. Hardware requirements
For this project we used a NETIO-4C manageable PDU. The magical Blackbox has 4 x 230V outputs that can be controlled with several protocols (REST API, SNMP, MQTT, Modbus/TCP).
For our little demo we connected the following devices to the outputs and named the output in the web interface (fig. 1):
Output #4 was not used for our project.
Fig. 1: Naming the outputs in the NETIO-4C web interface
Further, we created a “write” user with a password and assigned the corresponding API permissions. Figure 2 shows our test setup:
Fig. 2: The test setup
2. Preparing the Rest-API
REST stands for REpresentational State Transfer. It is an approach to create your API’s in today’s world. API stands for Application Programming Interface and can be pictured as a waiter in the restaurant who passes the order from customer to the kitchen and delivers the result to the customer.
The main building blocks of REST-API architecture are:
ACTION (get, post, put, merge, delete,….)
Let’s explain this with a brief PowerShell example :
The result given by the API is a list of the James Bond movies with some details in a JSON format. To make it readable you can convert it from JSON to a PowerShell object with the ConvertFrom-Json commandlet (figure 3).
Fig. 3: List of James Bond movies retrieved with PowerShell via a REST-Api
3. Reading the Outputs
You need a bit of information to start scripting:
Hostname/IP of your box
Base URI and Endpoint
Fig. 4: PowerShell output from variable $io_box
Transforming the 2 lines of code into a function and using the html formatting and shaping features of ScriptRunner (figure 5) it gives a really nice output:
Fig. 5: Using ScriptRunner we can turn the PowerShell output into an HTML report
The function below returns the inverse state of a specified output. The required parameters are:
Credentials, by using the type System.Management.Automation.PSCredential (the built-in credential vault of ScriptRunner can be used)
IP, by using the ipaddress type a built-in validation is done
The output which is limited from 1 to 4 as we have 4 outputs available
4. Setting the Outputs
The following parameters are required to set the output state:
HostName, URI and endpoint of your box
A body in JSON-format containing the output definition:
ID which represents the number of the output (1-4)
Action which represents the desired state (0 = Off, 4 = On)
Invoke-RestMethod -Uri "http://$ip/netio.json" -Credential (get-credential) -Method Post -Body $body
Wrapping this piece of code into a nice function gives us the result below:
5. Show Time!
Based on this function we create an Action in the ScriptRunner Portal. For easier handling we embed it into a web page. The new ScriptRunner Portal Widget is perfect for this.
Putting the pieces of code together in ScriptRunner and combing the interface for the IOBox with the portal widget gives us a nice overview, as can be seen in figure 6 … more can be seen on the demo video.
Fig. 6: Using a ScriptRunner Portal Widget we can now comfortably control our test setup via PowerShell
As you can see very nicely in the video, we built our own little Christmas command center with just a few steps. If this project has inspired you, we would of course be happy if you shared your results with us, e.g. on Twitter under the hashtag #merryscriptmas.
Bruno Buyck is the founder of Trouble Shooter a company that specializes in PowerShell automation. The past decade Bruno delivered workshops on how to manage and automate systems with PowerShell. He has hundreds of script running in production environments which results in over 34 Million script executions every year. He loves to teach and prove that PowerShell is “What The Fuck”.