Skip to content

simonfagerholm/PSSlack

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build status

PSSlack

This is a quick and dirty module to interact with the Slack API.

Pull requests and other contributions would be welcome!

Instructions

# One time setup
    # Download the repository
    # Unblock the zip
    # Extract the PSSlack folder to a module path (e.g. $env:USERPROFILE\Documents\WindowsPowerShell\Modules\)
# Or, with PowerShell 5 or later or PowerShellGet:
    Install-Module PSSlack

# Import the module.
    Import-Module PSSlack    #Alternatively, Import-Module \\Path\To\PSSlack

# Get commands in the module
    Get-Command -Module PSSlack

# Get help
    Get-Help Send-SlackMessage -Full
    Get-Help about_PSSlack

Prerequisites

Examples

Send a Simple Slack Message

# This example shows a crudely crafted message without any attachments,
# using parameters from Send-SlackMessage to construct the message.

#Previously set up Uri from https://<YOUR TEAM>.slack.com/apps/A0F7XDUAZ
$Uri = "Some incoming webhook uri from Slack"

Send-SlackMessage -Uri $Uri `
                  -Channel '@wframe' `
                  -Parse full `
                  -Text 'Hello @wframe, join me in #devnull!'

# Send a message to @wframe (not a channel), parsing the text to linkify usernames and channels

      Simple Send-SlackMessage

Search for a Slack Message

# Search for a message containing PowerShell, sorting results by timestamp

Find-SlackMessage -Token $Token `
                  -Query 'PowerShell' `
                  -SortBy timestamp

      Find Message

# Search for a message containing PowerShell
# Results are sorted by best match by default
# Notice the extra properties and previous/next messages

Find-SlackMessage -Token $Token `
                  -Query 'PowerShell' |
    Select-Object -Property *

      Find Message Select All

You could use this simply to search Slack from the CLI, or in an automated solution that might avoid posting if certain content is already found in Slack.

Send a Richer Slack Message

# This is a simple example illustrating some common options
# when constructing a message attachment
# giving you a richer message

$Token = 'A token. maybe from https://api.slack.com/docs/oauth-test-tokens'

New-SlackMessageAttachment -Color $([System.Drawing.Color]::red) `
                           -Title 'The System Is Down' `
                           -TitleLink https://www.youtube.com/watch?v=TmpRs7xN06Q `
                           -Text 'Please Do The Needful' `
                           -Pretext 'Everything is broken' `
                           -AuthorName 'SCOM Bot' `
                           -AuthorIcon 'http://ramblingcookiemonster.github.io/images/tools/wrench.png' `
                           -Fallback 'Your client is bad' |
    New-SlackMessage -Channel '@wframe' `
                     -IconEmoji :bomb: |
    Send-SlackMessage -Token $Token

      Rich messages

Notice that the title is clickable. You might link to...

  • The alert in question
  • A logging solution query
  • A dashboard
  • Some other contextual link
  • Strongbad

Send Multiple Slack Attachments

# This example demonstrates that you can chain new attachments
# together to form a multi-attachment message

$Token = 'A token. maybe from https://api.slack.com/docs/oauth-test-tokens'

New-SlackMessageAttachment -Color $_PSSlackColorMap.red `
                           -Title 'The System Is Down' `
                           -TitleLink https://www.youtube.com/watch?v=TmpRs7xN06Q `
                           -Text 'Everybody panic!' `
                           -Pretext 'Everything is broken' `
                           -Fallback 'Your client is bad' |
    New-SlackMessageAttachment -Color $([System.Drawing.Color]::Orange) `
                               -Title 'The Other System Is Down' `
                               -TitleLink https://www.youtube.com/watch?v=TmpRs7xN06Q `
                               -Text 'Please Do The Needful' `
                               -Fallback 'Your client is bad' |
    New-SlackMessage -Channel '@wframe' `
                     -IconEmoji :bomb: `
                     -AsUser `
                     -Username 'SCOM Bot' |
    Send-SlackMessage -Token $Token

      Multiple Attachments

Notice that we can chain multiple New-SlackMessageAttachments together.

Send a Table of Key Value Pairs

# This example illustrates a pattern where you might
# want to send output from a script; you might
# include errors, successful items, or other output

# Pretend we're in a script, and caught an exception of some sort
$Fail = [pscustomobject]@{
    samaccountname = 'bob'
    operation = 'Remove privileges'
    status = "An error message"
    timestamp = (Get-Date).ToString()
}

# Create an array from the properties in our fail object
$Fields = @()
foreach($Prop in $Fail.psobject.Properties.Name)
{
    $Fields += @{
        title = $Prop
        value = $Fail.$Prop
        short = $true
    }
}

$Token = 'A token. maybe from https://api.slack.com/docs/oauth-test-tokens'

# Construct and send the message!
New-SlackMessageAttachment -Color $([System.Drawing.Color]::Orange) `
                           -Title 'Failed to process account' `
                           -Fields $Fields `
                           -Fallback 'Your client is bad' |
    New-SlackMessage -Channel 'devnull' |
    Send-SlackMessage -Uri $uri

# We build up a pretend error object, and send each property to a 'Fields' array
# Creates an attachment with the fields from our error
# Creates a message fromthat attachment and sents it with a uri

      Fields

Store and Retrieve Configs

To save time and typing, you can save a token or uri to a config file (protected via DPAPI) and a module variable.

This is used as the default for commands, and is reloaded if you open a new PowerShell session.

# Save a Uri and Token.
# If both are specified, token takes precedence.
Set-PSSlackConfig -Uri 'SomeSlackUri' -Token 'SomeSlackToken'

# Read the current cofig
Get-PSSlackConfig

Notes

Currently evaluating .NET Core / Cross-platform functionality. The following will not work initially:

  • Serialization of URIs and tokens via Set-PSSlackConfig. Set these values per-session if needed
  • [System.Drawing.Color]::SomeColor shortcut. Use the provided $_PSSlackColorMap hash to simplify this. E.g. $_PSSlackColorMap.red

There are a good number of Slack functions out there, including jgigler's PowerShell.Slack and Steven Murawski's Slack. We borrowed some ideas and code from these - thank you!

If you want to go beyond interacting with the Slack API, you might consider using a bot

About

Fork of PSSlack, waiting for PRs to be merged

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • PowerShell 100.0%