Set Job Variables when submitting a job for execution #adTempus #api #version5

readme.md

This sample demonstrates how to define or override Job Variables when submitting a job for execution. Variables are defined or set at runtime using the JobExecutionSettings.JobVariables collection.

example.cs

	//Connect to the local adTempus server, using Windows authentication.
	using (var connection = Scheduler.Connect())
	{
		//Create a DataContext to work in. All object operations take place within this context.
		//Use a Using block so the context is disposed when we finish with it
		using (var context = connection.NewDataContext())
		{
			//Fetch the job named "My Test Job"
			var job = context.GetJob("My Test Job");
			if (null == job)
			{
				//job not found
				return;
			}

			var settings = new JobExecutionSettings();
			settings.Options = JobExecutionOptions.ForceNewInstance;

			/*
			Set Job Variable values for this instance only.
			If a variable with the same name is already defined for the job, it will be replaced with this value. Otherwise a new variable will be added for this instance only.
			
			The JobExecutionOptions.JobVariables collection is empty until you add variables to it--it does not get populated with the variables
			that are already defined for the job.
			
			We use AddOrReplace here, which specifies that the variable is added or replaced in the current collection--it does not affect
			whether the variable is replaced if it is previously defined in the job definition. If you add a variable to this collection and the job 
			already has a variable defined with that name, the value you set here will always replace the predefined value.
			
			AddOrReplace is generally preferable to using JobVariables.Add, as Add will throw an exception if the collection already
			has a variable with the same name.
			*/

			var variable=context.Create.JobVariable();
			variable.Name="MyVariable";
			variable.Value="Value set at execution";
			variable.AddToEnvironment=true;

			settings.JobVariables.AddOrReplace(variable);	//See comment above regarding use of AddOrReplace
			
			var result = job.Execute(settings);
			if (!result.JobSubmitted)
			{
				System.Diagnostics.Debug.WriteLine("Submission failed");
				foreach (var message in result.Messages)
				{
					System.Diagnostics.Debug.WriteLine(message.ToString());
				}
				return;
			}

			//The Instances collection contains all the instances created for this request.
			//(there will be more than one instance if the job was configured to run on Agents).
			//for this example we assume there's only one instance for the job
			var jobInstance = result.Instances[0];
			System.Diagnostics.Debug.WriteLine("Submitted instance " + jobInstance.InstanceID.ToString());

			//wait until the job finishes
			do
			{
				System.Threading.Thread.Sleep(5000);

				//refresh to get the most recent status for the instance
				jobInstance.Refresh();
			} while (jobInstance.IsRunning);

			System.Diagnostics.Debug.WriteLine("Instance finished with status " + JobStatusHelpers.GetJobStatusDescription(jobInstance.Status));


			//the JobExecutionSettings.ExecutionRequestID value is associated with all instances
			//submitted by this request and can be used to fetch all instances from this request if they
			//are needed later on:
			var instances = connection.JobServices.GetInstancesForRequest(settings.ExecutionRequestID);
		}

example.vb

Sub Main
        'Connect to the local adTempus server, using Windows authentication.
        Using connection = Scheduler.Connect()
            'Create a DataContext to work in. All object operations take place within this context.
            'Use a Using block so the context is disposed when we finish with it
            Using context = connection.NewDataContext()
                'Fetch the job named "My Test Job"
                Dim job = context.GetJob("My Test Job")
				
				If job Is Nothing
					'job not found
					Return
				End If

                Dim settings = New JobExecutionSettings()
                settings.Options = JobExecutionOptions.ForceNewInstance

	' 
	' 			Set Job Variable values for this instance only.
	' 			If a variable with the same name is already defined for the job, it will be replaced with this value. Otherwise a new variable will be added for this instance only.
	' 			
	' 			The JobExecutionOptions.JobVariables collection is empty until you add variables to it--it does not get populated with the variables
	' 			that are already defined for the job.
	' 			
	' 			We use AddOrReplace here, which specifies that the variable is added or replaced in the current collection--it does not affect
	' 			whether the variable is replaced if it is previously defined in the job definition. If you add a variable to this collection and the job 
	' 			already has a variable defined with that name, the value you set here will always replace the predefined value.
	' 			
	' 			AddOrReplace is generally preferable to using JobVariables.Add, as Add will throw an exception if the collection already
	' 			has a variable with the same name.
	' 			

			Dim variable = context.Create.JobVariable()
			variable.Name = "MyVariable"
			variable.Value = "Value set at execution"
			variable.AddToEnvironment = True

			settings.JobVariables.AddOrReplace(variable)    'See comment above regarding use of AddOrReplace

			Dim result = job.Execute(settings)
			If Not result.JobSubmitted Then
				Debug.WriteLine("Submission failed")
				For Each message In result.Messages
					Debug.WriteLine(message.ToString())
				Next
				Return
			End If

			'The Instances collection contains all the instances created for this request.
			'(there will be more than one instance if the job was configured to run on Agents).
			'for this example we assume there's only one instance for the job
			Dim jobInstance = result.Instances(0)
			Debug.WriteLine("Submitted instance " & jobInstance.InstanceID.ToString().ToString())

			'wait until the job finishes
			Do
				Threading.Thread.Sleep(5000)

				'refresh to get the most recent status for the instance
				jobInstance.Refresh()
			Loop While jobInstance.IsRunning

			Debug.WriteLine("Instance finished with status " & JobStatusHelpers.GetJobStatusDescription(jobInstance.Status).ToString())


			'the JobExecutionSettings.ExecutionRequestID value is associated with all instances
			'submitted by this request and can be used to fetch all instances from this request if they
			'are needed later on:
			Dim instances = connection.JobServices.GetInstancesForRequest(settings.ExecutionRequestID)
		End Using

	End Using
End Sub