Table of Contents

Class Job

Namespace
ArcanaDevelopment.adTempus.Client
Assembly
ArcanaDevelopment.adTempus.Client.dll

Represents a Job

public sealed class Job : ADTIndependentObject, ISupportJobVariables
Inheritance
object
Job
Implements

Remarks

When a job is created through ArcanaDevelopment.adTempus.Client.DataContext.CreateObject(ClassID) it is assigned to the root job group. If the caller does not have permission to assign jobs to the root group, the creation call will fail. Use ArcanaDevelopment.adTempus.Client.DataContext.CreateObject(ClassID,OID) or NewJob() to create a job within a specific group.

To fetch existing jobs, use GetJob(string)

Properties

APIExtensionData

Additional data stored by an API client

public string APIExtensionData { get; set; }

Property Value

string

Remarks

This information is not displayed in the user interface

APITags

List of tags for this job that are not displayed in the user interface

public StringList APITags { get; }

Property Value

StringList

Remarks

An API client can use this list to assign additional tags to the job that can be used by the API but are not displayed in the user interface

See Also

AgentType

If the job is on an Agent, indicates the AgentType of the Queue the job belongs to

public int AgentType { get; }

Property Value

int

AlreadyRunningBehavior

Determines how the job will be handled if another instance is already running when a new instance is triggered

public AlreadyRunningBehavior AlreadyRunningBehavior { get; set; }

Property Value

AlreadyRunningBehavior

AssemblyReferences

A semicolon-delimited list of any additional assemblies to be referenced when compiling variable functions used in this job.

public string AssemblyReferences { get; set; }

Property Value

string

ClassID

The Class ID for the object

[IgnoreDataMember]
public override ClassID ClassID { get; }

Property Value

ClassID

ClassKeyName

The key name for the class.

public override string ClassKeyName { get; }

Property Value

string

Remarks

This name the name used by adTempus to identify the class and is intended for programmatic use only. Use the ClassName for a user-friendly name.

ConditionFailureAction

Action to take if one or more Conditions fails

public ConditionFailureOptions ConditionFailureAction { get; set; }

Property Value

ConditionFailureOptions

ConditionRule

Determines how Conditions are evaluated

public ConditionRule ConditionRule { get; set; }

Property Value

ConditionRule

ConditionScript

Custom script used to evaluate the state of the Conditions for the job

[ReservedForFutureUse]
public Script ConditionScript { get; set; }

Property Value

Script

Conditions

The conditions that must be met before the job executes

public ConditionCollection Conditions { get; }

Property Value

ConditionCollection
See Also

Credentials

The CredentialProfile representing the user account that the job will run under

public CredentialProfile Credentials { get; set; }

Property Value

CredentialProfile

Remarks

The Credentials are required for all jobs

DescriptionOverride

Override for the system-generated description of the object

public string DescriptionOverride { get; set; }

Property Value

string

Remarks

This property is for use by user interface extensions

FullyQualifiedName

The fully-qualified name of the job (including the full path of the group)

public string FullyQualifiedName { get; }

Property Value

string

Remarks

