Merge pull request #38 from Readify/sharing-agreements

Adds Sharing Agreement commands. +semver: feature

PwshZendesk.psd1

@@ -35,7 +35,7 @@
     Description = 'Wrapper for the Zendesk Rest API'
 
     # Minimum version of the PowerShell engine required by this module
-    PowerShellVersion = '5.0'
+    PowerShellVersion = '5.1'
 
     # Name of the PowerShell host required by this module
     # PowerShellHostName = ''
@@ -96,6 +96,7 @@
         'Get-OrganizationRelated',             'Get-ZendeskOrganizationRelated'
         'Get-Problem',                         'Get-ZendeskProblem'
         'Get-SearchCount',                     'Get-ZendeskSearchCount'
+        'Get-SharingAgreement',                'Get-ZendeskSharingAgreement'
         'Get-SuspendedTicket',                 'Get-ZendeskSuspendedTicket'
         'Get-Tag',                             'Get-ZendeskTag'
         'Get-Ticket',                          'Get-ZendeskTicket'
@@ -118,13 +119,15 @@
         'New-GroupMembership',                 'New-ZendeskGroupMembership'
         'New-Organization',                    'New-ZendeskOrganization'
         'New-OrganizationMembership',          'New-ZendeskOrganizationMembership'
+        'New-SharingAgreement',                'New-ZendeskSharingAgreement'
         'New-Ticket',                          'New-ZendeskTicket'
         'New-UserIdentity',                    'New-ZendeskUserIdentity'
         'Remove-Attachment',                   'Remove-ZendeskAttachment'
         'Remove-Group',                        'Remove-ZendeskGroup'
         'Remove-GroupMembership',              'Remove-ZendeskGroupMembership'
         'Remove-Organization',                 'Remove-ZendeskOrganization'
         'Remove-OrganizationMembership',       'Remove-ZendeskOrganizationMembership'
+        'Remove-SharingAgreement',             'Remove-ZendeskSharingAgreement'
         'Remove-SuspendedTicket',              'Remove-ZendeskSuspendedTicket'
         'Remove-Tag',                          'Remove-ZendeskTag'
         'Remove-Ticket',                       'Remove-ZendeskTicket'
@@ -146,6 +149,7 @@
         'Test-Connection',                     'Test-ZendeskConnection'
         'Update-Group',                        'Update-ZendeskGroup'
         'Update-Organization',                 'Update-ZendeskOrganization'
+        'Update-SharingAgreement',             'Update-ZendeskSharingAgreement'
         'Update-Ticket',                       'Update-ZendeskTicket'
         'Update-User',                         'Update-ZendeskUser'
         'Update-UserIdentity',                 'Update-ZendeskUserIdentity'

README.md

@@ -3,7 +3,7 @@
 ![Build Status]
 
 PwshZendesk is a Zendesk Support API client for Powershell.
-PwshZendesk supports Powershell versions 5.0, 5.1, 6, and 7 on all platforms.
+PwshZendesk supports Powershell versions 5.1, 6, and 7 on all platforms.
 
 
 ## Getting Started
@@ -22,7 +22,7 @@ Head to Admin => Channels => API and click the `+` under "Token Access"
 
 ### Installing
 
-PwshZendesk supports Powershell versions 5.0, 5.1, 6, and 7 on all platforms.
+PwshZendesk supports Powershell versions 5.1, 6, and 7 on all platforms.
 
 It is recommended to install PwshZendesk from the [PowerShell Gallery]:
 

functions/Get-SharingAgreement.ps1

