Public/New-SlackMessageAttachment.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
#Borrowed from https://github.com/jgigler/Powershell.Slack - thanks @jgigler et al!
function New-SlackMessageAttachment
{
    <#
    .SYNOPSIS
        Creates a rich notification (Attachment) to use in a Slack message.
 
    .DESCRIPTION
        Creates a rich notification (Attachment) to use in a Slack message.
 
        Used to create Atachment message payloads for Slack.
        Attachemnts are a way of crafting richly-formatted messages in Slack.
        They can be as simple as a single plain text message,
            to as complex as a multi-line message with pictures, links and tables.
 
    .PARAMETER Fallback
        A plain-text summary of the attachment. This text will be used in clients that don't show formatted text (eg. IRC, mobile notifications) and should not contain any markup.
 
    .PARAMETER Severity
        This value is used to color the border along the left side of the message attachment. This parameter cannot be used in conjunction with the "Color" parameter.
 
        Only good, bad and warning are accepted by this parameter.
 
    .PARAMETER Color
        This value is used to color the border along the left side of the message attachment.
 
        There are two options for this value:
 
            Use Hex Web Colors to define the color. e.g. -Color #FF0000
            Use $_PSSlackColorMap. e.g. -Color $_PSSlackColorMap.orange
 
            See $_PSSlackColorMap for a full list of colors.
 
        This parameter cannot be used in conjuction with the Severity Parameter.
 
    .PARAMETER Pretext
        This is optional text that appears above the message attachment block.
 
    .PARAMETER AuthorName
        Small text used to display the author's name.
 
    .PARAMETER AuthorLink
        A valid URL that will hyperlink the AuthorName text mentioned above.
 
        Will only work if AuthorName is present.
 
    .PARAMETER AuthorIcon
        A valid URL that displays a small 16x16px image to the left of the AuthorName text.
 
        Will only work if AuthorName is present.
 
    .PARAMETER Title
        The title is displayed as larger, bold text near the top of the message attachment.
 
    .PARAMETER TitleLink
        If the title link is specified then it turns the Title into a hyperlink that the user can click.
 
    .PARAMETER Text
        This is the main text in a message attachment, and can contain standard message markup.
        Not to be confused with Pretext which would appear above this.
 
    .PARAMETER ImageURL
        A valid URL to an image file that will be displayed inside a message attachment.
 
    .PARAMETER ThumbURL
        A valid URL to an image file that will be displayed as a thumbnail on the right side of a message attachment.
 
    .PARAMETER Fields
        One or more hashtables contained provided here will be displayed in a table inside the message attachment.
 
        Each hashtable provided must contain a "title" key and a "value" key.
        Optionally it may also contain "Short" which is a boolean parameter.
 
    .PARAMETER MarkDownFields
        One or more fields (text, pretext, fields) to enable markdown-esque formatting in.
 
        The formatting is described here: https://get.slack.help/hc/en-us/articles/202288908-How-can-I-add-formatting-to-my-messages-
 
    .PARAMETER ExistingAttachment
        One or more attachments to add this attachment to.
 
        Allows you to chain calls to this function:
            New-SlackMessageAttachment ... | New-SlackMessageAttachment ...
 
    .EXAMPLE
        # 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 $_PSSlackColorMap.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
 
        # Create a message attachment with details about an alert
        # Attach this to a slack message sending to the devnull channel
        # Send the newly created message using a token
 
    .EXAMPLE
        # 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 $_PSSlackColorMap.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
 
        # Create an attachment, create another attachment,
        # add these to a message,
        # and send with a token
 
    .EXAMPLE
 
        # 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 $_PSSlackColorMap.orange `
                                   -Title 'Failed to process account' `
                                   -Fields $Fields `
                                   -Fallback 'Your client is bad' |
            New-SlackMessage -Channel 'devnull' |
            Send-SlackMessage -Token $Token
 
        # 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
 
    .LINK
        https://github.com/RamblingCookieMonster/PSSlack
 
    .LINK
        https://api.slack.com/docs/attachments
 
    .LINK
        https://api.slack.com/methods/chat.postMessage
    #>

    [CmdletBinding(DefaultParameterSetName='Severity')]
    [OutputType([System.Collections.Hashtable])]
    Param
    (
        [Parameter(ValueFromPipeline = $True)]
        [PSTypeName('PSSlack.MessageAttachment')]
        $ExistingAttachment,

        [Parameter(Mandatory=$true,
                   Position=0)]
        [String]$Fallback,

        [Parameter(Mandatory=$false,
                   ParameterSetName='Severity')]
        [ValidateSet("good",
                     "warning",
                     "danger")]
        [String]$Severity,

        [Parameter(Mandatory=$false,
                   ParameterSetName='Color')]
        [Alias("Colour")]
        $Color,

        [String]$AuthorName,
        [String]$Pretext,
        [String]$AuthorLink,
        [String]$AuthorIcon,
        [String]$Title,
        [String]$TitleLink,
        [Parameter(Position=1)]
        [String]$Text,
        [String]$ImageURL,
        [String]$ThumbURL,
        [validatescript({
            foreach($key in $_.keys){
                if('title', 'short', 'value' -notcontains $key)
                {
                    throw "$Key is invalid, must be 'title', 'value', or 'short'"
                }
            }
            $true
        })]
        [System.Collections.Hashtable[]]$Fields,
        [validateset('text','pretext','fields')]
        [string[]]$MarkDownFields # https://get.slack.help/hc/en-us/articles/202288908-How-can-I-add-formatting-to-my-messages-
    )

    Process
    {
        #consolidate the colour and severity parameters for the API.
        if($PSCmdlet.ParameterSetName -like 'Severity')
        {
            $Color = $Severity
        }

        $Attachment = @{}
        switch($PSBoundParameters.Keys)
        {
            'fallback' {$Attachment.fallback = $Fallback}
            'color' {$Attachment.color = $Color}
            'pretext'{$Attachment.pretext = $Pretext}
            'AuthorName'{$Attachment.author_name = $AuthorName}
            'AuthorLink' {$Attachment.author_link = $AuthorLink}
            'AuthorIcon' { $Attachment.author_icon = $AuthorIcon}
            'Title' { $Attachment.title = $Title}
            'TitleLink' { $Attachment.title_link = $TitleLink }
            'Text' {$Attachment.text = $Text}
            'fields' { $Attachment.fields = $Fields } #Fields are defined by the user as an Array of HashTables.
            'ImageUrl' {$Attachment.image_url = $ImageURL}
            'ThumbUrl' {$Attachment.thumb_url = $ThumbURL}
            'MarkDownFields' {$Attachment.mrkdwn_in = @($MarkDownFields)}
        }

        Add-ObjectDetail -InputObject $Attachment -TypeName 'PSSlack.MessageAttachment' -Passthru $False

        if($ExistingAttachment)
        {
            @($ExistingAttachment) + $Attachment
        }
        else
        {
            $Attachment
        }
    }
}