For jobs in the root group, FullyQualifiedName is just the Name of the job. For jobs in groups below the root, the FullyQualifiedName is the full (backslash-delimited) path for the job (the FullyQualifiedName of the owning group plus the Name of the job

Group

The JobGroup that the job belongs to

public JobGroup Group { get; set; }

Property Value

JobGroup

Remarks

A Group is required.

HistoryRetentionLimit

Maximum time to retain history for this job

public int HistoryRetentionLimit { get; set; }

Property Value

int

Remarks

The unit for this value depends on the setting for HistoryRetentionOptions.

See Also

HistoryRetentionOptions

Override of history retention options for this job

public HistoryRetentionOptions HistoryRetentionOptions { get; set; }

Property Value

HistoryRetentionOptions

Remarks

Jobs are created with this set to UseDefault, which causes the job to use the default retention options specified for the server.

HoldType

The hold type for the job

public HoldType HoldType { get; set; }

Property Value

HoldType

Remarks

If the job's Group or Queue is held, setting a different HoldType here will not override the Group and/or Queue. That is, you cannot override a hold state applied at the Group or Queue level. Use GetEffectiveHoldType() to determine the effective hold type, factoring in the hold type of the group and queue.

See Also

InheritHoldType

Determines whether the job inherits its parent group's HoldType

public bool InheritHoldType { get; set; }

Property Value

bool

Remarks

InheritHoldType does not have any effect unless all parent groups have AllowHoldTypeOverride set to true.

When InheritHoldType is true, the effective hold type for the job is the job's HoldType combined with the parent group's EffectiveHoldType

See Also

IsDependent

Indicates whether the object is a dependent of (owned by) another object

[IgnoreDataMember]
public override bool IsDependent { get; }

Property Value

bool

Remarks

An independent object (IsDependent is false) is an object that can exist on its own without being part of another object. For example, Jobs, Job Groups, etc.

A dependent object (IsDependent is true) is a part of another object. For example, a JobStep cannot exist independently of a Job, so the JobStep is dependent.

Dependent objects cannot be directly fetched from the server: they are only fetched as part of the object they belong to. They also cannot be saved or deleted independently: they are automatically saved or deleted when the owning object is saved or deleted.

IsFromController 

public bool IsFromController { get; }

Property Value

bool

true if the connected server is an Agent and the job was sent from the Controller; false if the server is not an Agent or if the job was created directly on the Agent and is not managed by the Controller.

See Also

JobQueue

The System.Collections.Queue that the job belongs to

public JobQueue JobQueue { get; set; }

Property Value

JobQueue

Remarks

A Queue is required.

JobStatus

Returns a JobStatus object showing the status and statistics for the job

public JobStatus JobStatus { get; }

Property Value

JobStatus

Remarks

The JobStatus object retrieved through this process is current at the time the job is fetched or refreshed but otherwise does not update automatically. To get the latest status information call GetStatus(bool).

See Also

JobVariables

The job variables defined for the job

public JobVariableCollection JobVariables { get; }

Property Value

JobVariableCollection

Remarks

This collection only contains the variables defined explicitly for the job. Use GetInheritedVariables(bool) to retrieve variables inherited from higher levels (server, group, queue).

To override a variable set at a higher level, add a new variable to this collection with the same name and the desired value.

LogRetention

Maximum time to retain log entries for this job

[ReservedForFutureUse]
public int LogRetention { get; set; }

Property Value

int

Name

The user-supplied name for the job

public string Name { get; set; }

Property Value

string

Remarks

The Name must be unique within the parent JobGroup. However, the name is not used by adTempus to uniquely identify the job; the OID is used for this. Changing the Name has no effect on links to other objects within adTempus.

NamespaceImports

A semicolon-delimited list of any additional namespaces to be included when compiling variable functions used in this job.

public string NamespaceImports { get; set; }

Property Value

string

Priority

Specify the priority of this job within the queue

public int Priority { get; set; }

Property Value

int

Remarks

In a queue that limits the number of jobs that can run simultaneously, jobs with higher priorities are executed before jobs with lower priorities. New jobs have a default priority of 100. For queues with no limit, the Priority has no effect.

RemoteAgents

Status information for the remote agents where this job runs, if any.

public JobAgentJoinCollection RemoteAgents { get; }

Property Value

JobAgentJoinCollection

ResourceFailureAction

Action to take if one or more Resources for the job cannot be obtained

public ResourceFailureAction ResourceFailureAction { get; set; }

Property Value

ResourceFailureAction

ResourceWaitLimit

Maximum time to wait for resources to be available when running the job

[ReservedForFutureUse]
public int ResourceWaitLimit { get; set; }

Property Value

int

Resources

The resources that must be loaded before this job runs

public ResourceCollection Resources { get; }

Property Value

ResourceCollection
See Also

Responses

The responses that are defined for this job

public ResponseCollection Responses { get; }

Property Value

ResponseCollection

Remarks

This collection contains only the responses defined explicitly for the job, at the job level. The job will also execute responses inherited from the Group and Queue, and steps may define additional responses.

RestartOptions

Determines how the job is handled if it is missed or abandoned.

public RestartOptions RestartOptions { get; set; }

Property Value

RestartOptions

RunElevated

Determines if administrative privileges will be enabled when the job runs

public bool RunElevated { get; set; }

Property Value

bool

Remarks

This is equivalent to using the "Run as administrator" command in Windows. If this option is not checked, administrative privileges will not be enabled, and the program may not behave as you expect.

This setting has no effect if the CredentialProfile used for the job is not a user with Administrator permissions on the computer (you cannot get elevated privileges for a user who is not an Administrator).

ScriptLibraries

Script Libraries associated with this job

[ReservedForFutureUse]
public ScriptLibraryCollection ScriptLibraries { get; }

Property Value

ScriptLibraryCollection

StepExecutionRule

Determines how Steps will be executed

public StepExecutionSequence StepExecutionRule { get; set; }

Property Value

StepExecutionSequence

Steps

The steps to execute for this job

public JobStepCollection Steps { get; }

Property Value

JobStepCollection

Remarks

The step's StepNumber is assigned based on the step's order in this collection, and that is the default order for execution. To change a step's order in the collection, remove it and then insert it in the correct location.

See Also

SupportedResponseEvents

Gets a list of the events that are supported for Responses associated with this object.

public ReadOnlyCollection<SupportedResponseEvent> SupportedResponseEvents { get; }

Property Value

ReadOnlyCollection<SupportedResponseEvent>

SupportedSecurityActions

List of security actions supported by this object.

public override Dictionary<int, string> SupportedSecurityActions { get; }

Property Value

Dictionary<int, string>

A dictionary of the supported actions. The key is one of the SecurityPermission values and the value is the name of the permission (from GetSecurityPermissionName(SecurityPermission, string); a given SecurityPermission may use different names in different contexts).

TagList

Gets or sets the Tags as a comma-delimited string.

public string TagList { get; set; }

Property Value

string

Tags

User-defined tags assigned to the job (visible in the user interface)

public StringList Tags { get; }

Property Value

StringList
See Also

Triggers

The triggers that cause this job to execute

public TriggerCollection Triggers { get; }

Property Value

TriggerCollection

UpdateCycleID

Determines whether the cycle ID for the current scope will be updated when this job runs

public bool UpdateCycleID { get; set; }

Property Value

bool

UseInheritedResponses

Determines whether the job will execute Responses inherited from the Group or Queue

[ReservedForFutureUse]
public bool UseInheritedResponses { get; set; }

Property Value

bool

UserInteractionMode

The user interaction mode to use when running the job

public UserInteractionMode UserInteractionMode { get; set; }

Property Value

UserInteractionMode

UserInterfaceExtensionData

Extension data for the customer user interface for this object

public string UserInterfaceExtensionData { get; set; }

Property Value

string

UserInterfaceExtensionID

Extension ID of the customer user interface for this object

public string UserInterfaceExtensionID { get; set; }

Property Value

string

WaitStartLimit

Maximum time (in seconds) to wait for the previous instance to complete if AlreadyRunningBehavior is WaitThenSkip or WaitThenRun

public int WaitStartLimit { get; set; }

Property Value

int

Methods

AcknowledgeAllInstances()

Marks the status of all instances for this job as Acknowledged

[RequiredVersion(5, 0, 0, 0)]
public void AcknowledgeAllInstances()

Remarks

Requires ServerVersion 5.0 or later.

Marking an instance as Acknowledged removes it from the Failed Jobs view in the Console and clears its Failed or Warning status indicator.

ClearHistory(HistoryClearOptions)

Clears the history for the job, optionally resetting the statistics for the job.

public void ClearHistory(HistoryClearOptions options)

Parameters

NameTypeDescription
options HistoryClearOptions

Options for the operation

Remarks

Calling this method signals the server to purge the history and returns immediately; there may be a delay before the purge completes. If options contains ResetStatistics, the statistics tracked in the JobStatus are all reset to zero.

Clearing the history does not reset the instance numbering for the job back to 1.

Execute(JobExecutionSettings)

Submits the job for execution

public ExecuteJobResult Execute(JobExecutionSettings options)

Parameters

NameTypeDescription
options JobExecutionSettings

Options and settings for executing the job

Returns

ExecuteJobResult

An ExecuteJobResult containing the status of the execution request

Examples

This example demonstrates how to submit a job for execution and then wait until execution has completed. To do this, you must periodically refresh the status of each of the instances created by the execution request and wait until all have finished running.

void RunJobAndWait(Job job)
{
    var options = new JobExecutionSettings();

    //submit the job
    var result = job.Execute(options);

    if (!result.JobSubmitted)
    {
        //The job could not be submitted. The result.Messages collection will contain the error message(s)
        return;
    }

    var waitingInstances = new List<ExecutionHistoryItem>();

    //result.Instances has all the instances created for this request
    //make a new collection of them
    waitingInstances.AddRange(result.Instances);

    while (waitingInstances.Any())
    {
        //Sleep for some reasonable period before checking again
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(30));

        //look at each instance that we're still waiting on
        foreach (var instance in waitingInstances.ToArray())
        {
            //Refresh the instance to get its latest status from the server
            instance.Refresh();

            //The instance is created with state NotRun. If we poll the server before the execution process has gotten
            //underway it's possible the instance will still have that state, so we treat that the same as if it were running.
            //The IsRunning property returns true if the job is in any of the active job states
            if (instance.Status != JobState.NotRun && !instance.IsRunning)
            {
                //if the instance is no longer running, remove it from the list of instances we're waiting on.
                waitingInstances.Remove(instance);
            }
        }

        //if all instances have completed, waitingInstances will be empty and we're finished
    }
}
Private Sub RunJobAndWait(ByVal job As Job)
    Dim options = New JobExecutionSettings()

    'submit the job
    Dim result = job.Execute(options)

    If Not result.JobSubmitted Then
        'The job could not be submitted. The result.Messages collection will contain the error message(s)
        Return
    End If

    'result.Instances has all the instances created for this request
    'make a new collection of them
    Dim waitingInstances = New List(Of ExecutionHistoryItem)()
    waitingInstances.AddRange(result.Instances)

    While waitingInstances.Any()
        'Sleep for some reasonable period before checking again
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(30))

        'look at each instance that we're still waiting on
        For Each instance In waitingInstances.ToArray()
            'Refresh the instance to get its latest status from the server
            instance.Refresh()

            'The instance is created with state NotRun. If we poll the server before the execution process has gotten
            'underway it's possible the instance will still have that state, so we treat that the same as if it were running.
            'The IsRunning property returns true if the job is in any of the active job states
            If instance.Status <> JobState.NotRun AndAlso Not instance.IsRunning Then
                'if the instance is no longer running, remove it from the list of instances we're waiting on.
                waitingInstances.Remove(instance)
            End If
        Next

        'if all instances have completed, waitingInstances will be empty and we're finished
    End While
