Parsing Job and Setup Properties

Parsing can be used to obtain the values of Job and Setup Properties. These values can be used in your source which allows for customization and a more dynamic Job source. Parsing allows you to easily obtain the values of the properties of Job and Setup definitions. It is also possible to access the properties of a currently scheduled Job or Setup to access information about the Job or Setup as it is executing.

To get the values of the properties from a Job's definition use the template "<<JAMS.Job.PropertyName>>". To see all the available properties refer to the Job Class Documentation. To access the properties of a current Job entry use the format: <<JAMS.PropertyName>>. This is different than the Job definition and can be used to get information about the running Job or Setup such as the Agent Node the Job is running on or the user the Job is executing under. This is called the CurJob or entry and can be either a Setup or a Job. To see all the available properties refer to the CurJob Class Documentation. You can use these parsed values directly or assign them to a Variable.

Note: Parsing allows for the use of standard .NET format strings. One common example of this is using .NET DateTime string formatting to specify the formatting of a DateTime property. This is done using the template: "<<JAMS.Job.PropertyName("Formatting Here")>>" or "<<JAMS.PropertyName("Formatting Here")>>".

Note: If you want the property to be used as a string use quotes when parsing "<<JAMS.Job.PropertyName>>". Alternatively if a property is an integer and you want to maintain this type, do not use quotes: $number = <<JAMS.Job.PropertyName>>

Job Properties Parsing	Copy Code
Write-Host "Job name: <<JAMS.Job.Name>>" Write-Host "The last successful completion of the Job was on <<JAMS.Job.LastSuccess("MM/DD/YY")>>" # # Accessing the current Job entry is done using the format: <<JAMS.PropertyName>> # $folderID = <<JAMS.ParentFolderID>> Write-Host "User Name: <<JAMS.UserName>>" # # It is also possible to directly use the values returned from the parsed # property in your source. # $descriptionLength = "<<JAMS.Job.Description>>".Length Write-Host "$descriptionLength" # # JAMS.Agent is a Boolean, so by adding $ in front of the parsed value you can use it # as you would any Boolean value. This is needed because the parsing is replaced # with the string True or False instead of $True or $False # if(! $<<JAMS.Agent>>) { Write-Host "This Job is not running on a remote JAMS Agent." }

Job Properties Parsing

Copy Code

Write-Host "Job name: <<JAMS.Job.Name>>"
Write-Host "The last successful completion of the Job was on <<JAMS.Job.LastSuccess("MM/DD/YY")>>"

#
# Accessing the current Job entry is done using the format: <<JAMS.PropertyName>>
#
$folderID = <<JAMS.ParentFolderID>>
Write-Host "User Name: <<JAMS.UserName>>"

#
# It is also possible to directly use the values returned from the parsed
# property in your source.
#
$descriptionLength = "<<JAMS.Job.Description>>".Length
Write-Host "$descriptionLength"

#
# JAMS.Agent is a Boolean, so by adding $ in front of the parsed value you can use it
# as you would any Boolean value. This is needed because the parsing is replaced
# with the string True or False instead of $True or $False
#
if(! $<<JAMS.Agent>>)
{
 Write-Host "This Job is not running on a remote JAMS Agent."
}

In PowerShell it is possible to maintain property types such as DateTime and Boolean when parsing by using casting as shown below. By defining the type of the Variable, PowerShell can cast the value returned from parsing as the correct type instead of treating it as a string.

