external help file: PoshBot-help.xml Module Name: poshbot online version: schema: 2.0.0


New-PoshBotConfiguration

SYNOPSIS

Creates a new PoshBot configuration object.

SYNTAX

New-PoshBotConfiguration [[-Name] <String>] [[-ConfigurationDirectory] <String>] [[-LogDirectory] <String>]
 [[-PluginDirectory] <String>] [[-PluginRepository] <String[]>] [[-ModuleManifestsToLoad] <String[]>]
 [[-LogLevel] <LogLevel>] [[-MaxLogSizeMB] <Int32>] [[-MaxLogsToKeep] <Int32>] [[-LogCommandHistory] <Boolean>]
 [[-CommandHistoryMaxLogSizeMB] <Int32>] [[-CommandHistoryMaxLogsToKeep] <Int32>]
 [[-BackendConfiguration] <Hashtable>] [[-PluginConfiguration] <Hashtable>] [[-BotAdmins] <String[]>]
 [[-CommandPrefix] <Char>] [[-AlternateCommandPrefixes] <String[]>]
 [[-AlternateCommandPrefixSeperators] <Char[]>] [[-SendCommandResponseToPrivate] <String[]>]
 [[-MuteUnknownCommand] <Boolean>] [[-AddCommandReactions] <Boolean>] [[-ApprovalExpireMinutes] <Int32>]
 [-DisallowDMs] [[-FormatEnumerationLimitOverride] <Int32>] [[-ApprovalCommandConfigurations] <Hashtable[]>]
 [[-ChannelRules] <Hashtable[]>] [[-PreReceiveMiddlewareHooks] <MiddlewareHook[]>]
 [[-PostReceiveMiddlewareHooks] <MiddlewareHook[]>] [[-PreExecuteMiddlewareHooks] <MiddlewareHook[]>]
 [[-PreResponseMiddlewareHooks] <MiddlewareHook[]>] [[-PostResponseMiddlewareHooks] <MiddlewareHook[]>]
 [<CommonParameters>]

DESCRIPTION

Creates a new PoshBot configuration object.

EXAMPLES

EXAMPLE 1

New-PoshBotConfiguration -Name Cherry2000 -AlternateCommandPrefixes @('Cherry', 'Sam')

Name : Cherry2000 ConfigurationDirectory : C:\Users\brand.poshbot LogDirectory : C:\Users\brand.poshbot PluginDirectory : C:\Users\brand.poshbot PluginRepository : {PSGallery} ModuleManifestsToLoad : {} LogLevel : Verbose BackendConfiguration : {} PluginConfiguration : {} BotAdmins : {} CommandPrefix : ! AlternateCommandPrefixes : {Cherry, Sam} AlternateCommandPrefixSeperators : {:, ,, ;} SendCommandResponseToPrivate : {} MuteUnknownCommand : False AddCommandReactions : True ApprovalConfiguration : ApprovalConfiguration

Create a new PoshBot configuration with default values except for the bot name and alternate command prefixes that it will listen for.

EXAMPLE 2

$backend = @{Name = 'SlackBackend'; Token = 'xoxb-569733935137-njOPkyBThqOTTUnCZb7tZpKK'}

PS C:\> $botParams = @{ Name = 'HAL9000' LogLevel = 'Info' BotAdmins = @('JoeUser') BackendConfiguration = $backend } PS C:\> $myBotConfig = New-PoshBotConfiguration @botParams PS C:\> $myBotConfig

Name : HAL9000 ConfigurationDirectory : C:\Users\brand.poshbot LogDirectory : C:\Users\brand.poshbot PluginDirectory : C:\Users\brand.poshbot PluginRepository : {MyLocalRepo} ModuleManifestsToLoad : {} LogLevel : Info BackendConfiguration : {} PluginConfiguration : {} BotAdmins : {JoeUser} CommandPrefix : ! AlternateCommandPrefixes : {poshbot} AlternateCommandPrefixSeperators : {:, ,, ;} SendCommandResponseToPrivate : {} MuteUnknownCommand : False AddCommandReactions : True ApprovalConfiguration : ApprovalConfiguration

PS C:\> $myBotConfig | Start-PoshBot -AsJob

Create a new PoshBot configuration with a Slack backend. Slack's backend only requires a bot token to be specified. Ensure the person with Slack handle 'JoeUser' is a bot admin.

PARAMETERS

-Name