End Sub

Remarks

This method submits the job for execution and returns immediately; it does not wait for execution to complete.

If the job cannot be submitted (e.g., because the caller does not have Execute permission for the job), JobSubmitted will be false and Messages will contain one or more messages giving the error.

If the job is submitted, JobSubmitted will be true and Instances will contain ExecutionHistoryItem(s) representing the instances created as a result of the request. There may be more than one instance for a job in a Queue that runs on multiple targets (agents). In that case there will be one instance for each computer where the job will execute.

You also retain the ExecutionRequestID and use it in a call to GetInstancesForRequest(Guid) to retrieve the instances for this execution request.

To wait for the outcome of the job

GetEffectiveHoldType()

Gets the effective HoldType for the job (combining the HoldType for the job, queue, and group hierarchy).

public HoldType GetEffectiveHoldType()

Returns

HoldType

Remarks

The job's HoldType can be overridden by the hold type of the parent group(s) and the queue that the job belongs to. GetEffectiveHoldType looks at the settings for all of them to determine the hold type that currently applies to the job.

See Also

GetExecutionHistory(InstanceQueryParameters)

Fetches the history (instances) for this job

public ExecutionHistoryItemCollection GetExecutionHistory(InstanceQueryParameters parameters)

Parameters

NameTypeDescription
parameters InstanceQueryParameters

