Summary
Job Variables allow you to define changeable values that can be used throughout your jobs. While a job is executing, you can easily create and modify variables from within scripts. However, any changes made using the simple approach only affect the job in which the changes are made; other jobs are not affected.
In some cases you may want to programmatically make changes to variables and have those changes affect all jobs. For example, you may have variables that are used by several jobs in your nightly processing cycle, and you need to update these variables at the beginning of the cycle, setting the values based on the current date.
This article explains how to use the adTempus API to make the changes.
Note
Beginning with version 4, the Job Variable Update Task or Job Variable Update Action can be used to update variables.
Procedure
You will first create a Script Library that contains supporting code.You will then create a job that runs the script code to set the values.
Create the Script Library
1. In the adTempus Console, expand the Scripts folder, then right-click Script Libraries and choose New Script Library....
2. In the Script Library Properties window:
a. Name the library "SetVariables"
b. Select "VB.NET" for the Language
c. Erase the default script code and paste in the following code:
Imports System.Collections.Generic
Imports ArcanaDevelopment.adTempus.Client
'This code can be called from adTempus scripts to create or modify Job Variables for a Job Group.
'From your script, reference the SetVariables library, and then call the SetGroupVariable methods to
'set the variables. See www.arcanadev.com/support/kb/K00000379.aspx for more information.
Public Module SetVariables
'Sets a JobVariable for the specified group.
'This method will update the variable if it already exists, or create a new variable if it does not.
'Important: The job that calls this script must be running under the account of a user who has permission to update the target group.
'the groupName should be the fully-qualified name of the group. For example:
' "" or "\" for the root group
' "GroupLevel1" for a top-level group
' "GroupLevel1\GroupLevel2" for a second-level group
Public Sub SetGroupVariable(ByVal groupName As String, ByVal variableName As String, ByVal variableValue As String)
Dim session As Scheduler
Dim variable As JobVariable
Dim group As JobGroup
'create a new session to the local adTempus instance
session = CreateSession()
group = FindGroup(session, groupName)
If group Is Nothing Then
'the group does not exist
Throw New System.Exception("The requested group could not be found")
End If
'get the existing variable with the specified variableName, if there is one
variable = FindVariable(group.JobVariables, variableName)
If variable Is Nothing Then
'no variable has been defined with that name, so create a new JobVariable object, initialize it with the correct name, and add
'it to the server settings.
variable = CType(session.CreateObject(ClassIDEnum.CID_JobVariable), JobVariable)
variable.Name = variableName
group.JobVariables.Add(variable)
'else we will update the value for the variable that already existed.
End If
variable.Value = variableValue
group.Save()
End Sub
Private Const DEFAULT_JOB_GROUP_OID As String = "{2C13CBB7-57D7-44A7-A74C-92B9F92A2A01}:{9A3EA996-9137-4EA7-8CAC-55E70695B473}"
Private Function FindGroup(ByVal session As Scheduler, ByVal groupName As String) As JobGroup
Dim groupPath As New Queue(Of String)
Dim pathParts As System.Text.RegularExpressions.MatchCollection
pathParts = System.Text.RegularExpressions.Regex.Matches(groupName, "([^\\]+)")
For Each match As System.Text.RegularExpressions.Match In pathParts
groupPath.Enqueue(match.Value)
Next
If groupPath.Count > 0 AndAlso groupPath.Peek() = "Root" Then
groupPath.Dequeue()
End If
Dim group As JobGroup
group = CType(session.GetObject(DEFAULT_JOB_GROUP_OID), JobGroup)
Return FindGroup(group, groupPath)
End Function
Private Function FindGroup(ByVal currentGroup As JobGroup, ByVal groupPath As Queue(Of String)) As JobGroup
If groupPath.Count = 0 Then
Return currentGroup
End If
For Each group As JobGroup In currentGroup.Groups
If String.Compare(group.Name, groupPath.Peek, True) = 0 Then
groupPath.Dequeue()
Return FindGroup(group, groupPath)
End If
Next
Return Nothing
End Function
Private Function FindVariable(ByVal variables As JobVariables, ByVal variableName As String) As JobVariable
For Each variable As JobVariable In variables
If String.Compare(variable.Name, variableName, True) = 0 Then
Return variable
End If
Next
Return Nothing
End Function
'Sets a JobVariable at the server level.
'This method will update the variable if it already exists, or create a new variable if it does not.
'Important: The job that calls this script must be running under the account of a user who has permission to update server settings.
Public Sub SetServerVariable(ByVal variableName As String, ByVal variableValue As String)
Dim session As Scheduler
Dim settings As ServerSettings
Dim variable As JobVariable
'create a new session to the local adTempus instance
session = CreateSession()
'retrieve the server settings, which contain the job variables
settings = session.GetServerSettings()
'get the existing variable with the specified variableName, if there is one
variable = FindVariable(settings.JobVariables, variableName)
If variable Is Nothing Then
'no variable has been defined with that name, so create a new JobVariable object, initialize it with the correct name, and add
'it to the server settings.
variable = CType(session.CreateObject(ClassIDEnum.CID_JobVariable), JobVariable)
variable.Name = variableName
settings.JobVariables.Add(variable)
'else we will update the value for the variable that already existed.
End If
variable.Value = variableValue
settings.Save()
End Sub
Private Function CreateSession() As Scheduler
Dim app As Application
app = New Application
'create a new session to the local adTempus instance
Return app.Connect("", "")
End Function
End Module
d. Click OK to save the Script Library.
Set Variables from a Script
Once the Script Library has been created you can call the SetGroupVariable method from an adTempus script to set variable values.
To use the code defined in the Script Library:
1. Create a new job, or edit an existing job. Keep in mind the following points:
- The values that a job sees for the Job Variables are fixed at the time the job begins executing. Therefore changing variables using this code will not affect any jobs that are already running, including the job that is making the changes. Therefore you should make the variable changes in a standalone job that runs before any jobs that depend on the variables.
- The script uses the adTempus API to update the variables. The API is subject to the same security checks as the adTempus Console. Therefore you must run the job under the User Account of a user who has permission within adTempus to modify the Job Group whose variables you are updating.
2. On the Steps page of the Job Properties, add a new step, selecting the "Execute a script" option in the Select Task window.
3. In the Script Execution Task Properties window, select the "Execute a script stored in adTempus" option, then click the Select... button.
4. In the Select Script window, click New... to create a new script.
5. In the Script Properties window, select "VB.NET" as the script Language.
6. Under Included Script Libraries, check the "SetVariables" library.
7. Add whatever code you need to calculate the value(s) of the variable(s) you need to set.
8. To set the variable values, call the SetGroupVariable method using the following syntax:
where GroupName is the name of the group where you want to set the variable, VariableName is the variable's name, and VariableValue is the new value for the variable.
To set variables for the root group (represented by the base "Jobs" folder in the Console), specify an empty string for GroupName:
Imports System
Imports System.Collections
Imports ArcanaDevelopment.adTempus.Server
Public Class UserScript
Inherits ArcanaDevelopment.adTempus.ScriptEngine.UserScriptBase
Public Overrides Function Run() As Object
Dim runDate As String
runDate=DateTime.Now.ToString("yyyyMMdd")
SetGroupVariable("","RunDate", rundate)
adtempus.LogMessage(MessageTypeEnum.Informational, 0, "Set RunDate to " & runDate)
Return 0
End Function
End Class
Use a backslash to separate levels of hierarchy when settings values for groups below the first level:
SetGroupVariable("Top Level Group","SomeVariable", "some value")
SetGroupVariable("Top Level Group\Second Level Group","SomeOtherVariable", "some value")
If the Job Variable already exists, its value will be updated. If it does not exist, it will be created. The variable will retain the new value until it is modified by another script or by a user.
