X-mas Fun with PowerShell and ScriptRunner

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):

1. Xmas Tree
2. Disco Light
3. Santa Claus

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

The main building blocks of REST-API architecture are:

• BASE-URI
• ENDPOINT
• 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
• Credentials
• 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:

1. Credentials, by using the type System.Management.Automation.PSCredential (the built-in credential vault of ScriptRunner can be used)
2. IP, by using the ipaddress type a built-in validation is done
3. The output which is limited from 1 to 4 as we have 4 outputs available

4. Setting the Outputs

• HostName, URI and endpoint of your box
• Credentials
• 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)

$ip = ‘192.168.111.111' 

$body = '{
"Outputs": [{
"ID": 1,
"Action": 0 
}]
}'

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

The Video

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.

Happy scripting & happy holidays!

Related links

• PowerPDU 4C | NETIO products a.s.