# HipChatAdmin

HipChatAdmin is a PowerShell module designed to automate Atlassian HipChat administration tasks using the HipChat API V2. Originally developed as a simple script for employee onboarding, it has evolved into a comprehensive toolkit for managing HipChat users, rooms, and messaging. The module requires PowerShell 5 or later and an API token with appropriate scopes (Administer Group, Manage Rooms, Send Notification).

The module provides eight public functions that cover the most common HipChat administration tasks: creating and removing user accounts, creating and deleting rooms, managing room membership, and sending notifications to rooms. All functions follow standard PowerShell cmdlet conventions, support pipeline input, and return PSObjects with operation results including status codes.

## Installation

Install HipChatAdmin from the PowerShell Gallery or manually copy the module folder to your PowerShell modules path.

```powershell
# Install from PowerShell Gallery (recommended)
Install-Module -Name HipChatAdmin

# Verify installation
Get-Module -ListAvailable HipChatAdmin

# Import the module
Import-Module HipChatAdmin

# Check available commands
Get-Command -Module HipChatAdmin
# Output:
# CommandType     Name                        Version    Source
# -----------     ----                        -------    ------
# Function        Add-HipchatUserToRoom       1.1        HipChatAdmin
# Function        Get-HipchatUser             1.1        HipChatAdmin
# Function        New-HipchatRoom             1.1        HipChatAdmin
# Function        New-HipchatUser             1.1        HipChatAdmin
# Function        Remove-HipchatRoom          1.1        HipChatAdmin
# Function        Remove-HipchatUser          1.1        HipChatAdmin
# Function        Remove-HipchatUserFromRoom  1.1        HipChatAdmin
# Function        Send-HipchatMessage         1.1        HipChatAdmin
```

## New-HipchatUser

Creates a new HipChat user account using the HipChat API. The mention name defaults to the user's first and last name concatenated, but can be customized. First and last names are automatically formatted with proper capitalization.

```powershell
# Store your API token securely
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Create a new user with default mention name (@JohnSmith)
New-HipchatUser -FirstName 'John' -LastName 'Smith' -EmailAddress 'jsmith@example.com' -ApiToken $ApiToken
# Output:
# MentionName  FirstName  LastName  StatusCode
# -----------  ---------  --------  ----------
# JohnSmith    John       Smith     201

# Create a new user with a custom mention name
New-HipchatUser -FirstName 'John' -LastName 'Smith' -EmailAddress 'jsmith@example.com' -MentionName 'Jay.Smith' -ApiToken $ApiToken
# Output:
# MentionName  FirstName  LastName  StatusCode
# -----------  ---------  --------  ----------
# Jay.Smith    John       Smith     201

# Create multiple users from a CSV file
$employees = Import-Csv -Path 'new_employees.csv'
# CSV format: FirstName,LastName,EmailAddress
foreach ($emp in $employees) {
    try {
        $result = New-HipchatUser -FirstName $emp.FirstName -LastName $emp.LastName -EmailAddress $emp.EmailAddress -ApiToken $ApiToken -Verbose
        Write-Host "Created user: $($result.MentionName)"
    }
    catch {
        Write-Error "Failed to create user $($emp.FirstName) $($emp.LastName): $_"
    }
}
```

## Remove-HipchatUser

Deletes an existing HipChat user account by their mention name or email address. This permanently removes the user from HipChat.

```powershell
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Remove a user by mention name
Remove-HipchatUser -MentionName 'JohnSmith' -ApiToken $ApiToken
# Output:
# Name        StatusCode
# ----        ----------
#             204

# Remove a user by email address
Remove-HipchatUser -EmailAddress 'jsmith@example.com' -ApiToken $ApiToken
# Output:
# Name        StatusCode
# ----        ----------
#             204

# Bulk removal of departing employees
$departingUsers = @('JohnSmith', 'JaneDoe', 'BobJohnson')
foreach ($user in $departingUsers) {
    try {
        Remove-HipchatUser -MentionName $user -ApiToken $ApiToken -Verbose
        Write-Host "Removed user: @$user"
    }
    catch {
        Write-Error "Failed to remove @$user: $_"
    }
}
```

