Invoke TaskOnComputers - Tiberriver256/PoshAltiris GitHub Wiki

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

}

Invoke TaskOnComputers - Tiberriver256/PoshAltiris GitHub Wiki

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️