====== Powershell connector configuration ======


==== Connector attributes ====
=== argumentStyle ===
Powershell connector calls powershell command and passes mapped attributes to it. There are four different ways of passing an argument to powershell script and they all correspond with possible configuration values below.

  * PARAMETERS\_DASH - Executes command in this template: COMMAND -PARAMETER_NAME VALUE

  * PARAMETERS\_SLASH - Executes command in this template: COMMAND /PARAMETER\_NAME:VALUE

  * VARIABLES - Executes command in this template: $PARAMETER_NAME=VALUE COMMAND 

  * HASH_MAP - This template exists only because powershell has problems passing multiple parameters to longer script blocks. It creates map as one input argument which will then contain all input parameters.

=== testScriptPath, authenticateScriptPath, searchScriptPath, deleteScriptPath, createScriptPath, updateScriptPath, syncScriptPath ===
These parameters contain path to scripts (on client machine) which will be executed when corresponding operation is invoked. Make sure that the script files are accessible.

=== useScriptCache ===
If true, then scripts, once read from drive, will be kept in memory for later reuse.

=== userName ===
Username used for authentication.

=== disableableCertificateChecks ===
If true, then connector will not check certificate validity.

=== script ResponseType ===
Only CSV is supported at the moment.

=== authenticationScheme ===
Specifies type of authentication to use. Possible values are:

  * Basic
  * NTLM
  * Negotiate
  * Kerberos
  * CredSSP

=== endpointUri ===
Uri contains information about protocol, port and hostname. Common URIs are

  * http://HOST:5985/wsman for http communication
  * https://HOST:5986/wsman for https comunication

=== domainName ===
Name of AD domain. It is used for authentication purposes.

=== multivaluedArgumentEncodingStrategy, multivalueEncodingSeparator ===
This is used for encoding multivalued parameters as arguments. Possible values are:

  * SINGLE\_VALUE\_ONLY - Uses only one value

  * MULTIVALUE\_WITH\_SEPARATOR - encodes multivalue as list of values separated by multivalueEncodingSeparator

  * MULTIVALUE - encodes multivalue using Java Arrays.toString method 


===== Setting-up WinRM =====

[[https://msdn.microsoft.com/en-us/library/aa384372(v=vs.85).aspx|Installation and Configuration for Windows Remote Management]]
===== MS Exchange =====
In order to use Powershell commands such as New-Mailbox, you need to add Exchange snapIn. Example powershell create script can be seen bellow.

<code>
param([string]$__UID__ = "", [string]$__NAME__ = "",[string]$SamAccountName = "", [string]$name = "", [string]$UserPrincipalName = "", [string]$__PASSWORD__)
Try{
    Add-PSSnapIn -Name Microsoft.Exchange.Management.PowerShell.SnapIn
    $secure_password = ConvertTo-SecureString -String $__PASSWORD__ -AsPlainText -Force
    New-Mailbox `
        -SamAccountName $SamAccountName `
        -Name $name `
        -UserPrincipalName $UserPrincipalName `
        -Password $secure_password `
        -Confirm:$false `
        -ErrorAction Stop | out-null -outvariable $mailbox

    Write-Host "__UID__,__NAME__"
    Write-Host "$SamAccountName,$SamAccountName"
} Catch {
    Write-Host "__ERROR__"
    Write-Host "$_.Exception.Message"
}
</code>

Another requirement is top use CredSSP authentication scheme.
===== Useful links =====
  * [[https://msdn.microsoft.com/cs-cz/library/windows/desktop/bb204773(v=vs.85).aspx|Set up CredSSP]]
  * [[https://www.sevecek.com/Lists/Posts/Post.aspx?ID=280|Guide on enabling winrm]]
  * [[https://www.sevecek.com/Lists/Posts/Post.aspx?ID=276|Troubleshooting winrm (in czech)]]
  * [[https://docs.microsoft.com/en-us/powershell/module/microsoft.wsman.management/enable-wsmancredssp?view=powershell-5.1|Official guide on how to enable CredSSP]]
  * [[http://www.hurryupandwait.io/blog/understanding-and-troubleshooting-winrm-connection-and-authentication-a-thrill-seekers-guide-to-adventure|Useful guide on winrm]]
  * [[https://github.com/ansible/ansible/blob/devel/examples/scripts/ConfigureRemotingForAnsible.ps1|Script to configure Winrm for Ansible]]
  * [[https://support.microsoft.com/en-us/help/2019527/how-to-configure-winrm-for-https|Winrm and https]]
  * [[https://rcmtech.wordpress.com/2016/10/21/fix-powershell-winrm-remote-connection-errors/|More troubleshooting]]