Merge pull request #3 from cksapp/SaaS-Bulk-Seat-API

Datto REST API - SaaS Bulk Seat Change

DattoAPI/Private/apiCalls/ConvertTo-DattoQueryString.ps1

@@ -64,7 +64,7 @@ param(
                                 'allPages', 'page', 'perPage',
                                 'endpoint_Agents', 'endpoint_Devices', 'endpoint_byDevice', 'endpoint_byDeviceAgent',
                                 'endpoint_byDeviceAlert', 'endpoint_byDeviceAsset', 'endpoint_byDeviceShare', 'endpoint_byDeviceVolume',
-                                'endpoint_Domains', 'endpoint_CustomerSeats', 'endpoint_CustomerApps', 'saasCustomerId','externalSubscriptionId'
+                                'endpoint_Domains', 'endpoint_CustomerSeats', 'endpoint_CustomerApps', 'saasCustomerId','externalSubscriptionId','seatType','remoteId','actionType'
 
         $query_Parameters = [System.Web.HttpUtility]::ParseQueryString([String]::Empty)
 

DattoAPI/Private/apiCalls/Invoke-DattoRequest.ps1

@@ -14,7 +14,7 @@ function Invoke-DattoRequest {
         Defines the type of API method to use
 
         Allowed values:
-        'GET'
+        'GET', 'PUT'
 
     .PARAMETER resource_Uri
         Defines the resource uri (url) to use when creating the API call
@@ -63,7 +63,7 @@ function Invoke-DattoRequest {
     [CmdletBinding()]
     param (
         [Parameter(Mandatory = $false)]
-        [ValidateSet('GET')]
+        [ValidateSet('GET','PUT')]
         [String]$method = 'GET',
 
         [Parameter(Mandatory = $true)]
@@ -96,7 +96,7 @@ function Invoke-DattoRequest {
         if ($null -eq $data) {
             $body = $null
         } else {
-            $body = @{'data'= $data} | ConvertTo-Json -Depth $Datto_JSON_Conversion_Depth
+            $body = $data | ConvertTo-Json -Depth $Datto_JSON_Conversion_Depth
         }
 
         try {

DattoAPI/Public/SaaS/Set-DattoBulkSeatChange.ps1

@@ -0,0 +1,98 @@
+function Set-DattoBulkSeatChange {
+<#
+    .SYNOPSIS
+        Sets Datto SaaS Protection bulk seat changes
+
+    .DESCRIPTION
+        The Set-DattoBulkSeatChange cmdlet is used to set SaaS Protection bulk seat changes
+
+    .PARAMETER saasCustomerId
+        Defines the id of the Organization to set SaaS information from
+
+    .PARAMETER externalSubscriptionId
+        Defines the external Subscription ID of the SaaS Protection Organization used to set SaaS bulk seat changes
+
+    .EXAMPLE
+        Set-DattoBulkSeatChange -saasCustomerId "12345678" -externalSubscriptionId 'Classic:Office365:123456' -seatType "User" -remoteId "ab23-bdf234-1234-asdf" -actionType "License"
+
+        Sets the Datto SaaS protection seats from the defined Office365 customer id
+
+    .EXAMPLE
+        Set-DattoBulkSeatChange -saasCustomerId "12345678" -externalSubscriptionId 'Classic:GoogleApps:123456' -seatType "SharedDrive" -remoteId "ab23-bdf234-1234-asdf","cd45-cfe567-5678-qwer" -actionType "Pause"
+
+        Sets the Datto SaaS protection seats from the defined Google customer id
+
+    .NOTES
+        N\A
+
+    .LINK
+        https://celerium.github.io/Datto-PowerShellWrapper/site/SaaS/Set-DattoBulkSeatChange.html
+#>
+
+    [CmdletBinding(DefaultParameterSetName = 'index', SupportsShouldProcess = $true)]
+    Param (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'index')]
+        [ValidateNotNullOrEmpty()]
+        [string]$saasCustomerId,
+
+        [Parameter(Mandatory = $true, ParameterSetName = 'index')]
+        [ValidateNotNullOrEmpty()]
+        [string]$externalSubscriptionId,
+
+        # Parameter help description
+        [Parameter(
+            Mandatory = $true,
+            ValueFromPipeline = $true,
+            ValueFromPipelineByPropertyName = $true,
+            ParameterSetName = 'index'
+            )]
+        [ValidateNotNullOrEmpty()]
+        [string]$seatType,
+
+        # Valid methods are 'License' to "Protect", 'Pause' to "Pause", and 'Unlicense' to "Unprotect"
+        [Parameter(
+            Mandatory = $true,
+            ValueFromPipeline = $true,
+            ValueFromPipelineByPropertyName = $true,
+            ParameterSetName = 'index'
+            )]
+        [ValidateSet('License','Pause','Unlicense')]
+        [ValidateNotNullOrEmpty()]
+        [string]$actionType,
+
+        # Either like 'Classic:Office365:123456', or 'Classic:GoogleApps:123456'
+        [Parameter(
+            Mandatory = $true,
+            ValueFromPipeline = $true,
+            ValueFromPipelineByPropertyName = $true,
+            ParameterSetName = 'index'
+            )]
+        [ValidateNotNullOrEmpty()]
+        [string[]]$remoteId
+    )
+
+    begin {
+
+        $resource_uri = "/saas/$saasCustomerId/$externalSubscriptionId/bulkSeatChange"
+
+        $requestBody = @{
+            seat_type = $seatType
+            action_type = $actionType
+            ids = $remoteId
+            }
+
+    }
+
+    process {
+
+        if ($PSCmdlet.ShouldProcess("saasCustomerId: $saasCustomerId, externalSubscriptionId: $externalSubscriptionId, $remoteId", "$actionType $seatType")) {
+            Write-Verbose "Running the [ $($PSCmdlet.ParameterSetName) ] parameterSet"
+            Set-Variable -Name 'Datto_bulkSeatParameters' -Value $PSBoundParameters -Scope Global -Force
+
+            Invoke-DattoRequest -method PUT -resource_Uri $resource_Uri -uri_Filter $PSBoundParameters -data $requestBody
+        }
+
+    }
+
+    end {}
+}

README.md

@@ -86,9 +86,10 @@ The [DattoAPI](https://www.datto.com/) offers users the ability to extract data
 - :book: Project documentation can be found on [Github Pages](https://celerium.github.io/Datto-PowerShellWrapper/)
 - :book: Datto's REST API documentation on their management portal [here](https://portal.dattobackup.com/integrations/api) *[ Requires a login ]*.
 
-Datto features a REST API that makes use of common HTTPs GET actions. In order to maintain PowerShell best practices, only approved verbs are used.
+Datto features a REST API that makes use of common HTTP request methods. In order to maintain PowerShell best practices, only approved verbs are used.
 
 - GET -> Get-
+- PUT -> Set-
 
 Additionally, PowerShell's `verb-noun` nomenclature is respected. Each noun is prefixed with `Datto` in an attempt to prevent naming problems.
 
@@ -131,12 +132,12 @@ After installing this module, you will need to configure both the *base URI* & *
    - By default, Datto's `https://api.datto.com/v1` URI is used.
    - If you have your own API gateway or proxy, you may put in your own custom URI by specifying the `-base_uri` parameter:
       - `Add-DattoBaseURI -base_uri http://myapi.gateway.celerium.org`
-<br>
+      <br>
 
 2. Run `Add-DattoAPIKey -Api_Key_Public 12345 -Api_Key_Secret 123456789`
    - It will prompt you to enter your API access tokens if you do not specify them.
    - Datto API access tokens are generated via the Datto portal at *Admin > Integrations*
-<br>
+   <br>
 
 3. [**optional**] Run `Export-DattoModuleSettings`
    - This will create a config file at `%UserProfile%\DattoAPI` that holds the *base uri* & *API access tokens* information.
@@ -153,22 +154,22 @@ Calling an API resource is as simple as running `Get-Datto<resourceName>`
 - The following is a table of supported functions and their corresponding API resources:
 - Table entries with [ `-` ] indicate that the functionality is **NOT** supported by the Datto API at this time.
 
-| Section   | API Resource       | Create    | Read                           | Update    | Delete    |
-|---------  | --------------     | --------- | -------------------------      | --------- | --------- |
-| Reporting | ActivityLog        | -         | `Get-DattoActivityLog`         | -         | -         |
-| BCDR      | Agent              | -         | `Get-DattoAgent`               | -         | -         |
-| BCDR      | Alert              | -         | `Get-DattoAlert`               | -         | -         |
-| BCDR      | Asset              | -         | `Get-DattoAsset`               | -         | -         |
-| BCDR      | **BCDR** *         | -         | `Get-DattoBCDR`                | -         | -         |
-| BCDR      | Device             | -         | `Get-DattoDevice`              | -         | -         |
-| BCDR      | Share              | -         | `Get-DattoShare`               | -         | -         |
-| BCDR      | VMRestore          | -         | `Get-DattoGet-DattoVMRestore`  | -         | -         |
-| BCDR      | Volume             | -         | `Get-DattoVolume`              | -         | -         |
-| SaaS      | **SaaS** *         | -         | `Get-DattoSaaS`                | -         | -         |
-| SaaS      | Domains            | -         | `Get-DattoDomain`              | -         | -         |
-| SaaS      | Seats              | -         | `Get-DattoSeat`                | -         | -         |
-| SaaS      | Applications       | -         | `Get-DattoApplication`         | -         | -         |
-| SaaS      | BulkSeatAssignment | -         | `Get-DattoBulkSeatAssignment`  | -         | -         |
+| Section   | API Resource       | Create | Read                          | Update                    | Delete |
+| --------- | ------------------ | ------ | ----------------------------- | ------------------------- | ------ |
+| Reporting | ActivityLog        | -      | `Get-DattoActivityLog`        | -                         | -      |
+| BCDR      | Agent              | -      | `Get-DattoAgent`              | -                         | -      |
+| BCDR      | Alert              | -      | `Get-DattoAlert`              | -                         | -      |
+| BCDR      | Asset              | -      | `Get-DattoAsset`              | -                         | -      |
+| BCDR      | **BCDR** *         | -      | `Get-DattoBCDR`               | -                         | -      |
+| BCDR      | Device             | -      | `Get-DattoDevice`             | -                         | -      |
+| BCDR      | Share              | -      | `Get-DattoShare`              | -                         | -      |
+| BCDR      | VMRestore          | -      | `Get-DattoGet-DattoVMRestore` | -                         | -      |
+| BCDR      | Volume             | -      | `Get-DattoVolume`             | -                         | -      |
+| SaaS      | **SaaS** *         | -      | `Get-DattoSaaS`               | -                         | -      |
+| SaaS      | Domains            | -      | `Get-DattoDomain`             | -                         | -      |
+| SaaS      | Seats              | -      | `Get-DattoSeat`               | -                         | -      |
+| SaaS      | Applications       | -      | `Get-DattoApplication`        | -                         | -      |
+| SaaS      | BulkSeatChange | -      | -                             | `Set-DattoBulkSeatChange` | -      |
 
 - :warning: `Get-DattoBCDR` & `Get-DattoSaaS` are special functions.
 - These are **NOT** endpoints in Datto's REST API and are a single set of commands that can run endpoints in their associate sections.

docs/Contributing.md

@@ -14,9 +14,9 @@ nav_order: 3
 
 ## **Did you find a bug?**
 
-* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Celerium/DattoAPI/issues).
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/Celerium/Datto-PowerShellWrapper/issues).
 
-* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Celerium/DattoAPI/issues/new/choose).
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Celerium/Datto-PowerShellWrapper/issues/new/choose).
   * Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
 
 ## **Did you write a patch that fixes a bug?**

docs/DattoAPI.md

@@ -36,9 +36,6 @@ Gets Datto BCDR alerts for a given device.
 ### [Get-DattoAPIKey](site/Internal/Get-DattoAPIKey.md)
 Gets the Datto API public & secret key global variables.
 
-### [Get-DattoApplication](site/SaaS/Get-DattoApplication.md)
-Get Datto SaaS protection backup data for a given customer
-
 ### [Get-DattoAsset](site/BCDR/Get-DattoAsset.md)
 Get Datto BCDR assets (agents and shares) for a given device
 
@@ -48,15 +45,9 @@ Shows the Datto base URI global variable.
 ### [Get-DattoBCDR](site/BCDR/Get-DattoBCDR.md)
 Gets Datto BCDR devices and assets
 
-### [Get-DattoBulkSeatAssignment](site/SaaS/Get-DattoBulkSeatAssignment.md)
-Get SaaS Protection bulk seats assignment
-
 ### [Get-DattoDevice](site/BCDR/Get-DattoDevice.md)
 Gets Datto BCDR devices from the the Datto API.
 
-### [Get-DattoDomain](site/SaaS/Get-DattoDomain.md)
-Get Datto SaaS protection data about what domains are being protected
-
 ### [Get-DattoMetaData](site/Internal/Get-DattoMetaData.md)
 Gets various Api metadata values
 
@@ -66,9 +57,18 @@ Gets the saved Datto configuration settings
 ### [Get-DattoSaaS](site/SaaS/Get-DattoSaaS.md)
 Gets Datto SaaS protection data
 
+### [Get-DattoApplication](site/SaaS/Get-DattoApplication.md)
+Get Datto SaaS protection backup data for a given customer
+
+### [Get-DattoDomain](site/SaaS/Get-DattoDomain.md)
+Get Datto SaaS protection data about what domains are being protected
+
 ### [Get-DattoSeat](site/SaaS/Get-DattoSeat.md)
 Get Datto SaaS protection seats for a given customer
 
+### [Set-DattoBulkSeatChange](site/SaaS/Set-DattoBulkSeatChange.md)
+Sets Datto SaaS Protection bulk seat changes
+
 ### [Get-DattoShare](site/BCDR/Get-DattoShare.md)
 Gets Datto BCDR shares for a given device
 

docs/Endpoints.csv

@@ -25,7 +25,7 @@ Internal,,DELETE,Remove-DattoModuleSettings,YES,
 Internal,,GET,Test-DattoAPIKey,YES,
 Reporting,/report/activity-log,GET,Get-DattoActivityLog,YES,
 SaaS,/sass/{sassCustomerId}/applications,GET,Get-DattoApplication,YES,
-SaaS,/saas/{saasCustomerId}/{externalSubscriptionId}/bulkSeatAssignment,GET,Get-DattoBulkSeatAssignment,YES,Cannot fully validate at this time
+SaaS,/saas/{saasCustomerId}/{externalSubscriptionId}/bulkSeatAssignment,SET,Set-DattoBulkSeatChange,YES,
 SaaS,/sass/domains,GET,Get-DattoDomain,YES,
 SaaS,/sass/,GET,Get-DattoSaaS,YES,Special command that combines all SaaS endpoints
 SaaS,/sass/{sassCustomerId}/seats,GET,Get-DattoSeat,YES,