Parameters for selecting the instances to return. See Remarks for additional information.

Returns

ExecutionHistoryItemCollection

A collection containing the requested history records.

Remarks

This method returns a collection of ExecutionHistoryItem objects representing the instances that match the query parameters. Any LogMessages associated with those instances are returned automatically and are accessible through LogMessages. If you also need log messages that are not associated with an instance (such as job-level alerts) use GetLogMessages(LogQueryParameters) or GetHistoryAndMessages(InstanceQueryParameters, out ExecutionHistoryItemCollection, LogQueryParameters, out LogMessageCollection), which combines both history and log message fetches in a single call.

The TargetObjects collection for the parameters is cleared of all values and the job's OID is added. That is, this method will only return data for the current job. To query for multiple jobs use GetJobHistory(InstanceQueryParameters).

See Also

GetHistoryAndMessages(InstanceQueryParameters, out ExecutionHistoryItemCollection, LogQueryParameters, out LogMessageCollection)

Gets history (instances) and messages (job log) for the job

public void GetHistoryAndMessages(InstanceQueryParameters historyParameters, out ExecutionHistoryItemCollection history, LogQueryParameters logParameters, out LogMessageCollection messages)

Parameters

NameTypeDescription
historyParameters InstanceQueryParameters

Parameters for selecting the instances to return. Set to null if you don't want the history, but then you might as well call GetExecutionHistory(InstanceQueryParameters). See Remarks for additional information.
history ExecutionHistoryItemCollection

