Try Now

X-mas Fun with PowerShell and ScriptRunner

Table of Contents

Post Featured Image

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.

Screenshot: web interface of NETIO-4C

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:

Photo of the test setup, showing the pdu box, a LED Christmas decoration, an LED disco-ball and an electric Santa Claus puppet

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:

  • 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).

Screenshot: PowerShell output from running the command above

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
Screenshot: PowerShell output from variable $io_box

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:

Screenshot: ScriptRunner Admin App

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

The following parameters are required to set the output state:
  • 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.

Screenshot: Overview of NETIO outputs in the web interface next to the ScriptRunner Action that's used for controlling the test setup

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

About the author: