Hi Everyone,

I have noticed several questions around REST APIs for Service Desk Plus on the forums, and some vague answers. I have been using the REST APIs as part of a daily PowerShell workflow for some time, and I thought I would post my PowerShell functions with the hope of helping others through an example.  

Please keep in mind that these are very basic functions, and they are not intended to be a one-size-fits-all module. So please modify to meet your needs, and feel free to post your changes so others can get help on this very useful feature.

I am using four basic functions

1. Get a request, or several requests, based on a view filter
2. Add a work item to a request
3. Add a resolution to a request
4. Close a request

Below the four functions is an example on how to use them.

1. function Get-Request
   {
       <#
       .SYNOPSIS
    This function is used to return a list of requests. If RequestID is specified then a single request is returned. If RequestID is ommited then all requests assigned to the specified filter are returned. The filter will default to All Requests if one is not specified.
       .DESCRIPTION
    Get a list of Requests
2.     .EXAMPLE
    Get-Request -SdpUri "http://sdp.domain.com" -ApiKey "1234567A-2AB0-12A3-A123-1234567890AB" -RequestID 1234
3.     .PARAMETER RequestID
       The RequestID is the integer assigned to a "ticket" automatically by service desk plus
4.     .PARAMETER Filter
       The Request View Filter. These filters can be created in SDP. To find the filter name, Click on the ADMIN tab in SDP. Under General Settings click API, and Documentation.
    
    In the new Tab click "Requests" then "View Requests Filters", then "Try now". This parameter accepts the VIEWID
      
       .PARAMETER ApiKey
       This parameter is the API Key assigned to each technician. This serves as authentication to Service Desk Plus
    
    .PARAMETER Limit
       This parameter limits the number of returned requests. the default is 50
5.     .PARAMETER SdpUri
       This is the URI for Service Desk Plus
      
       #>
       [CmdletBinding()]
       param
       (
           [Parameter(Mandatory=$false, ValueFromPipelineByPropertyName=$true, Position=0)]
           [alias ("id")]
           [Int32]
           $RequestID=$null,
6.         [Parameter(Mandatory=$false, ValueFromPipelineByPropertyName=$true, Position=1)]
           [String]
           $Filter = "All_Requests",
7.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=2)]
           [String]
           $ApiKey,
8.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=3)]
           [String]
           $SdpUri,
9.         [Parameter(Mandatory=$false)]
           [String]
           $limit = 50
       )
       begin
       {
           if ($SdpUri[$SdpUri.Length -1] -eq "/") { $Uri = $SdpUri + "sdpapi/request" }
           else { $Uri = $SdpUri + "/sdpapi/request" }
       }
       process
       {
           if ($RequestID -gt 0)
           {
               $Uri = $Uri + "/" + $RequestID
               $Uri = $Uri + "?format=json&OPERATION_NAME=GET_REQUEST&TECHNICIAN_KEY=$ApiKey"
               $result = Invoke-RestMethod -Method Get -Uri $Uri
               $result
           }
           else
           {
               $Parameters = @{
                   "operation" = @{
                       "details" = @{
                           "from" = "0";
                           "limit" = $limit;
                           "filterby" = $filter
                       }
                  }
               }
10.        
11.             $input_data = $Parameters | ConvertTo-Json -Depth 50
                $Uri = $Uri + "?format=json&OPERATION_NAME=GET_REQUESTS&INPUT_DATA=$input_data&TECHNICIAN_KEY=$ApiKey"
                $result = Invoke-RestMethod -Method Get -Uri $Uri
                $result
            }
        }
    }
    function Add-WorkItem
    {
     <#
        .SYNOPSIS
     This function adds a work item to a request with a known request ID
     
        .DESCRIPTION
     Add a work item to a request
     
        .EXAMPLE
        Add-WorkItem -RequestID $request.WORKORDERID -ApiKey $ApiKey -SdpUri $SdpUri -Description "Review Completed" -workHours 0 -WorkMinutes 15 -Technician "Darth Vader"
     
        .PARAMETER RequestID
        The RequestID is the integer assigned to a "ticket" automatically by service desk plus
12.     .PARAMETER SdpUri
        This is the URI for Service Desk Plus
     
     .PARAMETER ApiKey
        This parameter is the API Key assigned to each technician. This serves as authentication to Service Desk Plus
     
     .PARAMETER Description
     This is the text that will display in the work item description area.
     
     .PARAMETER Technician
     This is the technician assigned to the work item
     
     .PARAMETER WorkHours
     This is the hours worked on a work item
     
     .PARAMETER WorkMinutes
     This is the minutes worked on a work item
        #>
        [CmdletBinding()]
        param
        (
            [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=0)]
            [alias ("id")]
            [Int32]
            $RequestID,
13.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=2)]
            [String]
            $ApiKey,
14.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=3)]
            [String]
            $SdpUri,
15.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)]
            [String]
            $Description,
16.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)]
            [String]
            $Technician,
17.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)]
            [Int32]
            $WorkHours,