On return, contains the requested instances
logParameters LogQueryParameters

Parameters for selecting the log messages to return. Set to null if you don't want the messages, but then you might as well call GetLogMessages(LogQueryParameters).See Remarks for additional information.
messages LogMessageCollection

On return, contains the requested log messages

Remarks

The TargetObjects collection for historyParameters and logParameters are cleared of all values and the job's OID is added. That is, this method will only return data for the current job. To query for multiple jobs use GetHistoryAndMessages(InstanceQueryParameters, out ExecutionHistoryItemCollection, LogQueryParameters, out LogMessageCollection).

This method combines GetExecutionHistory(InstanceQueryParameters) and GetLogMessages(LogQueryParameters) in a single server call, making it more efficient than calling them separately if you need both instances and messages. If you only need one or the other, call the appropriate method.

Log messages associated with an instance are returned as part of that instance when you query the history here or with GetExecutionHistory(InstanceQueryParameters) and are accessible through LogMessages; they do not require the use of the logParameters or a separate call to GetLogMessages(LogQueryParameters). Using logParameters is only necessary to query for messages that are not associated with a specific instance.

See Also

GetInheritedVariables(bool)

Gets a collection containing the JobVariables inherited by this object, and optionally the variables for the object itself.

public JobVariableCollection GetInheritedVariables(bool includeSelf)

Parameters

NameTypeDescription
includeSelf bool

If true the returned collection contains both inherited variables and variables defined at this level. If false the results only include inherited variables.

Returns

JobVariableCollection

GetJobChain(Guid?)

Gets all jobs in the chain that contains this job.

public JobLinkResults GetJobChain(Guid? chainID)

Parameters

NameTypeDescription
chainID Guid?

If specified, only jobs participating in the specified chain are returned.

Returns

JobLinkResults

Remarks

GetJobChain returns all jobs that are linked to this job, directly or indirectly, through JobConditions, JobTriggers, and JobControlActions.

For example, if this job is called by a Response in JobA, and JobA has a condition on JobB, GetJobChain returns this job, JobA, and JobB.

GetLogMessages(LogQueryParameters)

Fetches log messages for this job

public LogMessageCollection GetLogMessages(LogQueryParameters parameters)

