Hello, Agility Blue!

Introduction

Skill Level: Beginner
Execution Intent: Manual

The point of this script is to get familiar with the scripting environment within Agility Blue and to write your first "Hello, World!" style script. It uses the basic, but very important, PowerShell command `Write-Output` that can be found in any PowerShell environment that writes data to the output stream. In a console application, the `Write-Output` command writes data to the console. In Agility Blue scripting, each call to the output stream is captured as a new line in the additional information field for every execution result. 

Setup & Execution

Create a new script named "Hello, Agility Blue!" with the following body:

Write-Output "Hello, Agility Blue!"

Save the script and navigate to the details page of the script.

On the side panel, click on the "Execute Script..." link and then click on the "Execute" button after the modal window presents itself. After the script finishes processing, you should see the following execution results at the bottom of the modal window:

Hello, Agility Blue!

Remember, after you've closed the modal window, you can always view all script execution results on the execution results tab of the script details page to help you see the history of results. 

Congratulations, you've executed your first Agility Blue script!

"Hello, Agility Blue!"

Summary

Although this example was a very simple one-line script, it provided a very useful concept that will be instrumental for the success of providing you with feedback. Writing output is the best way to convey information for a variety of scenarios and is particularly important during the development of a script. You should treat writing output as a form of logging because it provides more context inside each execution. Here are some use cases for writing output:

• To provide the status of a particular milestone in a script. For example, while making a call to a collection that requires paging the data, it may be helpful to output each time the loop initiates the call.
• To output the structure/values of complex objects in a consumable format where you pipe data to commands such as `ConvertTo-JSON` or `ConvertTo-CSV`. This is a great way to get to understand the available properties on a particular object or to see a list of object values in a way that's more human readable.
• Catching and providing more context around an issue in a try-catch block.

One last thing to keep in mind about writing output is that unless your end users are executing scripts manually, which they likely aren't because most scripts will have some kind of event trigger attached to them, they will never see the execution results of a script. Writing output is very much a developer and systems-focused construct to help provide you with feedback on how a script is doing.