The name the bot instance will be known as.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: PoshBot
Accept pipeline input: False
Accept wildcard characters: False

-ConfigurationDirectory

The directory when PoshBot configuration data will be written to.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: $script:defaultPoshBotDir
Accept pipeline input: False
Accept wildcard characters: False

-LogDirectory

The log directory logs will be written to.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: $script:defaultPoshBotDir
Accept pipeline input: False
Accept wildcard characters: False

-PluginDirectory

The directory PoshBot will look for PowerShell modules. This path will be prepended to your $env:PSModulePath.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: $script:defaultPoshBotDir
Accept pipeline input: False
Accept wildcard characters: False

-PluginRepository

One or more PowerShell repositories to look in when installing new plugins (modules). These will be the repository name(s) as found in Get-PSRepository.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: @('PSGallery')
Accept pipeline input: False
Accept wildcard characters: False

-ModuleManifestsToLoad

One or more paths to module manifest (.psd1) files. These modules will be automatically loaded when PoshBot starts.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-LogLevel

The level of logging that PoshBot will do.

Type: LogLevel
Parameter Sets: (All)
Aliases:
Accepted values: Info, Verbose, Debug

Required: False
Position: 7
Default value: Verbose
Accept pipeline input: False
Accept wildcard characters: False

-MaxLogSizeMB

The maximum log file size in megabytes.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 8
Default value: 10
Accept pipeline input: False
Accept wildcard characters: False

-MaxLogsToKeep

The maximum number of logs to keep. Once this value is reached, logs will start rotating.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 9
Default value: 5
Accept pipeline input: False
Accept wildcard characters: False

-LogCommandHistory

Enable command history to be logged to a separate file for convenience. The default it $true

Type: Boolean
Parameter Sets: (All)
Aliases:

Required: False
Position: 10
Default value: True
Accept pipeline input: False
Accept wildcard characters: False

-CommandHistoryMaxLogSizeMB

The maximum log file size for the command history

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 11
Default value: 10
Accept pipeline input: False
Accept wildcard characters: False

-CommandHistoryMaxLogsToKeep

The maximum number of logs to keep for command history. Once this value is reached, the logs will start rotating.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 12
Default value: 5
Accept pipeline input: False
Accept wildcard characters: False

-BackendConfiguration

A hashtable of configuration options required by the backend chat network implementation.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: 13
Default value: @{}
Accept pipeline input: False
Accept wildcard characters: False

-PluginConfiguration

A hashtable of configuration options used by the various plugins (modules) that are installed in PoshBot. Each key in the hashtable must be the name of a plugin. The value of that hashtable item will be another hashtable with each key matching a parameter name in one or more commands of that module. A plugin command can specifiy that a parameter gets its value from this configuration by applying the custom attribute [PoshBot.FromConfig()] on the parameter.

The function below is stating that the parameter $MyParam will get its value from the plugin configuration. The user running this command in PoshBot does not need to specify this parameter. PoshBot will dynamically resolve and apply the matching value from the plugin configuration when the command is executed.

function Get-Foo { [cmdletbinding()] param( [PoshBot.FromConfig()] [parameter(mandatory)] [string]$MyParam )

Write-Output $MyParam

}

If the function below was part of the Demo plugin, PoshBot will look in the plugin configuration for a key matching Demo and a child key matching $MyParam.

Example plugin configuration: @{ Demo = @{ MyParam = 'bar' } }

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: 14
Default value: @{}
Accept pipeline input: False
Accept wildcard characters: False

-BotAdmins

An array of chat handles that will be granted admin rights in PoshBot. Any user in this array will have full rights in PoshBot. At startup, PoshBot will resolve these handles into IDs given by the chat network.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 15
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-CommandPrefix

The prefix (single character) that must be specified in front of a command in order for PoshBot to recognize the chat message as a bot command.

!get-foo --value bar

Type: Char
Parameter Sets: (All)
Aliases:

Required: False
Position: 16
Default value: !
Accept pipeline input: False
Accept wildcard characters: False

-AlternateCommandPrefixes

Some users may want to specify alternate prefixes when calling bot comamnds. Use this parameter to specify an array of words that PoshBot will also check when parsing a chat message.

bender get-foo --value bar

hal open-doors --type pod

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 17
Default value: @('poshbot')
Accept pipeline input: False
Accept wildcard characters: False

-AlternateCommandPrefixSeperators

An array of characters that can also ben used when referencing bot commands.

bender, get-foo --value bar

