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 variable definitions 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 without the need for scripting. This code is presented for use in scenarios where the task or action cannot be used to meet your needs.

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:
   1. Name the library "SetVariables"
   2. Select "VB.NET" for the Language

   3. Erase the default script code and paste in the following code:

      
      Imports System
      Imports System.Collections.Generic
      Imports ArcanaDevelopment.adTempus.Shared
      Imports ArcanaDevelopment.adTempus.ApplicationIntegration
      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/K00000555.aspx for more information.
      'NOTE: You can also use the Variable Update Task or Variable Update Action to update variables without the need for scripting.
      
      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)
      
      	'create a new session to the local adTempus instance
      	Using session = ArcanaDevelopment.adTempus.Client.Scheduler.Connect()
      		Using context = session.NewDataContext()
      			Dim group = context.GetJobGroup(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
      			Dim variable = group.JobVariables.GetVariable(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 group.
      				variable = CType(context.CreateObject(ClassId.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()
      			adTempus.LogMessage(MessageTypeEnum.Informational,0,String.Format("Updated variable {0} to ""{1}"" for Job Group ""{2}""",variableName,variableValue, group.FullyQualifiedName))
      		End Using
      	End Using
      End Sub
      
      '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)
      
      	'create a new session to the local adTempus instance
      	Using session = ArcanaDevelopment.adTempus.Client.Scheduler.Connect()
      		Using context=session.NewDataContext()
      			Dim settings = context.GetServerSettings()
      			Dim variable = settings.JobVariables.GetVariable(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(context.CreateObject(ClassId.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()
      			adTempus.LogMessage(MessageTypeEnum.Informational, 0, String.Format("Updated variable {0} to ""{1}"" for server settings", variableName, variableValue))
      		End Using
      	End Using
      End Sub
      
      
      End Module
      

   4. 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.

   To set the variable values, call the SetGroupVariable method using the following syntax:

   SetGroupVariable(GroupName,VariableName,VariableValue)

   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.Generic
   Imports ArcanaDevelopment.adTempus.Shared
   Imports ArcanaDevelopment.adTempus.ApplicationIntegration
   
   Public Class UserScript
       Inherits ArcanaDevelopment.adTempus.ApplicationIntegration.UserScriptBase
   
       Public Overrides Function Run() As Object
   
   		Dim runDate As String
   		runDate=DateTime.Now.ToString("yyyyMMdd")
   	
   		SetVariables.SetGroupVariable("","RunDate",runDate)
           Return 0
       End Function
   End Class

   Use a backslash to separate levels of hierarchy when settings values for groups below the first level:

   
   Imports System
   Imports System.Collections.Generic
   Imports ArcanaDevelopment.adTempus.Shared
   Imports ArcanaDevelopment.adTempus.ApplicationIntegration
   
   Public Class UserScript
       Inherits ArcanaDevelopment.adTempus.ApplicationIntegration.UserScriptBase
   
       Public Overrides Function Run() As Object
   
   		Dim runDate As String
   		runDate=DateTime.Now.ToString("yyyyMMdd")
   	
   		SetVariables.SetGroupVariable("Level 1 Group\Level 2 Group","RunDate",runDate)
           Return 0
       End Function
   End Class

   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.