@@ -0,0 +1,45 @@
+function Get-SharingAgreement {
+    <#
+    .SYNOPSIS
+        Returns a sharing agreement for your account.
+    .DESCRIPTION
+        Returns a sharing agreement for your account.
+    .EXAMPLE
+        PS C:\> Get-ZendeskSharingAgreement
+
+        Lists all sharing agreements
+    .EXAMPLE
+        PS C:\> Get-ZendeskSharingAgreement -Id 1
+
+        Gets the details of the sharing agreement with id 1
+    #>
+    [OutputType([PSCustomObject])]
+    [CmdletBinding(DefaultParameterSetName = 'Default')]
+    Param (
+
+        # Unique Id of the sharing agreement to retrieve
+        [Parameter(Mandatory = $false)]
+        [ValidateRange(1, [Int64]::MaxValue)]
+        [Int64]
+        $Id,
+
+        # Zendesk Connection Context from `Get-ZendeskConnection`
+        [Parameter(Mandatory = $false)]
+        [PSTypeName('ZendeskContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    Assert-IsAgent -Context $Context
+
+    if ($PSBoundParameters.ContainsKey('Id')) {
+        $path = "/api/v2/sharing_agreements/$Id.json"
+        $key = 'sharing_agreement'
+    } else {
+        $path = '/api/v2/sharing_agreements.json'
+        $key = 'sharing_agreements'
+    }
+
+    $result = Invoke-Method -Context $Context -Path $path -Verbose:$VerbosePreference
+    $result | Select-Object -Expand $key
+}

functions/New-SharingAgreement.ps1

@@ -0,0 +1,86 @@
+
+function New-SharingAgreement {
+    <#
+    .SYNOPSIS
+        Creates a sharing agreement.
+    .DESCRIPTION
+        Creates a sharing agreement. Requires sharing to be enabled on the Zendesk instance. For more information see: https://support.zendesk.com/hc/en-us/articles/203661466-Sharing-tickets-with-other-Zendesk-Support-accounts
+    .EXAMPLE
+        PS C:\> New-ZendeskSharingAgreement -RemoteSubdomain 'Foo'
+
+        Creates a new sharing agreement with the Foo Zendesk Support instance.
+    #>
+    [OutputType([PSCustomObject])]
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    Param (
+        # Name of this sharing agreement
+        [Parameter(Mandatory = $false)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Name,
+
+        # The direction of the agreement
+        [Parameter(Mandatory = $false)]
+        [ValidateSet('inbound', 'outbound')]
+        [String]
+        $Type,
+
+        # The status of the agreement
+        [Parameter(Mandatory = $false)]
+        [ValidateSet('accepted', 'declined', 'pending', 'inactive')]
+        [String]
+        $Status,
+
+        # The Partner System
+        [Parameter(Mandatory = $false)]
+        [ValidateSet('jira')]
+        [String]
+        $PartnerName,
+
+        # Subdomain of the remote account
+        [Parameter(Mandatory = $false)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $RemoteSubdomain,
+
+        # Zendesk Connection Context from `Get-ZendeskConnection`
+        [Parameter(Mandatory = $false)]
+        [PSTypeName('ZendeskContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    Assert-IsAdmin -Context $Context
+
+    $path = '/api/v2/sharing_agreements.json'
+    $body = @{
+        sharing_agreement = @{
+        }
+    }
+
+    if ($PSBoundParameters.ContainsKey('Name')) {
+        $body.sharing_agreement['name'] = $Name
+    }
+
+    if ($PSBoundParameters.ContainsKey('Type')) {
+        $body.sharing_agreement['type'] = $Type
+    }
+
+    if ($PSBoundParameters.ContainsKey('Status')) {
+        $body.sharing_agreement['status'] = $Status
+    }
+
+    if ($PSBoundParameters.ContainsKey('PartnerName')) {
+        $body.sharing_agreement['partner_name'] = $PartnerName
+    }
+
+    if ($PSBoundParameters.ContainsKey('RemoteSubdomain')) {
+        $body.sharing_agreement['remote_subdomain'] = $RemoteSubdomain
+    }
+
+    if ($PSCmdlet.ShouldProcess($Name, 'Create Group')) {
+        $result = Invoke-Method -Context $Context -Method 'Post' -Path $path -Body $body -Verbose:$VerbosePreference
+        $result
+    }
+
+}

functions/Remove-SharingAgreement.ps1

@@ -0,0 +1,38 @@
+
+function Remove-SharingAgreement {
+    <#
+    .SYNOPSIS
+        Deletes a sharing agreement.
+    .DESCRIPTION
+        Deletes a sharing agreement.
+    .EXAMPLE
+        PS C:\> Remove-ZendeskSharingAgreement -Id 1
+
+        Deletes the sharing agreement with Id 1
+    #>
+    [OutputType([PSCustomObject])]
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    Param (
+        # Unique Id of sharing agreement to delete
+        [Parameter(Mandatory = $true)]
+        [ValidateRange(1, [Int64]::MaxValue)]
+        [Int64]
+        $Id,
+
+        # Zendesk Connection Context from `Get-ZendeskConnection`
+        [Parameter(Mandatory = $false)]
+        [PSTypeName('ZendeskContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    Assert-IsAdmin -Context $Context
+
+    $path = "/api/v2/sharing_agreements/$Id.json"
+
+    if ($PSCmdlet.ShouldProcess($Id, "Delete Sharing Agreement")) {
+        $result = Invoke-Method -Context $Context -Method 'Delete' -Path $path -Verbose:$VerbosePreference
+        $result
+    }
+
+}

functions/Update-SharingAgreement.ps1

@@ -0,0 +1,50 @@
+function Update-SharingAgreement {
+    <#
+    .SYNOPSIS
+        Updates the status of a sharing agreement
+    .DESCRIPTION
+        Updates the status of a sharing agreement
+    .EXAMPLE
+        PS C:\> Update-SharingAgreement -Id 1 -Status 'accepted'
+
+        Accepts the sharing agreement with id 1.
+    .EXAMPLE
+        PS C:\> Update-SharingAgreement -Id 1 -Status 'declined'
+
+        Declines the sharing agreement with id 1.
+    #>
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    Param (
+        # Unique Id of the sharing agreement to update
+        [Parameter(Mandatory = $true)]
+        [ValidateRange(1, [Int64]::MaxValue)]
+        [Int64]
+        $Id,
+
+        # The status of the agreement
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('accepted', 'declined', 'pending', 'inactive')]
+        [String]
+        $Status,
+
+        # Zendesk Connection Context from `Get-ZendeskConnection`
+        [Parameter(Mandatory = $false)]
+        [PSTypeName('ZendeskContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    Assert-IsAdmin -Context $Context
+
+    $path = "/api/v2/sharing_agreements/$Id.json"
+    $body = @{
+        sharing_agreement = @{
+            status = $Status
+        }
+    }
+
+    if ($PSCmdlet.ShouldProcess($Id, 'Update Sharing Agreement.')) {
+        $result = Invoke-Method -Context $Context -Method 'Put' -Path $path -Body $body -Verbose:$VerbosePreference
+        $result
+    }
+}