The use of the tag $COMPLETE_JSON_FILE is only needed when you want to send your PowerShell script the output data of the request from where the script is being actioned or triggered. This is useful for getting information such as the Request ID if you're looking to interact with the request from which the PowerShell script was actioned. You can pass individual request data values, e.g. $ASSET, but you might as well send details of the whole request and split out the required values as needed in the PowerShell script.

So for a real scenario ... one client we were working with had a new starter process that required an email to be delivered to a specific team that were not part of the ServiceDesk installation with details of the ticket if a particular level of access was requested. As an enhancement we added an option to write a note to the request, via the API, to indicate that the email had been sent.

In order to achieve this we designed a Service Request template with all the necessary data fields and resource elements to collect the required data for the new starter process. On this template was a specific custom field that we used to specify the particular access level and this was used as a trigger condition for a 'Custom Trigger' with the full request data being passed to the script as $COMPLETE_JSON_FILE. 

An example is shown below:















Here is the PowerShell script we created  to  send the email with the required contents of the request; the actual script also included a large number of custom fields but I've only included the standard SDP request fields in this example. I've also kept the data in the JSON format as this is easier to relate to and test when using the API Documentation feature in the ServiceDesk Plus Admin tab. Remember to save your script file to the '\integration\custom_scripts' folder if you're going to test a copy:

-------- Start of script -------

# Store request data passed to script - this must be first element in script 
param (
    $json = "none"
)

$jsondata = Get-Content $json -Encoding UTF8    #Encode if necessary
$obj = ConvertFrom-Json $jsondata


# Add Request fields values as needed - custom fields are referenced by their alias name
$workorderid = $obj.request.WORKORDERID
$requester = $obj.request.REQUESTER
$createdtime = $obj.request.createdtime
$subject = $obj.request.SUBJECT
$category = $obj.request.category
$technician = $obj.request.technician
$status = $obj.request.status
$priority = $obj.request.priority
$requesttype = $obj.request.requesttype
$group = $obj.request.group
$description = $obj.request.description

# Set system parameters - change these details to suit your system environment
$sdphost = " http:// [hostname or IP address]:[port]/"
$techkey = " [your technician API key]"

# Set API module URL and operation - this is the URL for calling the create note API
# It uses the request parameter passed to the script $workorderid
$url = $sdphost + "sdpapi/request/" + $workorderid + "/notes"
$method = "POST"
$operation = "ADD_NOTE"

# Define SMTP Email Settings - this example uses Gmail
$SMTPServer = "  [insert SMTP host name here e.g. smtp.gmail.com] "
$SMTPPort = "  [insert SMTP port here e.g. 587 ] "
$Username = "  [insert account details here] "
$Password = "  [insert password here] "

$to = "  [insert to email address here] "
$cc = "  [insert cc email address here] "
$subject = "New Starter Alert"

# insert required email text between @" "@ markers including any HTML and request parameters 
#   <br> is HTML for a line break
$body = @"
Request Number : $workorderid <br>
Requester : $requester <br>
Subject : $subject <br>
Category : $category <br>
Technician: $technician <br>
Status : $status <br>
Priority : $priority <br>
Request Type: $requesttype <br>
Group : $group <br>
Description : $description <br>

"@

# Create email message
$message = New-Object System.Net.Mail.MailMessage
$message.subject = $subject
$message.IsBodyHTML =$true
$message.body = $body
$message.to.add($to)
$message.cc.add($cc)
$message.from = $username

# Send email
$smtp = New-Object System.Net.Mail.SmtpClient($SMTPServer, $SMTPPort);
$smtp.EnableSSL = $true
$smtp.Credentials = New-Object System.Net.NetworkCredential($Username, $Password);
$smtp.send($message)

# Configure input data for add note operation in JSON format
$inputdata = @"
{
    "operation": {
        "details": {
            "notes": {
                "note": {
                    "ispublic": "false",
                    "notestext": "New starter elevated level requested - action email sent to team."
                }
            }
        }
    }
}
"@

# Configure paramaters for web API call as an array of object and format as JSON data - this is a more elegant method than creating a text string to build the URL

# Make a web API call and record result
$response = Invoke-WebRequest -Uri $url -Method POST -Body $params

-------- End of script -------


I hope this series of blog articles has been useful. I'm finding that there are ever more customer requirements for using scripts and the API in general. I will be including more examples in future posts and also uploading them to the Forum Resources but that's all on the ServiceDesk Plus API for now.