Parameters

NameTypeDescription
parameters LogQueryParameters

Parameters for selecting the messages to return. See Remarks for additional information.

Returns

LogMessageCollection

A collection containing the requested log messages.

Remarks

This method returns both instance-level and job-level (not associated with an instance) messages

The TargetObjects collection for the parameters is cleared of all values and the job's OID is added. The MessageSources filter is set to JobMessages. That is, this method will only return data for the current job. To query for multiple jobs use GetLogMessages(LogQueryParameters).

GetObjectDescription()

Gets a description of the object's key settings.

protected override string GetObjectDescription()

Returns

string

Remarks

This method is called by GetDescription() to get a user-friendly description of the object (such as its key settings) for display to the user. The description should contain enough information to distinguish this object from others of the same class.

GetStandardSupportedResponseEvents()

Gets the response events that are supported for jobs

public static List<SupportedResponseEvent> GetStandardSupportedResponseEvents()

Returns

List<SupportedResponseEvent>

GetStatus(bool)

Gets the status of the job, optionally refreshing from the server

public JobStatus GetStatus(bool refresh = false)

Parameters

NameTypeDescription
refresh bool

Indicates whether to refresh the status from the server. See Remarks.

Returns

JobStatus

Remarks

If GetStatus is called with refresh set to false, this is equivalent to using the JobStatus property, and the status is not updated from the server (it will reflect the status as of when the job was fetched, when the job was last refreshed, or the last time GetStatus was called). For the latest status set refresh to true, which fetches the latest information from the server.

GetTriggerStatus(OID)

Gets the TriggerStatus for the job or for a specified trigger.

[RequiredVersion(4, 3, 0, 0)]
public TriggerStatusCollection GetTriggerStatus(OID triggerOID)

Parameters

NameTypeDescription
triggerOID OID

The trigger to get the status for. Specify null to get the status for all triggers for the job.

Returns

TriggerStatusCollection

A collection of TriggerStatus objects with the status of the triggers.

Remarks

Note that not all triggers report status information.

OnEntityReloaded()

Called when the entity is reloaded from the server

protected override void OnEntityReloaded()

OnNewEntity()

Called when the entity is created

protected override void OnNewEntity()

Resync(int)

Resynchronizes status data for the job.

public void Resync(int options)

Parameters

NameTypeDescription
options int

Reserved for future use.

Remarks

Use this method to initiate a resync if the instance counts for the job are incorrect.

Terminate(TerminationOptions, int)

Terminates one or more instances of the job

public void Terminate(TerminationOptions options, int instanceID)

Parameters

NameTypeDescription
options TerminationOptions

Options specifying which instances are terminated
instanceID int

The InstanceID of the instance to terminate, if you only want to terminate a specific instance.

UpdateHoldType(HoldType, MissedJobCheckOptions, ChangeLogParameters, bool?)

Updates the HoldType for the Job immediately.

public void UpdateHoldType(HoldType newValue, MissedJobCheckOptions missedJobOptions, ChangeLogParameters auditRecord = null, bool? inherit = null)

Parameters

NameTypeDescription
newValue HoldType

The new setting for the object's HoldType
missedJobOptions MissedJobCheckOptions

Indicates how missed executions will be treated if the HoldType.DisableTriggers flag is being turned off. Reserved for future use: this parameter currently has no effect
auditRecord ChangeLogParameters

Optional audit record for change log and snapshot.
inherit bool?

New setting for the job's InheritHoldType. Set to null to keep the current setting.

Remarks

This method is equivalent to setting the HoldType and then calling Save. It makes an immediate server call to update the HoldType and no Save is required. The caller must have Modify or Hold/Release permission for the job.

WriteToConfigurationReport(IADTObjectConfigurationReportWriter)

Writes the object and any contained objects to a configuration report

public override void WriteToConfigurationReport(IADTObjectConfigurationReportWriter reportBuilder)

Parameters

NameTypeDescription
reportBuilder IADTObjectConfigurationReportWriter

The report builder to write the object to.

Inherited Members