## Get-HipchatUser

Retrieves a list of all existing HipChat users in your organization, returning their display names and mention names.

```powershell
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Get all HipChat users
$users = Get-HipchatUser -ApiToken $ApiToken
# Output:
# Name              MentionName
# ----              -----------
# John Smith        JohnSmith
# Jane Doe          JaneDoe
# Bob Johnson       BobJohnson

# Count total users
$users = Get-HipchatUser -ApiToken $ApiToken
Write-Host "Total users: $($users.Count)"

# Filter users by name pattern
$users = Get-HipchatUser -ApiToken $ApiToken
$smithUsers = $users | Where-Object { $_.Name -like '*Smith*' }
$smithUsers | Format-Table -AutoSize

# Export all users to CSV for reporting
$users = Get-HipchatUser -ApiToken $ApiToken
$users | Export-Csv -Path 'hipchat_users.csv' -NoTypeInformation

# Find a specific user
$users = Get-HipchatUser -ApiToken $ApiToken
$targetUser = $users | Where-Object { $_.MentionName -eq 'JohnSmith' }
if ($targetUser) {
    Write-Host "Found user: $($targetUser.Name)"
}
```

## New-HipchatRoom

Creates a new HipChat room. Rooms are public by default (visible to all organization members), but can be made private (invite-only) using the -Private switch.

```powershell
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Create a public room
New-HipchatRoom -Name 'Development' -ApiToken $ApiToken
# Output:
# Name          StatusCode
# ----          ----------
# Development   201

# Create a private room
New-HipchatRoom -Name 'Finance' -Private -ApiToken $ApiToken
# Output:
# Name          StatusCode
# ----          ----------
# Finance       201

# Create multiple project rooms
$projectRooms = @('Project-Alpha', 'Project-Beta', 'Project-Gamma')
foreach ($room in $projectRooms) {
    try {
        New-HipchatRoom -Name $room -Private -ApiToken $ApiToken -Verbose
        Write-Host "Created private room: $room"
    }
    catch {
        Write-Error "Failed to create room $room: $_"
    }
}
```

## Remove-HipchatRoom

Deletes an existing HipChat room and automatically kicks all users from the room. The room name must match exactly as it appears in HipChat.

```powershell
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Remove a room
Remove-HipchatRoom -Name 'Development' -ApiToken $ApiToken
# Output:
# Name          StatusCode
# ----          ----------
# Development   204

# Remove multiple rooms
$obsoleteRooms = @('Old-Project', 'Archived-Team', 'Temp-Discussion')
foreach ($room in $obsoleteRooms) {
    try {
        Remove-HipchatRoom -Name $room -ApiToken $ApiToken -Verbose
        Write-Host "Removed room: $room"
    }
    catch {
        Write-Error "Failed to remove room $room: $_"
    }
}
```

## Add-HipchatUserToRoom

Invites one or more existing HipChat users to join a room. Accepts an array of mention names to add multiple users at once.

```powershell
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Add a single user to a room
Add-HipchatUserToRoom -MentionName 'JohnSmith' -RoomName 'Development' -ApiToken $ApiToken
# Output:
# Name          StatusCode
# ----          ----------
# JohnSmith     204

# Add multiple users to a room
Add-HipchatUserToRoom -MentionName 'JohnSmith','JaneDoe','BobJohnson' -RoomName 'Project-Alpha' -ApiToken $ApiToken
# Output:
# Name          StatusCode
# ----          ----------
# JohnSmith     204
# JaneDoe       204
# BobJohnson    204

# Onboard new employee - add to standard rooms
$newEmployee = 'JohnSmith'
$standardRooms = @('General', 'Announcements', 'Water-Cooler')
foreach ($room in $standardRooms) {
    try {
        Add-HipchatUserToRoom -MentionName $newEmployee -RoomName $room -ApiToken $ApiToken
        Write-Host "Added @$newEmployee to $room"
    }
    catch {
        Write-Error "Failed to add @$newEmployee to $room: $_"
    }
}
```

