Send-HipChat.ps1

<#
	{
		"info": {
			"Statement": "Code is poetry",
			"Author": "Joerg Hochwald",
			"Contact": "joerg.hochwald@outlook.com",
			"Link": "http://hochwald.net",
			"Support": "https://github.com/jhochwald/MyPowerShellStuff/issues"
		},
		"Copyright": "(c) 2012-2015 by Joerg Hochwald. All rights reserved."
	}

	Redistribution and use in source and binary forms, with or without modification,
	are permitted provided that the following conditions are met:

	1. Redistributions of source code must retain the above copyright notice, this list of
	   conditions and the following disclaimer.

	2. Redistributions in binary form must reproduce the above copyright notice,
	   this list of conditions and the following disclaimer in the documentation and/or
	   other materials provided with the distribution.

	3. Neither the name of the copyright holder nor the names of its contributors may
	   be used to endorse or promote products derived from this software without
	   specific prior written permission.

	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
	IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
	AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
	CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	POSSIBILITY OF SUCH DAMAGE.

	By using the Software, you agree to the License, Terms and Conditions above!
#>

function Send-HipChat {
<#
	.SYNOPSIS
		Send a notification message to a HipChat room.

	.DESCRIPTION
		Send a notification message to a HipChat room via a Rest Call to the HipChat API V2 of Atlassian

	.PARAMETER Token
		HipChat Auth Token

	.PARAMETER Room
		HipChat Room Name that get the notification. The Token has to fit to the Room!

	.PARAMETER notify
		Whether this message should trigger a user notification (change the tab color, play a sound, notify mobile phones, etc).
		Each recipient's notification preferences are taken into account.

	.PARAMETER color
		Background color for message. Valid is 'yellow', 'green', 'red', 'purple', 'gray', 'random'

	.PARAMETER Message
		The message body itself. Please see the HipChat API V2 documentation

	.PARAMETER Format
		Determines how the message is treated by the server and rendered inside HipChat applications

	.EXAMPLE
		PS C:\> Send-HipChat -Message "This is just a BuildServer Test" -color "gray" -Room "DevOps" -notify $true

		Sent a HipChat Room notification "This is just a BuildServer Test" to the Room "DevOps".
		It uses the Color "gray", and it sends a Notification to all users in the room.
		It uses a default Token to do so!

	.NOTES
		Early Beta Function!

	.LINK
		Joerg Hochwald: http://hochwald.net
#>

	[CmdletBinding(ConfirmImpact = 'None',
				   SupportsShouldProcess = $true)]
	param
	(
		[Parameter(HelpMessage = 'HipChat Auth Token')]
		[Alias('AUTH_TOKEN')]
		[string]
		$Token = "YOUR_DEFAULT_TOKEN_COMES_HERE",
		[Parameter(HelpMessage = 'HipChat Room Name that get the notification')]
		[Alias('ROOM_ID')]
		[string]
		$Room = "Testing",
		[Parameter(HelpMessage = 'Whether this message should trigger a user notification.')]
		[boolean]
		$notify = $false,
		[Parameter(HelpMessage = 'Background color for message.')]
		[ValidateSet('yellow', 'green', 'red', 'purple', 'gray', 'random', IgnoreCase = $true)]
		[string]
		$color = 'gray',
		[Parameter(HelpMessage = 'The message body')]
		[ValidateNotNullOrEmpty()]
		[string]
		$Message,
		[Parameter(HelpMessage = 'Determines how the message is treated by our server and rendered inside HipChat applications')]
		[ValidateSet('html', 'text', IgnoreCase = $true)]
		[Alias('message_format')]
		[string]
		$Format = 'text'
	)

	BEGIN {
		# Cleanup all variables...
		Remove-Variable -Name "headers" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "body" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "myBody" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "uri" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "myMethod" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "post" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
	}

	PROCESS {
		# Set the Header Variable
		Set-Variable -Name "headers" -Value $(@{
			"Authorization" = "Bearer $($Token)"
			"Content-type" = "application/json"
		})

		# Set the Body Variable, will be converted to JSON
		Set-Variable -Name "body" -Value $(@{
			"color" = "$color"
			"message_format" = "$Format"
			"message" = "$Message"
			"notify" = "$notify"
		})

		# Convert the Body Variable to JSON
		Set-Variable -Name "myBody" -Value $(ConvertTo-Json $body)

		# Set the URI Variable based on the Atlassian HipChat API V2 documentation
		Set-Variable -Name "uri" -Value $("https://api.hipchat.com/v2/room/" + $Room + "/notification")

		# Method to use for the Rest Call
		Set-Variable -Name "myMethod" -Value $("POST")

		# Fire up the Rest Call
		try {
			Set-Variable -Name "post" -Value $(Invoke-RestMethod -Uri $uri -Method $myMethod -Headers $headers -Body $myBody -ErrorAction:Stop -WarningAction:SilentlyContinue)
		} catch {
			# Whoopsie! That should not happen...
			Write-Warning -message "Could not send notification to your HipChat Room $Room"
			<#
				I use Send-HipChat a lot within automated tasks. I post updates from my build server
				and info from customers Mobile Device Management systems. So I decided to use a warning
				instead of an error here.

				You might want to change this to fit you needs.

				Remember: If you throw an terminating error, you might want to add a "finally"
				block to this try/catch Block here.
			#>
		}
	}

	END {
		# Cleanup all variables...
		Remove-Variable -Name "headers" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "body" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "myBody" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "uri" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "myMethod" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name "post" -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
	}
}