Public/New-RyverAction.ps1
|
function New-RyverAction { <# .SYNOPSIS Creates an action to use in a Ryver message attachment. .DESCRIPTION Creates an action to use in a Ryver message attachment. Used to create actions for Ryver message attachments. .INPUTS System.String[] .NOTES - Troy Lindsay - Twitter: @troylindsay42 - GitHub: tlindsay42 .EXAMPLE # This is a simple example illustrating some common options # when constructing an action $acknowledge = @{ Name = 'Acknowledge' Text = 'Acknowledge' Type = 'button' } $dismiss = @{ Name = 'Dismiss' Text = 'Dismiss' Type = 'button' } $actions = New-RyverAction @acknowledge | New-RyverAction @dismiss $splat = @{ Color = $Script:PSRyverColorMap.Orange Title = 'Failed to process account' Actions = $actions Fallback = 'Your client is bad' } New-RyverMessageAttachment @splat | New-RyverMessage | Send-RyverMessage -Uri 'https://hooks.ryver.com/services/SomeUniqueId' # We create an action object with an 'Acknowledge' button and a # Dismiss button. # Creates an attachment with the button created in the action object # Creates a message from that attachment and sents it with a URI .LINK https://tlindsay42.github.io/PSRyver/Public/New-RyverAction/ .LINK https://github.com/tlindsay42/PSRyver/blob/master/PSRyver/Public/New-RyverAction.ps1 .LINK https://api.ryver.com/docs/interactive-message-field-guide#action_fields #> [CmdletBinding( HelpUri = 'https://tlindsay42.github.io/PSRyver/Public/New-RyverAction/' )] [OutputType( [PSCustomObject[]] )] [OutputType( [PSCustomObject] )] param ( <# Provide a string to give this specific action a name. The name will be returned to your Action URL along with the message's callback_id when this action is invoked. Use it to identify this particular response path. If multiple actions share the same name, only one of them can be in a triggered state. #> [Parameter( Mandatory = $true, Position = 0 )] [String] $Name, <# The user-facing label for the message button or menu representing this action. Cannot contain markup. Best to keep these short and decisive. Use a maximum of 30 characters or so for best results across form factors. #> [Parameter( Mandatory = $true, Position = 1 )] [ValidateLength( 1, 30 )] [String] $Text, <# Provide button when this action is a message button or provide select when the action is a message menu. #> [Parameter( Mandatory = $true, Position = 2 )] [ValidateSet( 'button', 'select' )] [String] $Type, <# Provide a string identifying this specific action. It will be sent to your Action URL along with the name and attachment's callback_id. If providing multiple actions with the same name, value can be strategically used to differentiate intent. Your value may contain up to 3000 characters. #> [Parameter( Position = 3 )] [ValidateLength( 0, 3000 )] [String] $Value, <# If you provide a JSON hash of confirmation fields, your button or menu will pop up a dialog with your indicated text and choices, giving them one last chance to avoid a destructive action or other undesired outcome. #> [Parameter( Position = 4 )] [PSTypeName( 'PSRyver.ActionConfirmation' )] $Confirmation, <# Used only with message buttons, this decorates buttons with extra visual importance, which is especially useful when providing logical default action or highlighting a destructive activity. - default: Yes, it's the default. Buttons will look simple. - primary: Use this sparingly, when the button represents a key action to accomplish. You should probably only ever have one primary button within a set. - danger: Use this when the consequence of the button click will result in the destruction of something, like a piece of data stored on your servers. Use even more sparingly than primary. #> [Parameter( Position = 5 )] [ValidateSet( 'default', 'primary', 'danger' )] [String] $Style, <# Used only with message menus. The individual options to appear in this menu, provided as an array of option fields. Required when data_source is static or otherwise unspecified. A maximum of 100 options can be provided in each menu. Options can be created using the New-RyverActionOption command. #> [Parameter( Position = 6 )] [PSTypeName( 'PSRyver.ActionOption' )] $Options, <# One or more actions to add this action to. Allows you to chain calls to this function: New-RyverAction ... | New-RyverAction ... #> [Parameter( Mandatory = $true, Position = 7, ValueFromPipeline = $true )] [PSTypeName( 'PSRyver.Action' )] $ExistingAction ) begin { $function = $MyInvocation.MyCommand.Name Write-Verbose -Message ( "Beginning: '${function}' with ParameterSetName '$( $PSCmdlet.ParameterSetName )' and Parameters: " + ( $PSBoundParameters | Remove-SensitiveData | Format-Table -AutoSize | Out-String ) ) } process { $action = @{} switch ( $PSBoundParameters.Keys ) { 'Name' { $action.Name = $Name } 'Text' { $action.Text = $Text } 'Type' { $action.Type = $Type } 'Value' { $action.Value = $Value } 'Confirmation' { $action.Confirm = $Confirmation } 'Style' { $action.Style = $Style } 'Options' { $action.Options = $Options } } Add-ObjectDetail -InputObject $action -TypeName 'PSRyver.Action' -Passthru $false if ( $ExistingAction -eq $true ) { @( $ExistingAction ) + $action } else { $action } } end { Write-Verbose -Message "Ending: '${function}'." } } |