ActionCard.ps1
|
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Scope='Function', Target='New*', Justification='New- Commands create definitions but do not change system state')] Param() Function Convert-ColorToHex { <# .Synopsis Turns a [System.Drawing.Color] into a hex string e.g. Red to ff0000 #> [cmdletbinding()] [outputType([String])] Param ( [Alias("Colour")] [System.Drawing.Color]$Color ) #return 2 hex digits for red, green and blue components "{0:x2}{1:x2}{2:x2}" -f $Color.r, $Color.g, $Color.b } Function New-CardImage { [cmdletbinding()] [Alias('CardImage')] [OutPuttype([Hashtable])] Param ( [parameter(Position=0, Mandatory=$true)] [alias('URI')] [string]$ImageURI, [string]$Title = 'Image' ) @{image = 'uri' ; title='title'} } Function New-CardSection { [CmdletBinding()] [alias('cardsection')] [OutputType([System.Collections.Specialized.OrderedDictionary])] Param ( [String]$Title = '' , [String]$ActivityImage = '' , [String]$ActivityTitle = '' , [String]$ActivitySubtitle = '' , [String]$ActivityText = '' , [bool]$StartGroup = $false , $Images ,# = @( @{image = 'uri1' ; title='title1'}, @{image = 'uri' ; title='title'}) , $Facts ,# = @( @{name1='value'}, @{name2='value2'}) , $HeroimageURI = 'HeroImageuri' , $HeroimageTitle = 'HeroImagetitle' ) $section = [ordered]@{ title = $Title startGroup = $StartGroup activityImage = $ActivityImage activityTitle = $ActivityTitle activitySubtitle = $ActivitySubtitle activityText = $ActivityText text = $Text } if ($HeroimageURI) { $heroimage = New-CardImage -ImageURI $HeroimageURI -title $HeroimageTitle $section['heroImage'] = $heroimage } if ($Facts) { $section['facts'] = $Facts } if ($Images) { $section['images'] = $Images} return $section } Function New-CardInput { <# .synopsis Creates the UI imput controls for message cards .Example > New-CardInput -InputType MultiLineText -ID 'Feedback' -Title "Let us know what you think" #Creates as a multi-line text box with the the ID "feedback" and a title #> [CmdletBinding()] [alias('cardinput')] Param ( [Parameter(ParameterSetName='SingleChoice',Mandatory=$true,Position=0)] [ValidateSet('Text','MultiLineText','DateOnly','DateTime')] [Alias('Type')] [string]$InputType, [Parameter(ParameterSetName='SingleChoice')] [int]$MaxLength, [Parameter(ParameterSetName='MultiChoice',Mandatory=$true)] [string[]]$Choices, [Parameter(ParameterSetName='MultiChoice')] [switch]$MultiSelect, [Parameter(ParameterSetName='SingleChoice',Mandatory=$true,Position=1)] [Parameter(ParameterSetName='MultiChoice',Mandatory=$true,Position=0)] [string]$ID = 'feedback' , [string]$Title, [string]$DefaultValue, [switch]$IsRequired ) if ($InputType -in ('Text','MultilineText')) { $InputControl = [ordered]@{ '@type' = 'TextInput' 'id' = $ID 'isRequired' = [bool]$IsRequired 'title' = $Title } if ($InputType -eq 'MultilineText') { $InputControl['isMultiline'] = $true } if ($MaxLength) { $InputControl['maxLength'] = $MaxLength } } elseif ($InputType -in ('DateTime','Date') ) { $InputControl = [ordered]@{ '@type' = 'DateInput' 'id' = $ID 'isRequired' = [bool]$IsRequired 'title' = $Title } if ($InputType -eq 'DateTime') {InputControl['includeTime'] = $true} } elseif ($Choices) { $InputControl = [ordered]@{ '@type' = 'MultichoiceInput' 'id' = $ID 'isRequired' = [bool]$IsRequired 'title' = $Title 'choices' = @() } if ($MultiSelect) {$InputControl['isMultiSelect'] = $true} foreach ($c in $choices) { if ($c -is [string]) { $InputControl['choices'] += @{'display' = $c ; 'value' = $c} } elseif ($c.display -and $c.value) { $InputControl['choices'] += @{'display' = $c.display ; 'value' = $c.value} } else {throw 'Invalid value for a choice.'; return} } } if ($DefaultValue) { $InputControl['value'] = $DefaultValue } return $InputControl } Function New-CardActionHttpPost { <# .Synopsis Creates an Http Post action for a message card .Description See https://docs.microsoft.com/en-gb/outlook/actionable-messages/message-card-reference#httppost-action .Example New-CardActionHttpPost -Name 'Send Feedback' -Target 'http://feedback.contoso.com' -Primary Creates a button for a form which contains which will post to the URL. need more params to be useful! #> [cmdletbinding()] [Alias("HttpPostAction")] param( [Parameter(Mandatory=$true,Position=0)] $Name , [Parameter(Mandatory=$true,Position=1)] $Target , [string[]]$Headers , $Body , [ValidateSet('application/json', 'application/x-www-form-urlencoded')] $ContentType, [switch]$Primary ) $action = [ordered]@{ '@type' = 'HttpPOST' 'name' = $Name 'target' = $target } if ($Primary) {$action['isPrimary'] = $true} if ($Headers) {$action['headers'] = $Headers} if ($Body) {$action['body'] = $Body} if ($ContentType) {$action['bodyContentType'] = $ContentType} return $action } Function New-CardActionOpenUri { <# .Synopsis Creates a button on a message card to open a link .Example New-CardActionOpenUri -Name 'Learn more' -Targets 'https://docs.microsoft.com/outlook/actionable-messages' This creates an action which a appers as button on the card [Learn More] clicking it opens the link #> [cmdletbinding()] [Alias("OpenUriAction")] param( [Parameter(Mandatory=$true,Position=0)] $Name , [Parameter(Mandatory=$true,Position=1)] $Targets , [switch]$Primary ) $Action = [ordered]@{ '@type' = 'OpenUri' 'name' = $Name 'targets' = @() } if ($Primary) {$Action['isPrimary']= $true} foreach ($t in $Targets) { if ($t -is [string]) { $Action['targets'] += @{'os' = 'default' ; 'uri' = $t} } elseif ($t.os -and $t.uri) { $Action['targets'] += @{'os' = $t.os ; 'uri' = $t.uri} } else {throw 'Invalid value for a target.'; return} } return $action } Function New-CardActionCard { <# .Synopsis Creates an "Action card" action for a message card .Description Actions are presented on the card as buttons the user can click For an "action card" action this reveals a 'sub-card' with input controls and action buttons. The buttons must be Http posts or Open URI types, they can't be nest action cards. .Example > >$inputs = @() >$inputs += New-CardInput ... >$actions = New-CardActionHttpPost -Name 'Send Feedback' -Target 'http://....' >$actioncard = New-CardActionCard -Name 'Send Feedback' -Inputs $inputs -Actions $actions This example starts by creating the input fields for the Action card It the definies a single action - the both these steps have been truncated for brevity The final step creates the action card. This will then be passed in the Actions parameter for New-Message card. The post action will usually need to send a some of the input in the body of the post see under 'Input value substitution' in https://docs.microsoft.com/en-gb/outlook/actionable-messages/message-card-reference #> [cmdletbinding()] [Alias("CardAction")] param( [Parameter(Mandatory=$true,Position=0)] $Name , $Inputs, $Actions ) [ordered]@{ '@type' = 'ActionCard' 'name' = $Name 'inputs' = @() + $Inputs 'actions' = @() + $Actions } } Function New-MessageCard { <# .Synopsis Creates a message card and either posts to a webhook or returns it for examination/tweaking. .Example > >new-messageCard -WebHookURI $hookUri -Title 'From powershell to teams using webhooks' -Text @' **James** did a _crane job_ on the logo! '@ Creates a simple card with a title and text using mark down to display a logo. This card is posted to the Webhook in $webhooURI. .Description See https://docs.microsoft.com/en-gb/outlook/actionable-messages/message-card-reference #> [cmdletbinding()] [Alias("MessageCard")] param( #The title for the card. The font for this is fixed. [string]$Title = 'Visit the Outlook Dev Portal' , #The body text for the card. This supports markdown, which you can use to include images. [String]$Text = '', #Short version of the text. [string]$Summary = '', [system.drawing.color]$Themecolor, $ThemeColorHex ,# ='0072C6', $Actions , [switch]$AsHashTable, [String]$WebHookURI ) #Build the card as a HashTable. Make it ordered when we connvert to JSON the items don't look in a strange order $CardSettings = [ordered]@{ '@context' = 'https://schema.org/extensions' '@type' = 'MessageCard' 'title' = $Title 'text' = $Text 'summary' = $Summary } #Add optional items color is a hex string but we'll take and convert system colors. if ($ThemeColorHex) {$cardSettings['themeColor'] = $ThemeColorHex} elseif ($Themecolor) {$cardSettings['themeColor'] = Convert-ColorToHex -Color $Themecolor} if ($Actions) {$cardSettings['potentialAction'] = @() + $Actions} #And either post to a webhook or return the results. if ($AsHashTable) {return $cardSettings} elseif ($WebHookURI) { Invoke-RestMethod -Method Post -Uri $WebHookURI -ContentType "application/json" -Body (ConvertTo-Json $cardSettings -Depth 99) } else {ConvertTo-Json $cardSettings -Depth 99} } ############## Example #################### # Your Web hook here # $hookUri = 'https://outlook.office.com/webhook/<<teamGuid>>@<<org GUID>>/IncomingWebhook/<<id>>/<<creator guid>>' <# First we can use these with the commands being written out in max-verbose. and storing in variables $inputs = New-CardInput -InputType MultiLineText -ID 'Feedback' -Title "Let us know what you think" $actions = New-CardActionHttpPost -Name 'Send Feedback' -Target 'http://....' -Primary $actioncard = New-CardActionCard -Name 'Send Feedback' -Inputs $inputs -Actions $actions $link = New-CardActionOpenUri -Name 'Learn more' -Targets 'https://docs.microsoft.com/outlook/actionable-messages' $actions = @($link,$actionCard) $json = New-MessageCard -Actions $actions -Title 'Visit the Outlook Dev Portal' -Text 'Click **Learn More** to learn more about Actionable Messages!' #The same but using aliases and being terse with parameters. $inputs = Cardinput MultiLineText feedback -Title "Let us know what you think" $actions = HttpPostAction 'Send Feeback' 'http://....' -Primary $actioncard = CardAction 'Send Feedback' -Inputs $inputs -Actions $actions $link = OpenUriAction 'Learn more' 'https://docs.microsoft.com/outlook/actionable-messages' $json = MessageCard 'Visit the Outlook Dev Portal' 'Click **Learn More** to learn more about Actionable Messages!' -Actions $link,$actioncard #And the same again but with attitude of "We don't need no stinking variables" MessageCard -Title 'Visit the Outlook Dev Portal' -Text @' **James** did a _crane job_ on the logo! '@ -Actions @( (CardAction "Feedback" -Inputs (Cardinput MultiLineText feedback -Title "Let us know, what do you think?") ` -Actions (HttpPostAction 'Send us feedback' 'http://....' -Primary) ) , (OpenUriAction 'Learn more' 'https://docs.microsoft.com/outlook/actionable-messages') ) | clip # paste into https://messagecardplayground.azurewebsites.net/ #> |