Add some functions for User and agreement management (#2)

* Add some functions for User and agreement management

* Update PwshAdobeSign.psd1

Co-authored-by: Mickaël Derriey <[email protected]>

* Ids are strings

Co-authored-by: Mickaël Derriey <[email protected]>

PwshAdobeSign.psd1

@@ -70,10 +70,21 @@
 
     # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
     FunctionsToExport = @(
-        'Connect-',       'Connect-AdobeSign'
-        'Get-BaseUri',    'Get-AdobeSignBaseUri'
-        'Get-Connection', 'Get-AdobeSignConnection'
-        'Invoke-Method',  'Invoke-AdobeSignMethod'
+        'Add-UserGroup',                 'Add-AdobeSignUserGroup'
+        'Connect-',                      'Connect-AdobeSign'
+        'Get-Agreement',                 'Get-AdobeSignAgreement'
+        'Get-AgreementCombinedDocument', 'Get-AdobeSignAgreementCombinedDocument'
+        'Get-BaseUri',                   'Get-AdobeSignBaseUri'
+        'Get-Connection',                'Get-AdobeSignConnection'
+        'Get-Group',                     'Get-AdobeSignGroup'
+        'Get-User',                      'Get-AdobeSignUser'
+        'Get-UserGroup',                 'Get-AdobeSignUserGroup'
+        'Hide-Agreement',                'Hide-AdobeSignAgreement'
+        'Invoke-Method',                 'Invoke-AdobeSignMethod'
+        'Remove-UserGroup',              'Remove-AdobeSignUserGroup'
+        'Show-Agreement',                'Show-AdobeSignAgreement'
+        'Update-AgreementVisibility',    'Update-AdobeSignAgreementVisibility'
+        'Update-UserGroup',              'Update-AdobeSignUserGroup'
     )
 
     # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.

functions/Add-UserGroup.ps1

@@ -0,0 +1,43 @@
+
+function Add-UserGroup {
+    <#
+    .SYNOPSIS
+        Adds a user to a group.
+    .DESCRIPTION
+        Adds a user to a group.
+    .EXAMPLE
+        PS /> Add-AdobeSignUserGroup -UserId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK -GroupId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Adds a user to a group.
+    .EXAMPLE
+        PS /> Add-AdobeSignUserGroup -Context $context -UserId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK -GroupId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Adds a user to a group using a connection context.
+    #>
+    [OutputType([PSCustomObject])]
+    [CMDletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]
+    Param (
+        # The ID of the user.
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $UserId,
+
+        # The ID of the group.
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $GroupId,
+
+        # Adobe Sign Connection Context from `Get-AdobeSignConnection`
+        [Parameter()]
+        [PSTypeName('AdobeSignContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    if ($PSCmdlet.ShouldProcess($UserId, 'Add Group Membership')){
+        $result = Set-UserGroup @PSBoundParameters -Status 'ACTIVE' -Verbose:$VerbosePreference -Confirm:$false
+        $result
+    }
+}

functions/Get-Agreement.ps1

@@ -0,0 +1,76 @@
+
+function Get-Agreement {
+    <#
+    .SYNOPSIS
+        Returns a list of agreements or a specified agreement.
+    .DESCRIPTION
+        Returns a list of agreements or a specified agreement.
+    .EXAMPLE
+        PS /> Get-AdobeSignAgreement
+
+        Gets a list of all agreements
+    .EXAMPLE
+        PS /> Get-AdobeSignAgreement -Id hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Gets an agreement using its id.
+    .EXAMPLE
+        PS /> Get-AdobeSignAgreement -GroupId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Gets all agreements from a group.
+    .EXAMPLE
+        PS /> Get-AdobeSignAgreement -ShowHiddenAgreements $true
+
+        Gets all agreements including hidden agreements.
+    .EXAMPLE
+        PS /> Get-AdobeSignAgreement -Context $context
+
+        Gets a list of all agreements using a connection context.
+    #>
+    [OutputType([PSCustomObject])]
+    [CMDletBinding(DefaultParameterSetName = 'all')]
+    Param (
+        # The ID of the agreement.
+        [Parameter(Mandatory, ParameterSetName = 'id')]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Id,
+
+        # The ID of the group.
+        [Parameter(ParameterSetName = 'all')]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $GroupId,
+
+        # Show agreements that have been hidden.
+        [Parameter(ParameterSetName = 'all')]
+        [Boolean]
+        $ShowHiddenAgreements = $false,
+
+        # Adobe Sign Connection Context from `Get-AdobeSignConnection`
+        [Parameter()]
+        [PSTypeName('AdobeSignContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    switch ($PSCmdlet.ParameterSetName) {
+        'id' {
+            $path = "/agreements/$Id"
+        }
+        default {
+            $path = "/agreements?showHiddenAgreements=$showHiddenAgreements"
+            if ($PSBoundParameters.ContainsKey('GroupId')) {
+                $path += "&groupId=$GroupId"
+            }
+        }
+    }
+
+    $result = Invoke-Method -Context $Context -Path $path -Verbose:$VerbosePreference
+    if ($result) {
+        if ($result | Get-Member -Name userAgreementList) {
+            $result | ForEach-Object userAgreementList
+        } else {
+            $result
+        }
+    }
+}

functions/Get-AgreementCombinedDocument.ps1

@@ -0,0 +1,80 @@
+
+function Get-AgreementCombinedDocument {
+    <#
+    .SYNOPSIS
+        Downloads an agreement's combined document
+    .DESCRIPTION
+        Downloads an agreement's combined document
+    .EXAMPLE
+        PS /> $params = @{
+            Id      = 'hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK'
+            OutFile = 'agreement.pdf'
+        }
+        PS /> Update-AdobeSignAgreementCombinedDocument @params
+
+        Downloads an agreement's combined document.
+    .EXAMPLE
+        PS /> $params = @{
+            Id                = 'hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK'
+            OutFile           = 'agreement.pdf'
+            AttachAuditReport = $true
+        }
+        PS /> Update-AdobeSignAgreementCombinedDocument @params
+
+        Downloads an agreement's combined document with attached audit report.
+    .EXAMPLE
+        PS /> $params = @{
+            Id                        = 'hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK'
+            OutFile                   = 'agreement.pdf'
+            AttachSupportingDocuments = $false
+        }
+        PS /> Update-AdobeSignAgreementCombinedDocument @params
+
+        Downloads an agreement's combined document without attached supporting documents.
+    .EXAMPLE
+        PS /> $params = @{
+            Id      = 'hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK'
+            OutFile = 'agreement.pdf'
+            Context = $context
+        }
+        PS /> Update-AdobeSignAgreementCombinedDocument @params
+
+        Downloads an agreement's combined document using a connection context.
+    #>
+    [OutputType([PSCustomObject])]
+    [CMDletBinding()]
+    Param (
+        # The ID of the agreement.
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Id,
+
+        # File to save response to
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $OutFile,
+
+        # If the autdit report should be included
+        [Parameter()]
+        [Boolean]
+        $AttachAuditReport = $false,
+
+        # If all supporting documents should be included
+        [Parameter()]
+        [Boolean]
+        $AttachSupportingDocuments = $true,
+
+        # Adobe Sign Connection Context from `Get-AdobeSignConnection`
+        [Parameter()]
+        [PSTypeName('AdobeSignContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    $path = "/agreements/$Id/combinedDocument?attachAuditReport=$AttachAuditReport&attachSupportingDocuments=$AttachSupportingDocuments"
+
+    $result = Invoke-Method -Context $Context -Path $path -OutFile $OutFile -Verbose:$VerbosePreference
+    $result
+}

functions/Get-Group.ps1

@@ -0,0 +1,51 @@
+
+function Get-Group {
+    <#
+    .SYNOPSIS
+        Returns a list of groups or a specified group.
+    .DESCRIPTION
+        Returns a list of groups or a specified group.
+    .EXAMPLE
+        PS /> Get-AdobeSigngroup
+
+        Gets a list of all groups
+    .EXAMPLE
+        PS /> Get-AdobeSigngroup -Id hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Gets a group using its id.
+    .EXAMPLE
+        PS /> Get-AdobeSigngroup -Context $context
+
+        Gets a list of all groups using a connection context.
+    #>
+    [OutputType([PSCustomObject])]
+    [CMDletBinding()]
+    Param (
+        # The ID of the group.
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Id,
+
+        # Adobe Sign Connection Context from `Get-AdobeSignConnection`
+        [Parameter()]
+        [PSTypeName('AdobeSignContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    if ($PSBoundParameters.ContainsKey('Id')) {
+        $path = "/groups/$Id"
+    } else {
+        $path = '/groups'
+    }
+
+    $result = Invoke-Method -Context $Context -Path $path -Verbose:$VerbosePreference
+    if ($result) {
+        if ($result | Get-Member -Name groupInfoList) {
+            $result | ForEach-Object groupInfoList
+        } else {
+            $result
+        }
+    }
+}

functions/Get-User.ps1

@@ -0,0 +1,51 @@
+
+function Get-User {
+    <#
+    .SYNOPSIS
+        Returns a list of users or a specified user.
+    .DESCRIPTION
+        Returns a list of users or a specified user.
+    .EXAMPLE
+        PS /> Get-AdobeSignUser
+
+        Gets a list of all users
+    .EXAMPLE
+        PS /> Get-AdobeSignUser -UserId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Gets a user using their id.
+    .EXAMPLE
+        PS /> Get-AdobeSignUser -Context $context
+
+        Gets a list of all users using a connection context.
+    #>
+    [OutputType([PSCustomObject])]
+    [CMDletBinding()]
+    Param (
+        # The ID of the user.
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Id,
+
+        # Adobe Sign Connection Context from `Get-AdobeSignConnection`
+        [Parameter()]
+        [PSTypeName('AdobeSignContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    if ($PSBoundParameters.ContainsKey('Id')) {
+        $path = "/users/$Id"
+    } else {
+        $path = '/users'
+    }
+
+    $result = Invoke-Method -Context $Context -Path $path -Verbose:$VerbosePreference
+    if ($result) {
+        if ($result | Get-Member -Name userInfoList) {
+            $result | ForEach-Object userInfoList
+        } else {
+            $result
+        }
+    }
+}

functions/Get-UserGroup.ps1

@@ -0,0 +1,43 @@
+
+function Get-UserGroup {
+    <#
+    .SYNOPSIS
+        Returns a list of groups for a specified user.
+    .DESCRIPTION
+        Returns a list of groups for a specified user.
+    .EXAMPLE
+        PS /> Get-AdobeSignUserGroup -UserId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Gets the groups for a user.
+    .EXAMPLE
+        PS /> Get-AdobeSignUserGroup -Context $context -UserId hXy4R2NaYnvTaftrEhaD4ZAJrxh3YM8kuf8CupEouFoK
+
+        Gets the groups for a user using a connection context.
+    #>
+    [OutputType([PSCustomObject])]
+    [CMDletBinding()]
+    Param (
+        # The ID of the user.
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [String]
+        $Id,
+
+        # Adobe Sign Connection Context from `Get-AdobeSignConnection`
+        [Parameter()]
+        [PSTypeName('AdobeSignContext')]
+        [PSCustomObject]
+        $Context = $null
+    )
+
+    $path = "/users/$Id/groups"
+
+    $result = Invoke-Method -Context $Context -Path $path -Verbose:$VerbosePreference
+    if ($result) {
+        if ($result | Get-Member -Name groupInfoList) {
+            $result | ForEach-Object groupInfoList
+        } else {
+            $result
+        }
+    }
+}