Merge pull request #49 from ZertoPublic/New-Token

Add Function to Obtain a Pairing Token

RELEASENOTES.md

@@ -4,6 +4,7 @@
 
 * [Zerto version 7.5 has been released.](https://s3.amazonaws.com/zertodownload_docs/Latest/Zerto%20Virtual%20Replication%20Release%20Notes.pdf) As part of this release Zerto has added API functionality that requires the following updates.
   * A token is now required to pair two sites together. The need is discussed in [Issue 46](https://github.com/ZertoPublic/ZertoApiWrapper/issues/46). To implement this change a `-token` parameter has been added to the `Add-ZertoPeerSite` function.
+  * A new function has been added; `New-ZertoPairingToken`. This function will allow users to generate a pairing authentication token from the target ZVM to be used in the pairing process. [Issue 47](https://github.com/ZertoPublic/ZertoApiWrapper/issues) covers additional details.
 
 ### Zerto Analytics
 

Tests/Public/Mocks/PairingToken.json

@@ -0,0 +1,4 @@
+{
+  "Token": "TH15ISN0T4R3AL70KEN",
+  "UtcExpirationDate": "10/09/2019 12:55 PM"
+}

Tests/Public/New-ZertoPairingToken.Tests.ps1

@@ -0,0 +1,51 @@
+#Requires -Modules Pester
+$global:here = (Split-Path -Parent $MyInvocation.MyCommand.Path)
+$global:function = ((Split-Path -leaf $MyInvocation.MyCommand.Path).Split('.'))[0]
+
+Describe $global:function -Tag 'Unit', 'Source', 'Built' {
+    BeforeAll {
+        $script:ScriptBlock = (Get-Command $global:function).ScriptBlock
+    }
+
+    Context "$global:function::Parameter Unit Tests" {
+        It "$global:function should have exactly 13 parameters defined" {
+            (Get-Command $global:function).Parameters.Count | Should -Be 13
+        }
+
+        It "Supports 'SupportsShouldProcess'" {
+            Get-Command $global:function | Should -HaveParameter WhatIf
+            Get-Command $global:function | Should -HaveParameter Confirm
+            $script:ScriptBlock | Should -match 'SupportsShouldProcess'
+            $script:ScriptBlock | Should -match '\$PSCmdlet\.ShouldProcess\(.+\)'
+        }
+    }
+
+    Context "$global:function::Parameter Functional Tests" {
+        Mock -ModuleName ZertoApiWrapper -CommandName Invoke-ZertoRestRequest {
+            return (Get-Content -Raw "$global:here\Mocks\PairingToken.json" | ConvertFrom-Json)
+        }
+
+        It "Returns a Token" {
+            $Token = New-ZertoPairingToken
+            $Token | Should -Not -Be $Null
+            $Token.Token | Should -Be "TH15ISN0T4R3AL70KEN"
+        }
+
+        It "Returns a ExpirationDate" {
+            $Token = New-ZertoPairingToken
+            $Token | Should -Not -Be $Null
+            $Token.UtcExpirationDate | Should -Be "10/09/2019 12:55 PM"
+        }
+
+        It "Does not return a taskId if '-whatif' is used" {
+            $results = New-ZertoPairingToken -WhatIf
+            $results | Should -BeNullOrEmpty
+        }
+
+        Assert-MockCalled -ModuleName ZertoApiWrapper -CommandName Invoke-ZertoRestRequest -Exactly 2
+
+    }
+}
+
+Remove-Variable -Name here -Scope Global
+Remove-Variable -Name function -Scope Global

ZertoApiWrapper/Public/New-ZertoPairingToken.ps1

@@ -0,0 +1,23 @@
+<# .ExternalHelp ./en-us/ZertoApiWrapper-help.xml #>
+function New-ZertoPairingToken {
+    [CmdletBinding(SupportsShouldProcess = $true)]
+    param (
+
+    )
+
+    begin {
+
+    }
+
+    process {
+        $uri = "peersites/generatetoken"
+        $body = @{ }
+        if ($PSCmdlet.ShouldProcess("Obtaining Pairing token from $script:zvmServer")) {
+            Invoke-ZertoRestRequest -uri $uri -method "POST" -body $($body | ConvertTo-Json)
+        }
+    }
+
+    end {
+
+    }
+}

docs/New-ZertoPairingToken.md

@@ -0,0 +1,77 @@
+---
+external help file: ZertoApiWrapper-help.xml
+Module Name: ZertoApiWrapper
+online version: https://github.com/ZertoPublic/ZertoApiWrapper/blob/master/docs/New-ZertoPairingToken.md
+schema: 2.0.0
+---
+
+# New-ZertoPairingToken
+
+## SYNOPSIS
+Generates a new pairing token to be used during pairing ZVM to ZVM operations.
+
+## SYNTAX
+
+```
+New-ZertoPairingToken [-WhatIf] [-Confirm] [<CommonParameters>]
+```
+
+## DESCRIPTION
+Generates a new pairing token to be used during pairing ZVM to ZVM operations. This token is valid until used or 48 hours have passed, whichever comes first. This feature is only required when pairing two Zerto sites that are both operating Zerto version 7.5 or greater. To use this feature you will need to generate a pairing token from the destination site. Once that token is generated you will use that token to pair the source site to the destination site either via the GUI or via the `Add-ZertoPeerSite` function.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+PS C:\> New-ZertoPairingToken
+```
+
+Generates an object that will contain the pairing token and expiration date and time.
+
+## PARAMETERS
+
+### -Confirm
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: cf
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -WhatIf
+Shows what would happen if the cmdlet runs.
+The cmdlet is not run.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: wi
+
+Required: False
+Position: Named
+Default value: None
+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
+
+### None
+
+## OUTPUTS
+
+### System.Object
+## NOTES
+
+## RELATED LINKS
+[Zerto REST API Peer Sites End Point Documentation](http://s3.amazonaws.com/zertodownload_docs/Latest/Zerto%20Virtual%20Replication%20Zerto%20Virtual%20Manager%20%28ZVM%29%20-%20vSphere%20Online%20Help/index.html#page/RestfulAPIs%2FStatusAPIs.5.046.html%23)