I wanted to give a little demo of a function constructed using the PowerShell PoshAltiris module to show how you might use it to programmatically execute tasks / jobs by name on the Altiris server usinng PowerShell
The cmdlet that we want to use is called Invoke-Task there is no existing help for this because Symantec has not provided any documentation on the webservice in their ASDK. I do know from running Help Invoke-Task though that it is going to require three parameters to run successfully (taskGuid, executionName and inputParameters)
PS C:\> help invoke-task
NAME
Invoke-Task
SYNOPSIS
SYNTAX
Invoke-Task [-taskGuid] <Guid> [-executionName] <String> [-inputParameters] <String> [-Server] <String>
[[-Credential] <PSCredential>] [<CommonParameters>]
I did a quick Google and found some sample code for this webservice from Lcode (Also using PowerShell, but I think you will like using the module much better).
It looks from his code to be something similar to the following for a description of the required parameters:
taskGuid - The Guid of the task you would like to execute
executionName - The name of the instance of the task you would like to show in the NS console
inputParameters - An xml file that houses required parameters (@AssignedResources and @CompRequirements) which I can describe a bit further here:
- @AssignedResources - A comma delimited string containing Guids for resources you would like to target with the task (We know from how the console works this could either be the Guid of a collection / filter or a computer)
- @CompRequirements - Short for completion requirements. Three settings are available here MinWaitTime, MaxWaitTime and MinCompletion (I can't find any more documentation on these and their possible formats)
- Additional input parameters that are created on a job are created using <paramater><name>NameHere</name><value>ValueHere</value></parameter>
Cool! But looks kind of complicated to gather all of that information. So lets break down exactly what we would need to do to make this as simple as giving a function an array of computernames and a taskname and watching the magic happen.
Step 1 - Get the taskGuid from the task name
This is pretty straightforward
Get-ItemsByName -itemName $TaskName -Server $Server
This will return an XML value containing an array of items that matches the task name I gave in Altiris. To parse into the first value of the array of items returned and get the Guid I modify the code to the following
$TaskGuid = @((Get-ItemsByName -itemName $TaskName -Server $Server).ArrayOfItemDetails.ItemDetails)[0].Guid
Now I have my TaskGuid value!
Step 2 - Choose an Execution Name
Looks like most execution names in the console just default to "Run $TaskName". Simple and classy. I like it.
$ExecutionName = "Run $TaskName"
Step 3 - Create the Input Parameters
Okay, now comes the more difficult part. I want to do this from an array of computer names right? The input parameters though expects a comma delimited string containing Guids for all of my computers!
*Onset of fear begins.... immediately turns to running Get-Command*
PS C:\> Get-Command *computer* -Module poshaltiris
CommandType Name Version Source
----------- ---- ------- ------
Function Get-ComputerByNameAndDomain 0.0.2 poshaltiris
Function Install-AltirisAgentToComputers 0.0.2 poshaltiris
Sick! What does this Get-ComputerByNameAndDomain cmdlet return!?
PS C:\> Get-ComputerByNameAndDomain -name $Env:COMPUTERNAME -domain $Env:USERDOMAIN -Server $Server
xml guid
--- ----
version="1.0" encoding="utf-8" guid
Miracle of miracles! Okay, now this shouldn't be so bad.
$ArrayOfComputerNames = @("Computer1","Computer2","Computer3")
[string[]]$ComputerGuids = foreach ($Computer in $ArrayOfComputerNames) {
(Get-ComputerByNameAndDomain -name $Computer -domain $Domain -Server $Server).guid."#text"
}
Now to merge that into my inputParamaters xml and call it.
$InputParameters = @"
<inputParameters>
<parameter>
<name>@AssignedResources</name>
<value>$($ComputerGuids -join ",")</value>
</parameter>
<parameter>
<name>@CompRequirements</name>
<value>
<minWaitTime>2 minutes</minWaitTime>
<maxWaitTime>60 minutes</maxWaitTime>
<minCompletion>100 %</minCompletion>
</value>
</parameter>
</inputParameters>
"@
Invoke-Task -taskGuid $TaskGuid -executionName "Run $TaskName" -inputParameters $InputParameters -Server $Server
And now I should be able to verify and watch my task get executed from the NS console!
Now I took this and built it out a bit more into a reusable function that allows you to change some of the parameters and add additional parameters with some examples if you want to play around with it a bit.
Example #1 - with additional input parameters specified
$Computers = @("Computer 1", "Computer 2")
$TaskName = "That one task I've always wanted to run from PowerShell but was never able to until now"
$CompletionRequirements = @{
"minWaitTime"="2 minutes"
"maxWaitTime"="60 minutes"
#Space here is deliberate between number and percentage. Again... couldn't find documentation on this.
"minCompletion"="100 %"
}
$AdditionalParameters = @{
"NEWCOMPUTERNAME" = "Hello"
}
$Server = "myserver.mydomain.com"
Invoke-TaskOnComputers -TaskName $TaskName `
-ComputerName $Computers `
-CompletionRequirements $CompletionRequirements `
-Server $Server -Domain $env:USERDOMAIN `
-AdditionalParameters $AdditionalParameters
Example #2 - No additional input parameters specified
$Computers = @("Computer 1", "Computer 2")
$TaskName = "That one task I've always wanted to run from PowerShell but was never able to until now"
$CompletionRequirements = @{
"minWaitTime"="2 minutes"
"maxWaitTime"="60 minutes"
#Space here is deliberate between number and percentage. Again... couldn't find documentation on this.
"minCompletion"="100 %"
}
$Server = "myserver.mydomain.com"
Invoke-TaskOnComputers -TaskName $TaskName `
-ComputerName $Computers `
-CompletionRequirements $CompletionRequirements `
-Server $Server -Domain $env:USERDOMAIN
Full Function Code (Invoke-TaskOnComputers)
Function Invoke-TaskOnComputers {
param(
[parameter(mandatory=$True)]
[string]$TaskName,
[parameter(mandatory=$True)]
[string[]]$ComputerName,
[parameter(mandatory=$True)]
[Hashtable]$CompletionRequirements,
[parameter(mandatory=$True)]
[string]$Server,
[string]$Domain = $env:USERDOMAIN,
[Hashtable]$AdditionalParameters,
#Default your Windows credentials will be used to authenticate to the NS server.
[pscredential]$AlternateCredential
)
# Getting the guid of the task from the name. Possibly better to use Get-ItemsByNameAndType for a safer experience.
$TaskGuid = @((Get-ItemsByName -itemName $TaskName -Server $Server).ArrayOfItemDetails.ItemDetails)[0].Guid
[string[]]$ComputerGuids = foreach ($Computer in $ComputerName) {
(Get-ComputerByNameAndDomain -name $Computer -domain $Domain -Server $Server).guid."#text"
}
#Building the input parameters XML
$InputParameters = @"
<inputParameters>
<parameter>
<name>@AssignedResources</name>
<value>$($ComputerGuids -join ",")</value>
</parameter>
<parameter>
<name>@CompRequirements</name>
<value>
<minWaitTime>$($AdditionalOptions["minWaitTime"])</minWaitTime>
<maxWaitTime>$($AdditionalOptions["maxWaitTime"])</maxWaitTime>
<minCompletion>$($AdditionalOptions["minCompletion"])</minCompletion>
</value>
</parameter>
$(
if($AdditionalParameters) {
foreach ($Parameter in $AdditionalParameters.Keys) {
@"
<parameter>
<name>$Parameter</name>
<value>$($AdditionalParameters[$Parameter])</value>
</parameter>
"@
}
})
</inputParameters>
"@
Invoke-Task -taskGuid $TaskGuid -executionName "Run $TaskName" -inputParameters $InputParameters -Server $Server
}