## Remove-HipchatUserFromRoom

Removes one or more users from a HipChat room. Accepts an array of mention names to remove multiple users at once.

```powershell
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Remove a single user from a room
Remove-HipchatUserFromRoom -MentionName 'JohnSmith' -RoomName 'Development' -ApiToken $ApiToken
# Output:
# Name          StatusCode
# ----          ----------
# JohnSmith     204

# Remove multiple users from a room
Remove-HipchatUserFromRoom -MentionName 'JohnSmith','JaneDoe','AlPennyworth' -RoomName 'Finance' -ApiToken $ApiToken
# Output:
# Name          StatusCode
# ----          ----------
# JohnSmith     204
# JaneDoe       204
# AlPennyworth  204

# Offboard departing employee - remove from all sensitive rooms
$departingEmployee = 'JohnSmith'
$sensitiveRooms = @('Finance', 'HR', 'Executive-Team')
foreach ($room in $sensitiveRooms) {
    try {
        Remove-HipchatUserFromRoom -MentionName $departingEmployee -RoomName $room -ApiToken $ApiToken
        Write-Host "Removed @$departingEmployee from $room"
    }
    catch {
        Write-Error "Failed to remove @$departingEmployee from $room: $_"
    }
}
```

## Send-HipchatMessage

Sends a notification message to a HipChat room with customizable background color and notification settings. Messages appear as coming from the API token owner, with an optional "from" label displayed alongside the sender's name.

```powershell
$ApiToken = 'REXsCauSe553gsoIJg1Gj4zwNsSAwS'

# Send a simple message
Send-HipchatMessage -Message 'Hello team!' -RoomName 'General' -Notify $false -ApiToken $ApiToken
# Output:
# Name        StatusCode
# ----        ----------
#             204

# Send a notification with custom color and alert
Send-HipchatMessage -Message 'Build Failed!' -RoomName 'Development' -From 'Jenkins' -Color 'red' -Notify $true -ApiToken $ApiToken
# Output:
# Name        StatusCode
# ----        ----------
#             204

# Send a success notification
Send-HipchatMessage -Message 'Deployment to production completed successfully!' -RoomName 'Development' -From 'Deploy Bot' -Color 'green' -Notify $true -ApiToken $ApiToken

# Available colors: yellow, green, red, purple, gray (default)

# Integration with CI/CD pipeline
function Send-BuildNotification {
    param(
        [string]$BuildStatus,
        [string]$BuildNumber,
        [string]$RoomName = 'Development'
    )

    $ApiToken = $env:HIPCHAT_API_TOKEN

    if ($BuildStatus -eq 'Success') {
        $message = "Build #$BuildNumber completed successfully!"
        $color = 'green'
    }
    else {
        $message = "Build #$BuildNumber failed. Please investigate."
        $color = 'red'
    }

    Send-HipchatMessage -Message $message -RoomName $RoomName -From 'CI Server' -Color $color -Notify $true -ApiToken $ApiToken
}

# Usage in build script
Send-BuildNotification -BuildStatus 'Success' -BuildNumber '1234'
```

## Summary

HipChatAdmin is ideal for automating employee onboarding and offboarding workflows, where multiple HipChat accounts and room memberships need to be managed in bulk. The module integrates seamlessly with existing PowerShell automation scripts, allowing IT administrators to create user accounts, assign them to appropriate rooms, and send welcome messages all in a single automated workflow. Similarly, when employees depart, their accounts can be removed and they can be kicked from all rooms programmatically.

Beyond HR automation, HipChatAdmin excels at CI/CD pipeline integration for sending build notifications, deployment alerts, and system status updates to team rooms. The `Send-HipchatMessage` function supports color-coded messages and user notifications, making it perfect for alerting teams about build failures, successful deployments, or critical system events. All functions return status codes for error handling, enabling robust automation that can gracefully handle API failures and retry operations as needed.