hal; open-doors --type pod

Type: Char[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 18
Default value: @(':', ',', ';')
Accept pipeline input: False
Accept wildcard characters: False

-SendCommandResponseToPrivate

A list of fully qualified (\<PluginName>:\<CommandName>) plugin commands that will have their responses redirected back to a direct message channel with the calling user rather than a shared channel.

@( demo:get-foo network:ping )

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 19
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-MuteUnknownCommand

Instead of PoshBot returning a warning message when it is unable to find a command, use this to parameter to tell PoshBot to return nothing.

Type: Boolean
Parameter Sets: (All)
Aliases:

Required: False
Position: 20
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-AddCommandReactions

Add reactions to a chat message indicating the command is being executed, has succeeded, or failed.

Type: Boolean
Parameter Sets: (All)
Aliases:

Required: False
Position: 21
Default value: True
Accept pipeline input: False
Accept wildcard characters: False

-ApprovalExpireMinutes

The amount of time (minutes) that a command the requires approval will be pending until it expires.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 22
Default value: 30
Accept pipeline input: False
Accept wildcard characters: False

-DisallowDMs

Disallow DMs (direct messages) with the bot. If a user tries to DM the bot it will be ignored.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-FormatEnumerationLimitOverride

Set $FormatEnumerationLimit to this. Defaults to unlimited (-1)

Determines how many enumerated items are included in a display. This variable does not affect the underlying objects; just the display. When the value of $FormatEnumerationLimit is less than the number of enumerated items, PowerShell adds an ellipsis (...) to indicate items not shown.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 23
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False

-ApprovalCommandConfigurations

Array of hashtables containing command approval configurations.

@( @{ Expression = 'MyModule:Execute-Deploy:' Groups = 'platform-admins' PeerApproval = $true } @{ Expression = 'MyModule:Deploy-HRApp:' Groups = @('platform-managers', 'hr-managers') PeerApproval = $true } )

Type: Hashtable[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 24
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-ChannelRules

Array of channels rules that control what plugin commands are allowed in a channel. Wildcards are supported. Channel names that match against this list will be allowed to have Poshbot commands executed in them.

Internally this uses the `-like` comparison operator, not `-match`. Regexes are not allowed.

For best results, list channels and commands from most specific to least specific. PoshBot will evaluate the first match found.

Note that the bot will still receive messages from all channels it is a member of. These message MAY be logged depending on your configured logging level.

Example value: @( # Only allow builtin commands in the 'botadmin' channel @{ Channel = 'botadmin' IncludeCommands = @('builtin:') ExcludeCommands = @() } # Exclude builtin commands from any "projectX" channel @{ Channel = 'projectx' IncludeCommands = @('') ExcludeCommands = @('builtin:') } # It's the wild west in random, except giphy :) @{ Channel = 'random' IncludeCommands = @('') ExcludeCommands = @('giphy') } # All commands are otherwise allowed @{ Channel = '' IncludeCommands = @('') ExcludeCommands = @() } )

Type: Hashtable[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 25
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-PreReceiveMiddlewareHooks

Array of middleware scriptblocks that will run before PoshBot "receives" the message from the backend implementation. This middleware will receive the original message sent from the chat network and have a chance to modify, analyze, and optionally drop the message before PoshBot continues processing it.

Type: MiddlewareHook[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 26
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-PostReceiveMiddlewareHooks

Array of middleware scriptblocks that will run after a message is "received" from the backend implementation. This middleware runs after messages have been parsed and matched with a registered command in PoshBot.

Type: MiddlewareHook[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 27
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-PreExecuteMiddlewareHooks

Array of middleware scriptblocks that will run before a command is executed. This middleware is a good spot to run extra authentication or validation processes before commands are executed.

Type: MiddlewareHook[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 28
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-PreResponseMiddlewareHooks

Array of middleware scriptblocks that will run before command responses are sent to the backend implementation. This middleware is a good spot for modifying or sanitizing responses before they are sent to the chat network.

Type: MiddlewareHook[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 29
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-PostResponseMiddlewareHooks

Array of middleware scriptblocks that will run after command responses have been sent to the backend implementation. This middleware runs after all processing is complete for a command and is a good spot for additional custom logging.

Type: MiddlewareHook[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 30
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

OUTPUTS

BotConfiguration

NOTES

Get-PoshBotConfiguration

Save-PoshBotConfiguration

New-PoshBotInstance

Start-PoshBot