Maintaining Property Type Using Casting	Copy Code
# # In order to maintain the type of the property you are parsing declare the # variable as the same data type as the JAMS property you are parsing. As # shown below this allows you to maintain types such as DateTime or Boolean. # This is done by using the format: [dataType]$varName = "<<parsing>>" # [int]$jobID = "<<JAMS.JamsEntry>>" Write-Host "$($jobID) \| $($jobID.GetType())" #output will be similar to: 1687 \| int # # Properties in Jams that are dateTime can be returned in various formats, so # in order to have a consistently working cast we need to specify the formatting as "O". # [System.DateTime]$TestTime = "<<JAMS.Job.LastSuccess("O")>>" Write-Host "$($TestTime) \| $($TestTime.GetType())" #output will be similar to: 07/22/2013 00:00:00 \| System.DateTime # # In order to maintain the type of a Boolean property you need to use the # format: [Bool]$testBool = $<<JAMS.PropertyName>> or # [Bool]$testBool = $<<JAMS.Job.PropertyName>> # [Bool]$onAgent = $<<JAMS.Agent>> Write-Host "$($testBool) \| $($testBool.GetType())" #output(If not running on an agent): False \| bool

Maintaining Property Type Using Casting

Copy Code

#
# In order to maintain the type of the property you are parsing declare the
# variable as the same data type as the JAMS property you are parsing. As
# shown below this allows you to maintain types such as DateTime or Boolean.
# This is done by using the format: [dataType]$varName = "<<parsing>>"
#
[int]$jobID = "<<JAMS.JamsEntry>>"
Write-Host "$($jobID) | $($jobID.GetType())"
#output will be similar to: 1687 | int

#
# Properties in Jams that are dateTime can be returned in various formats, so
# in order to have a consistently working cast we need to specify the formatting as "O".
#
[System.DateTime]$TestTime = "<<JAMS.Job.LastSuccess("O")>>"
Write-Host "$($TestTime) | $($TestTime.GetType())"
#output will be similar to: 07/22/2013 00:00:00 | System.DateTime

#
# In order to maintain the type of a Boolean property you need to use the
# format: [Bool]$testBool = $<<JAMS.PropertyName>> or
# [Bool]$testBool = $<<JAMS.Job.PropertyName>>
#
[Bool]$onAgent = $<<JAMS.Agent>>
Write-Host "$($testBool) | $($testBool.GetType())"
#output(If not running on an agent): False | bool

If your Job is being run as part of a Setup you can access the properties from the Setup definition by using the format: <<JAMS.Setup.PropertyName>>

Parsing Setup Definition Properties	Copy Code
Write-Host "Setup name: <<JAMS.Setup.Name>>" Write-Host "the Setup's description is <<JAMS.Setup.Description>>" $setupID = <<JAMS.Setup.SetupID>>

If your Job is running as part of a Setup it is also possible to access the properties of the Setup entry. This is different than the Setup definition because it is accessing the properties of the running Setup.

Accessing Setup Entry Properties	Copy Code
# # First assign the currently running Setup to a variable(such as $Setup) using the # format: $varName = Get-JamsEntry <<JAMS.MasterEntry>>. This allows you to get the # values of the Setup entry properties such as the current step or the user who # submitted the Setup. # $Setup = Get-JamsEntry <<JAMS.MasterEntry>> $stepNumber = $Setup.CurrentStep Write-Host "The Setup will only run from: $($Setup.ScheduleFromTime) to: $($Setup.ScheduleToTime)" # # These values can now be used directly in your code as you would any object in PowerShell. # $targetTime = $Setup.StartTime.addSeconds(10)

Accessing Setup Entry Properties

Copy Code

#
# First assign the currently running Setup to a variable(such as $Setup) using the
# format: $varName = Get-JamsEntry <<JAMS.MasterEntry>>. This allows you to get the
# values of the Setup entry properties such as the current step or the user who
# submitted the Setup.
#
$Setup = Get-JamsEntry <<JAMS.MasterEntry>>

$stepNumber = $Setup.CurrentStep
Write-Host "The Setup will only run from: $($Setup.ScheduleFromTime) to: $($Setup.ScheduleToTime)"

#
# These values can now be used directly in your code as you would any object in PowerShell.
#
$targetTime = $Setup.StartTime.addSeconds(10)

In summary, parsing allows you to easily access the properties of a CurJob or the definition of a Setup or Job. Building off of the above examples you can use parsing to perform complex tasks that suit your specific needs.

Click here for a downloadable sample.