18.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)]
            [Int32]
            $WorkMinutes
        )
        begin
        {
            if ($SdpUri[$SdpUri.Length -1] -eq "/") { $Uri = $SdpUri + "sdpapi/request/$RequestID/worklogs" }
            else { $Uri = $SdpUri + "/sdpapi/request/$RequestID/worklogs" }
        }
        process
        {
                $Parameters = @{
                "operation" = @{
                    "details" = @{
                        "worklogs" = @{
                            "worklog" = @{
                                "description" = $Description;
                                "technician" = $Technician;
                                "workHours" = $WorkHours;
                                "workMinutes" = $WorkMinutes
                            }
                        }
                    }
                }
            }
19.        
20.         $input_data = $Parameters | ConvertTo-Json -Depth 50
            $Uri = $Uri + "?format=json&OPERATION_NAME=ADD_WORKLOG&INPUT_DATA=$input_data&TECHNICIAN_KEY=$ApiKey"
            $result = Invoke-RestMethod -Method POST -Uri $Uri
            $result
        }
    }
    function Set-Resolution
    {
     <#
        .SYNOPSIS
     Set the Resolution for a request
        .DESCRIPTION
     Set the Resolution for a request
        .EXAMPLE
        Set-Resolution -RequestID $request.WORKORDERID -ApiKey $ApiKey -SdpUri $SdpUri -Resolution "I rebooted three times"
     
        .PARAMETER RequestID
        The RequestID is the integer assigned to a "ticket" automatically by service desk plus
21.     .PARAMETER SdpUri
        This is the URI for Service Desk Plus
     
     .PARAMETER ApiKey
        This parameter is the API Key assigned to each technician. This serves as authentication to Service Desk Plus
     
     .PARAMETER Resolution
     This is the text that will be added as a resolution
22.    
        #>
        [CmdletBinding()]
        param
        (
            [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=0)]
            [alias ("id")]
            [Int32]
            $RequestID,
23.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=2)]
            [String]
            $ApiKey,
24.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=3)]
            [String]
            $SdpUri,
25.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)]
            [String]
            $Resolution
        )
        begin
        {
            if ($SdpUri[$SdpUri.Length -1] -eq "/") { $Uri = $SdpUri + "sdpapi/request/$RequestID/resolution" }
            else { $Uri = $SdpUri + "/sdpapi/request/$RequestID/resolution" }
        }
        process
        {
                $Parameters = @{
                "operation" = @{
                    "details" = @{
                        "resolution" = @{
                           "resolutiontext" = $resolution
                        }
                    }
                }
            }
26.        
27.         $input_data = $Parameters | ConvertTo-Json -Depth 50
            $Uri = $Uri + "?format=json&OPERATION_NAME=ADD_RESOLUTION&INPUT_DATA=$input_data&TECHNICIAN_KEY=$ApiKey"
            $result = Invoke-RestMethod -Method POST -Uri $Uri
            $result
        }
    }
    function Close-Request
    {
     <#
        .SYNOPSIS
     Close a request. This function assumes the closure has been acknowledged.
        .DESCRIPTION
     Close a request. This function assumes the closure has been acknowledged.
       
     .EXAMPLE
        Close-Request -RequestID $request.WORKORDERID -ApiKey $ApiKey -SdpUri $SdpUri
     
        .PARAMETER RequestID
        The RequestID is the integer assigned to a "ticket" automatically by service desk plus
28.     .PARAMETER SdpUri
        This is the URI for Service Desk Plus
     
     .PARAMETER ApiKey
        This parameter is the API Key assigned to each technician. This serves as authentication to Service Desk Plus
     
29.    
        #>
        [CmdletBinding()]
        param
        (
            [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=0)]
            [alias ("id")]
            [Int32]
            $RequestID,
30.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=2)]
            [String]
            $ApiKey,
31.         [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true, Position=3)]
            [String]
            $SdpUri
        )
        begin
        {
            if ($SdpUri[$SdpUri.Length -1] -eq "/") { $Uri = $SdpUri + "sdpapi/request/$RequestID" }
            else { $Uri = $SdpUri + "/sdpapi/request/$RequestID" }
        }
        process
        {
                $Parameters = @{
                "operation" = @{
                    "details" = @{
                       "closeAccepted" = "Accepted";
                       "closeComment" = "Review Completed"
                    }
                }
            }
32.        
33.         $input_data = $Parameters | ConvertTo-Json -Depth 50
            $Uri = $Uri + "?format=json&OPERATION_NAME=CLOSE_REQUEST&INPUT_DATA=$input_data&TECHNICIAN_KEY=$ApiKey"
            $result = Invoke-RestMethod -Method POST -Uri $Uri
            $result
        }
    }

Now here an the example on how I use those four functions:

1. $ApiKey = "YOUR API KEY HERE!"
   $SdpUri = "https://sdpURL.domain.com"
   $MyDailyPMRequests = Get-Request -ApiKey $ApiKey -SdpUri $SdpUri -Filter "Open_User" -Limit 0
   foreach ($request in $$MyDailyPMRequests.operation.details)
   {
       if ($request.SUBJECT -like "*TICKET I WANT TO CLOSE*")
       {
           $result = Set-Resolution -RequestID $request.WORKORDERID -ApiKey $ApiKey -SdpUri $SdpUri -Resolution "I DID MY DAILY WORK"
           $result.operation.result.message
2.         $result = Add-WorkItem -RequestID $request.WORKORDERID -ApiKey $ApiKey -SdpUri $SdpUri -Description "I PERFORMED X Y AND Z" -workHours 0 -WorkMinutes 15 -Technician "René Sommer"
           $result.operation.result.message
3.         $result = Close-Request -RequestID $request.WORKORDERID -ApiKey $ApiKey -SdpUri $SdpUri
           $result.operation.result.message
       }
   }

I hope this helps someone!

Good luck!

Robert