Class DataContext

Namespace

ArcanaDevelopment.adTempus.Client

Assembly

ArcanaDevelopment.adTempus.Client.dll

Defines an isolation context within which most data fetch/update operations occur.

public sealed class DataContext

Inheritance

object

DataContext

Remarks

The DataContext provides the primary interface for fetching data and managing from an adTempus server.

While the Scheduler represents a connection to an adTempus server, Scheduler the DataContext allows a client to work with separate, isolated copies of objects from that server.

Each DataContext maintains a cache of all the objects that have been fetched through it, and guarantees that any operations you perform on an object with a given identity will operate on the same copy of the object.

For example, suppose you fetch a CredentialProfile for user "bob" through the DataContext. Subsequently you fetch a job that uses CredentialProfile "bob." When you ask the job for its CredentialProfile, the object you get back will be the same copy of the object that you previously fetched from the DataContext.

Conversely, DataContexts and the objects that belong to them are isolated from each other. If you fetch the CredentialProfile for "bob" through a second DataContext, you will get a separate copy of that CredentialProfile. If you make changes to that CredentialProfile, those changes will not be reflected in the copies that belong to other DataContexts.

To enforce this isolation, objects are not permitted to be used across DataContext boundaries. For example, if you fetch a CredentialProfile in DataContext A, you cannot assign that CredentialProfile to a Job that you fetched through DataContext B. If you try to do this, the assignment operation will throw a BoundaryViolationException.

The one exception to this rule is the %Scheduler.ReadOnlyDataContext% exposed by the Scheduler. This special context is intended to be used for fetching lists of reference data for use when editing other objects. Objects fetched through this DataContext can be used in other DataContexts. However, objects fetched through the ReadOnlyDataContext cannot be modified.

Generally a DataContext should be short-lived, discarded after updates made within the context have been saved. For example, in the adTempus Console, the list of job groups, jobs, etc., is fetched through a DataContext that is kept alive for the entire time the Console is running, but the data fetched through that DataContext is not updated in the Console. Instead, when a user wants to edit a Job or other object, the Console creates a new DataContext and fetches a copy of the desired job into that new DataContext. All edit operations now operate on objects in this separate context, keeping them isolated from the rest of the Console, and vice-versa. For example,

• The job list in the Console is refreshed from the server periodically. Since this operation uses a different context, the copy of the Job that is being edited is not overwritten by the refresh operation.
• Similarly, in-progress changes to the Job being edited are not reflected elsewhere in the Console until the job has been saved.

Once the user has finished editing the job (saving or discarding the changes), the DataContext is disposed.

To create a new DataContext, use NewDataContext().

Properties

Create

Contains methods for creating new objects

public ObjectFactory Create { get; }

Property Value

ObjectFactory

IsReadOnly

Indicates whether this context is read-only.

public bool IsReadOnly { get; }

Property Value

bool

Remarks

If the IsReadOnly is True, then all objects in the context are read-only, and attempts to modify them will result in an exception.

Scheduler

Gets the Scheduler session that this DataContext belongs to.

public Scheduler Scheduler { get; }

Property Value

Scheduler

Methods

CanCreateObject(ClassID)

Indicates whether the caller has permission to create objects of the specified class.

public bool CanCreateObject(ClassID cid)

Parameters

Name	Type	Description
cid	ClassID	The Class ID.

Returns

bool

True if the caller has permission to create objects of the class, or False otherwise.

Remarks

For a Job or JobGroup use CanCreateObject(ClassID, OID).

See Also

Create

CanCreateObject(ClassID, OID)

Indicates whether the caller has permission to create objects of the specified class.

public bool CanCreateObject(ClassID cid, OID parentOID)

Parameters

Name	Type	Description
cid	ClassID	The Class ID.
parentOID	OID	The OID of the parent object, if any. See Remarks.

Returns

bool

True if the caller has permission to create objects of the class, or False otherwise.

Remarks

For a Job or JobGroup the OID of the parent JobGroup must be specified in parentOID, because permission to create depends on permission to create within the parent Group.

CanDuplicateObject(ADTObject)

Indicates whether the caller has permission to duplicate the specified object.

public bool CanDuplicateObject(ADTObject source)

Parameters

Name	Type	Description
source	ADTObject	The object to check permissions for

Returns

bool

CanPerformOnObject(OID, SecurityPermission)

Determines whether the caller can perform the specified action on the specified object.

public bool CanPerformOnObject(OID oid, SecurityPermission action)

Parameters

Name	Type	Description
oid	OID	The OID of the object to check permission for.
action	SecurityPermission	The security action requested.

Returns

bool

True if the user can perform the requested action or False otherwise.

CountJobHistory(InstanceQueryParameters)

Gets a count of the number of job instances matching a filter

public int CountJobHistory(InstanceQueryParameters parameters)

Parameters

Name	Type	Description
parameters	InstanceQueryParameters	Query parameters specifying the messages to return

Returns

int

Remarks

In some circumstances (such as when the parameters does not filter by job) returned count include records that the caller does not have permission to view and therefore may be higher than the number of records that could actually be retrieved using GetLogMessages(LogQueryParameters).

See Also

GetJobHistoryWithRecordCount(InstanceQueryParameters, out int)

GetJobHistory(InstanceQueryParameters)

CountLogMessages(LogQueryParameters)

Gets a count of the number of log messages matching a filter

public int CountLogMessages(LogQueryParameters parameters)

Parameters

Name	Type	Description
parameters	LogQueryParameters	Query parameters specifying the messages to return

Returns

int

Remarks

In some circumstances (such as when the parameters does not filter by job) returned count include records that the caller does not have permission to view and therefore may be higher than the number of records that could actually be retrieved using GetLogMessages(LogQueryParameters).

See Also

GetLogMessagesWithRecordCount(LogQueryParameters, out int)

GetLogMessagesWithRecordCount(LogQueryParameters, out int)

GetLogMessages(LogQueryParameters)

CreateObject(ClassID)

Creates an object of the specified class.

public ADTObject CreateObject(ClassID cid)

Parameters

Name	Type	Description
cid	ClassID	The ID of the class to create.

Returns

ADTObject

A new object of the specified class.

Remarks

When you call this method to create a new Job or JobGroup, the new object will be created in the Root group. If the caller does not have permission to create jobs/groups in the Root group, the call will fail with a PermissionDeniedException. To avoid this, use NewJob() and NewGroup() instead, to create the new job or group directly in the target group.

Exceptions

PermissionDeniedException

Thrown if the caller does not have permission to create objects of the specified type.

CreateUnitOfWork()

Creates a new UnitOfWork.

public UnitOfWork CreateUnitOfWork()

Returns

UnitOfWork

Exceptions

InvalidOperationException

Thrown if IsReadOnly is true.

Dispose()

Releases all resources held by the DataContext.

public void Dispose()

DoFastJobLookup(string)

Performs a quick, minimal lookup to find jobs that match a textToMatch

public ReadOnlyCollection<JobLookupInfo> DoFastJobLookup(string textToMatch)

Parameters

Name	Type	Description
textToMatch	string	The name or partial name to match. See Remarks.

Returns

ReadOnlyCollection<JobLookupInfo>

A collection of JobLookupInfo representing the matching jobs, if any.

Remarks

This method supports the "Go to Job" feature in the Console. That feature calls this method each time a new character is entered in the search box, to quickly return jobs that match the text being entered.

The textToMatch is the full or partial job name to match, optionally including the group name (separated from the job name by "\". The method finds all jobs with names (and optionally group names) that contain the provided textToMatch.

The method returns only minimal information about the job, to make it efficient to call repeatedly.

DuplicateObject(OID)

Returns a duplicate copy of an object.

public ADTObject DuplicateObject(OID oid)

Parameters

Name	Type	Description
oid	OID	The OID of the object to duplicate.

Returns

ADTObject

A new copy of the object.

Remarks

This method should only be called for independent objects.

Calling DuplicateObject is equivalent to calling Duplicate() but eliminates the need to fetch the job from the server first.

This method is intended for use in scenarios where you want to duplicate a top-level object and edit the new object in a different DataContext than the original (without this method you would need to fetch the object in the new context, then call Duplicate on the object to create the new copy).

~DataContext()

protected ~DataContext()

FindVariablesAndInlineFunctions(TokenSearchOptions, ADTObject[], out ReadOnlyCollection<TokenFindResult>, out MessageCollection)

Searches for job variables (definition and uses) and inline function (uses)

[RequiredVersion(5, 0, 0, 0)]
public void FindVariablesAndInlineFunctions(TokenSearchOptions options, ADTObject[] objectsToSearch, out ReadOnlyCollection<TokenFindResult> results, out MessageCollection messages)

Parameters

Name	Type	Description
options	TokenSearchOptions	Options defining the behavior of the search/replace operation
objectsToSearch	ADTObject[]	Collection of objects to search in. See Remarks.
results	ReadOnlyCollection<TokenFindResult>	Returns the results of the operation
messages	MessageCollection	Returns any error messages encountered during the operation.

Remarks

This overload searches the objects in objectsToSearch (and any dependencies). The search is based on the current state of the object (on the client) and therefore takes into account changes that have not yet been saved to the server.

The search also includes the classes and objects specified in IncludeClasses, IncludeObjects, and ExcludeObjects members of the options.

FindVariablesAndInlineFunctions(TokenSearchOptions, out ReadOnlyCollection<TokenFindResult>, out MessageCollection)

Searches for job variables (definition and uses) and inline function (uses)

[RequiredVersion(5, 0, 0, 0)]
public void FindVariablesAndInlineFunctions(TokenSearchOptions options, out ReadOnlyCollection<TokenFindResult> results, out MessageCollection messages)

Parameters

Name	Type	Description
options	TokenSearchOptions	Options defining the behavior of the search/replace operation
results	ReadOnlyCollection<TokenFindResult>	Returns the results of the operation
messages	MessageCollection	Returns any error messages encountered during the operation.

Remarks

The search operation is performed on the server and therefore does not take account of any unsaved changes to objects. To search an object that may have unsaved client-side changes, use FindVariablesAndInlineFunctions(TokenSearchOptions, ADTObject[], out ReadOnlyCollection<TokenFindResult>, out MessageCollection).

GetAlertNotificationRules(ObjectFetchOptions)

Gets the AlertNotificationRules defined for the server

public AlertNotificationRuleCollection GetAlertNotificationRules(ObjectFetchOptions options)

Parameters

Name	Type	Description
options	ObjectFetchOptions	Options that control the fetch operation

Returns

AlertNotificationRuleCollection

GetCredentialProfile(string)

Gets the Windows Credential Profile with the specified name.

public CredentialProfile GetCredentialProfile(string userName)

Parameters

Name	Type	Description
userName	string	The user ID of the profile to fetch.

Returns

CredentialProfile

The profile, or null if the profile does not exist.

GetCredentialProfile(string, string, string)

Gets the Credential Profile with the specified name and type.

public CredentialProfile GetCredentialProfile(string userName, string profileType, string credentialSelector)

Parameters

Name	Type	Description
userName	string	The user ID of the profile to fetch.
profileType	string	The type of profile to fetch. Specify null for a default Windows credential profile.
credentialSelector	string	The profile selector/discriminator to use. Specify null or empty string when searching for Windows credentials.

Returns

CredentialProfile

The profile, or null if the profile does not exist.

GetCredentialProfiles(string, string)

Fetches all Credential Profiles of the specified type.

public CredentialProfileCollection GetCredentialProfiles(string profileType, string credentialSelector)

Parameters

Name	Type	Description
profileType	string	The profile type to fetch. Specify "*" for all types, an empty string ("") for Windows credentials, or the name of a credential type.
credentialSelector	string	The profile selector/discriminator to use. Specify null or empty string when searching for Windows credentials.

Returns

CredentialProfileCollection

All Credential Profiles of the requested type for which the caller has at least List permission.

GetCredentialProfiles(string, string, ObjectFetchOptions, int, ref bool)

Fetches all Credential Profiles of the specified type.

public CredentialProfileCollection GetCredentialProfiles(string profileType, string credentialSelector, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
profileType	string	The profile type to fetch. Specify "*" for all types, an empty string ("") for Windows credentials, or the name of a credential type.
credentialSelector	string	The profile selector/discriminator to use. Specify null or empty string when searching for Windows credentials.
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

CredentialProfileCollection

All Credential Profiles of the requested type for which the caller has at least List permission.

GetDescriptionForObject(OID, string)

Gets a description for an object, given its OID

public string GetDescriptionForObject(OID oid, string targetComputerName = null)

Parameters

Name	Type	Description
oid	OID	The OID of the object to look up.
targetComputerName	string	Reserved for future use.

Returns

string

The description (from GetDescription() of the object, or null if the object does not exist.

Remarks

This method allows you to retrieve the description for an object even if the caller does not otherwise have permission to view it.

GetEffectivePermissions(params OID[])

Gets the effective permission sets for one or more objects.

public Dictionary<OID, int[]> GetEffectivePermissions(params OID[] requestedOIDs)

Parameters

Name	Type	Description
requestedOIDs	OID[]	The OIDs of the object(s) to check permissions for.

Returns

Dictionary<OID, int[]>

A dictionary of permission sets for the objects.

Remarks

Each item is an array of uints representing all the permissions that the caller has for the object. The values may be any of the values from SecurityPermission, or extended values.

Important: When checking to see if a specific permission is present, you must test separately for the presence of SecurityPermission.FullControl. If SecurityPermission.FullControl is present then the caller is authorized to perform any action, but other actions will not be explicitly included in the list. Use CanPerform(IEnumerable<int>, SecurityPermission) to properly check for a permission.

If the array of permissions is empty, the object could not be found or the caller does not have any permissions.

GetExclusionPeriod(string)

Gets the ExclusionPeriod with the specified name

[RequiredVersion(5, 0, 0, 0)]
public ExclusionPeriod GetExclusionPeriod(string name)

Parameters

Name	Type	Description
name	string	The name to look for. Matching is case-insensitive. Partial matching is not supported.

Returns

ExclusionPeriod

The requested Exclusion Period, or null if the Exclusion Period does not exist or the caller does not have at least View permission for it.

GetExclusionPeriods()

Gets all ExclusionPeriods the user has permission to view

[RequiredVersion(5, 0, 0, 0)]
public ExclusionPeriodCollection GetExclusionPeriods()

Returns

ExclusionPeriodCollection

GetFastJobTree(SecurityPermission, bool, bool)

Returns a minimal representation of the full job hierarchy.

public FastTreeGroup GetFastJobTree(SecurityPermission requiredPermission, bool includeGroupsWithNoJobs, bool includeJobs)

Parameters

Name	Type	Description
requiredPermission	SecurityPermission	The minimum permission required. Only jobs and groups for which the caller has this level of permission will be returned.
includeGroupsWithNoJobs	bool	If true, the results will include all groups the user has permission for. If false, any group that do not contain jobs (directly or in sub-groups) will not be returned.
includeJobs	bool	If true, the results will include all jobs the caller has permission for. If false, the results will only include groups.

Returns

FastTreeGroup

A FastTreeGroup representing the root job group.

Remarks

This method is only supported on server version 5.0 or later. If the connected server is older, GetFastJobTree calls GetJobTree(OID, bool, bool, bool) and translates the results. Because GetJobTree returns more data from the server GetFastJobTree will perform more slowly in this scenario than against a server running version 5 or later.

GetFileServiceProvider(string)

Gets the FileServiceProvider with the specified ServiceName

public FileServiceProvider GetFileServiceProvider(string serviceName)

Parameters

Name	Type	Description
serviceName	string	The name to look for. Matching is case-insensitive. Partial matching is not supported.

Returns

FileServiceProvider

The requested provider, or null if the provider does not exist or the caller does not have at least View permission for it.

GetFileServiceProviders(params string[])

Gets all FileServiceProviders of the specified type(s)

public FileServiceProviderCollection GetFileServiceProviders(params string[] providerTypes)

Parameters

Name	Type	Description
providerTypes	string[]	The type(s) of the providers to fetch, or null to return all providers.

Returns

FileServiceProviderCollection

GetFileServiceProviders(string[], ObjectFetchOptions, int, ref bool)

Gets all FileServiceProviders of the specified type(s), with paging

public FileServiceProviderCollection GetFileServiceProviders(string[] providerTypes, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
providerTypes	string[]	The type(s) of the providers to fetch, or null to return all providers.
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

FileServiceProviderCollection

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

Gets job history and log messages

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

Parameters

Name	Type	Description
historyParameters	InstanceQueryParameters	Query parameters specifying the history records to return
history	ExecutionHistoryItemCollection	Returns the matching instances
logParameters	LogQueryParameters	Query parameters specifying the log messages to return
messages	LogMessageCollection	Returns the matching messages

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) specify logParameters to return those messages in messages.

See Also

GetJobHistory(InstanceQueryParameters)

GetLogMessages(LogQueryParameters)

GetExecutionHistory(InstanceQueryParameters)

GetLogMessages(LogQueryParameters)

GetHolidaySet(string)

Gets the Holiday Set with the specified name.

public SharedSchedule GetHolidaySet(string setName)

Parameters

Name	Type	Description
setName	string	The name of the Holiday Set to fetch.

Returns

SharedSchedule

The requested holiday set, or null if the schedule does not exist.

GetHolidaySets()

Gets all Holiday Sets the user has permission for.

public SharedScheduleCollection GetHolidaySets()

Returns

SharedScheduleCollection

All Holiday Sets for which the caller has at least List permission.

GetHolidaySets(ObjectFetchOptions, int, ref bool)

Gets all Holiday Sets the user has permission for.

public SharedScheduleCollection GetHolidaySets(ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

SharedScheduleCollection

All Holiday Sets for which the caller has at least List permission.

GetJob(string)

Gets the Job with the specified name.

public Job GetJob(string jobName)

Parameters

Name	Type	Description
jobName	string	The fully-qualified name of the job to fetch (see Remarks).

Returns

Job

The Job, or null if no matching object is found.

Remarks

If the job is contained in a group, the full path to the job must be included in the form "Group Level 1\Group Level 2\Job Name". For a job in the root group, specify "\Job Name". To search all groups, specify only the name (e.g., "Job Name").

Exceptions

MultipleMatchException

Thrown if more than one job matches the criteria. Use GetJobs instead to get multiple matches.

GetJobChain(IEnumerable<OID>, Guid?)

Gets the requested jobs and all jobs linked to them through Conditions, Responses, and Triggers.

public JobLinkResults GetJobChain(IEnumerable<OID> oids, Guid? chainID)

Parameters

Name	Type	Description
oids	IEnumerable<OID>	The OIDs to fetch. See Remarks.
chainID	Guid?	If specified, only jobs participating in the specified chain are returned.

Returns

JobLinkResults

Remarks

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

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.

The oids collection can also include JobGroup or JobQueue oids. In this case GetJobChain processes all jobs in the specified groups and queues.

This method supports the Job Flow Diagram feature in the Console.

GetJobExecutionTimes(JobQueryParameters, DateTime, DateTime)

Gets scheduled job executions that meet the specified criteria.

public ReadOnlyCollection<JobExecutionTimes> GetJobExecutionTimes(JobQueryParameters queryParameters, DateTime startDateTime, DateTime endDateTime)

Parameters

Name	Type	Description
queryParameters	JobQueryParameters	Query parameters to filter the jobs considered.
startDateTime	DateTime	The earliest time (inclusive) to consider. Specify the date/time in the timezone of the target server (available from ServerTimeZone).
endDateTime	DateTime	The latest time (inclusive) to consider.Specify the date/time in the timezone of the target server (available from ServerTimeZone).

Returns

ReadOnlyCollection<JobExecutionTimes>

A collection of JobExecutionTimes with one item for each job that is scheduled for execution during the specified date/time range. The ExecutionTimes collection will contain a value for each scheduled execution date/time for the job.

See Also

GetJobMonitorData(JobMonitorViewFetchOptions, InstanceQueryParameters, DateTime, DateTime, out DateTime, ref DateTime?, out ReadOnlyCollection<JobExecutionTimes>, out ExecutionHistoryItemCollection)

GetJobGroup(string)

Gets the JobGroup with the specified name.

public JobGroup GetJobGroup(string groupName)

Parameters

Name	Type	Description
groupName	string	The fully-qualified name of the group to fetch (see Remarks). Specify null or an empty string to get the root group.

Returns

JobGroup

The Job Group, or null if no matching object is found.

Remarks

If the group is contained in a parent group, the full path to the group must be included in the form "Group Level 1\Group Level 2\Group Level 3".

Exceptions

MultipleMatchException

Thrown if more than one job matches the criteria. Use GetJobs(string) instead to get multiple matches.

GetJobGroups(string)

Gets the Job Groups with the specified name.

public JobGroupCollection GetJobGroups(string groupName)

Parameters

Name	Type	Description
groupName	string	The fully-qualified name of the group to fetch (see Remarks). Specify null or an empty string to get the root group.

Returns

JobGroupCollection

The matching Job Groups

Remarks

If the group is contained in a parent group, the full path to the group must be included in the form "Group Level 1\Group Level 2\Group Level 3" (to fetch the group "Group Level 3".

GetJobGroups(string, ObjectFetchOptions, int, ref bool)

Gets the Job Groups with the specified name.

public JobGroupCollection GetJobGroups(string groupName, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
groupName	string	The fully-qualified name of the group to fetch (see Remarks). Specify null or an empty string to get the root group.
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

JobGroupCollection

The matching Job Groups

Remarks

If the group is contained in a parent group, the full path to the group must be included in the form "Group Level 1\Group Level 2\Group Level 3" (to fetch the group "Group Level 3".

GetJobHistory(InstanceQueryParameters)

Gets job history records matching a filter

public ExecutionHistoryItemCollection GetJobHistory(InstanceQueryParameters parameters)

Parameters

Name	Type	Description
parameters	InstanceQueryParameters	Query parameters specifying the history records to return

Returns

ExecutionHistoryItemCollection

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 GetHistoryAndMessages(InstanceQueryParameters, out ExecutionHistoryItemCollection, LogQueryParameters, out LogMessageCollection) instead.

See Also

GetExecutionHistory(InstanceQueryParameters)

GetLogMessages(LogQueryParameters)

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

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

GetJobHistoryWithRecordCount(InstanceQueryParameters, out int)

Gets job instances matching a filter and returns a count of the records available

public ExecutionHistoryItemCollection GetJobHistoryWithRecordCount(InstanceQueryParameters parameters, out int recordCount)

Parameters

Name	Type	Description
parameters	InstanceQueryParameters	Query parameters specifying the instances to return
recordCount	int	Returns the total number of records that match the query parameters. See Remarks.

Returns

ExecutionHistoryItemCollection

See Also

CountJobHistory(InstanceQueryParameters)

GetJobHistory(InstanceQueryParameters)

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

GetJobMonitorData(JobMonitorViewFetchOptions, InstanceQueryParameters, DateTime, DateTime, out DateTime, ref DateTime?, out ReadOnlyCollection<JobExecutionTimes>, out ExecutionHistoryItemCollection)

Gets information about past, current, and future executions of jobs

public void GetJobMonitorData(JobMonitorViewFetchOptions fetchOptions, InstanceQueryParameters queryParameters, DateTime startDateTime, DateTime endDateTime, out DateTime calculatedRangeEnd, ref DateTime? lastFetchTimeUTC, out ReadOnlyCollection<JobExecutionTimes> scheduledExecutions, out ExecutionHistoryItemCollection instances)

Parameters

Name	Type	Description
fetchOptions	JobMonitorViewFetchOptions	Options specifying which data to return
queryParameters	InstanceQueryParameters	Query parameters for selecting the instances to return. Can be null if no filtering is required.
startDateTime	DateTime	The earliest date/time to fetch data for. Specify in the time zone of the adTempus server (available from ServerTimeZone).
endDateTime	DateTime	The latest date/time to fetch data for. Specify in the time zone of the adTempus server (available from ServerTimeZone).
calculatedRangeEnd	DateTime	Indicates the latest date/time for which the scheduler has calculated runtimes. If the endDateTime is later than the calculatedRangeEnd, the calculatedRangeEnd is used instead of the endDateTime.
lastFetchTimeUTC	DateTime?	Set to null on first call. On return, will contain a reference timestamp that should be passed in the next call. See Remarks.
scheduledExecutions	ReadOnlyCollection<JobExecutionTimes>	On return, contains information about scheduled executions, if fetchOptions contains ScheduledExecutions. If this flag is not included, scheduledExecutions will be null.
instances	ExecutionHistoryItemCollection	Contains the instances representing current executions (fetchOptions contains ActiveInstances) and/or past executions (fetchOptions contains PastInstances). If neither flag is set, instances may be null.

Remarks

This method supports the Job Monitor view in the Console. It can return information about past, current, and future executions of specified jobs.

The queryParameters specifies which jobs to select instances for.

The lastFetchTimeUTC is used to limit the return of redundant data. On first call of the method, set this parameter to null. On return, it will contain a timestamp from the server. On each subsequent call, pass the value returned from the previous call. The server will generally return only instances with state changes since the specified timestamp. However, in some cases (such as a clock change on the server) the server may still perform a full refresh. On the client, therefore, you must maintain state information between calls and merge the returned data with the previous data. If the client cannot maintain state, set this parameter to null on each call to force a full data fetch.

The calculatedRangeEnd indicates how far into the future the scheduling engine has calculated runtimes for (generally this is slightly more than 1 year from the current time). If your endDateTime is later than this, the calculatedRangeEnd will be used as the end of the range (it is not possible to force the scheduler to calculate a longer range from the client).

See Also

GetJobExecutionTimes(JobQueryParameters, DateTime, DateTime)

GetJobQueue(string)

Gets the Job Queue with the specified name.

public JobQueue GetJobQueue(string queueName)

Parameters

Name	Type	Description
queueName	string	The name of the Queue to fetch. Specify null or an empty string to get the default queue.

Returns

JobQueue

The Job Queue, or null if no matching object is found.

GetJobQueueStubs()

Gets stubs for all Job Queues the caller has permission for

public JobQueueCollection GetJobQueueStubs()

Returns

JobQueueCollection

A collection containing stubs for all Queues the caller has at least View permission for

GetJobQueues()

Gets all Job Queues the caller has permission for

public JobQueueCollection GetJobQueues()

Returns

JobQueueCollection

All Job Queues that the caller has at least View permission for

GetJobQueues(ObjectFetchOptions, int, ref bool)

Gets all Job Queues the caller has permission for, with paging

public JobQueueCollection GetJobQueues(ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

JobQueueCollection

The matching Job Groups

Remarks

If the group is contained in a parent group, the full path to the group must be included in the form "Group Level 1\Group Level 2\Group Level 3" (to fetch the group "Group Level 3".

GetJobTree(OID, bool, bool, bool)

Gets jobs and sub-groups starting from a specified group and including additional information for display in the user interface

public JobGroup GetJobTree(OID baseGroupOID, bool recursive, bool includeGroups, bool includeJobs)

Parameters

Name	Type	Description
baseGroupOID	OID	The OID of the JobGroup to use as the starting point for the tree. Use RootGroup to return all groups and jobs on the server.
recursive	bool	If true, works recursively to return all levels of group below the starting point. If false, only information about the group represented by baseGroupOID and its jobs is returned.
includeGroups	bool	Specifies whether child groups should be returned
includeJobs	bool	Specifies whether jobs should be returned

Returns

JobGroup

Remarks

This method is intended to be used for listing jobs and groups in the user interface. It returns stubs for the groups and jobs, which contain only minimal descriptive information and not full properties and relations (see Remarks).

JobGroups returned by this method also have several properties set that are not otherwise returned by the server:

• ActiveJobs
• FailedJobs
• WarningJobs
• GetInstanceCounts()

GetDescription()

GetJobs(JobFetchFilter, ObjectFetchOptions, int, ref bool)

Gets jobs from the server.

public JobCollection GetJobs(JobFetchFilter fetchCriteria, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
fetchCriteria	JobFetchFilter	Criteria to filter the jobs to be returned
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

JobCollection

Remarks

If the job is contained in a group, the full path to the job must be included in the form "Group Level 1\Group Level 2\Job Name". For a job in the root group, specify "\Job Name". To search all groups, specify only the name (e.g., "Job Name").

GetJobs(OID[], ObjectFetchOptions, int, ref bool)

Gets specific jobs from the server with paging

public JobCollection GetJobs(OID[] oids, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
oids	OID[]	The OIDs of the jobs to fetch
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

JobCollection

GetJobs(string)

Gets the Jobs that match the specified name.

public JobCollection GetJobs(string jobName)

Parameters

Name	Type	Description
jobName	string	The fully-qualified name of the job to fetch (see Remarks).

Returns

JobCollection

The Job, or null if no matching object is found.

Remarks

If the job is contained in a group, the full path to the job must be included in the form "Group Level 1\Group Level 2\Job Name". For a job in the root group, specify "\Job Name". To search all groups, specify only the name (e.g., "Job Name").

GetJobs(string, ObjectFetchOptions, int, ref bool)

Gets jobs from the server.

public JobCollection GetJobs(string jobName, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
jobName	string	The fully-qualified name of the job to fetch (see Remarks).
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

JobCollection

Remarks

If the job is contained in a group, the full path to the job must be included in the form "Group Level 1\Group Level 2\Job Name". For a job in the root group, specify "\Job Name". To search all groups, specify only the name (e.g., "Job Name").

GetLogMessages(LogQueryParameters)

Gets log messages matching a filter

public LogMessageCollection GetLogMessages(LogQueryParameters parameters)

Parameters

Name	Type	Description
parameters	LogQueryParameters	Query parameters specifying the messages to return

Returns

LogMessageCollection

See Also

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

GetLogMessagesWithRecordCount(LogQueryParameters, out int)

GetLogMessages(LogQueryParameters)

GetLogMessagesWithRecordCount(LogQueryParameters, out int)

Gets log messages matching a filter and returns a count of the records available

public LogMessageCollection GetLogMessagesWithRecordCount(LogQueryParameters parameters, out int recordCount)

Parameters

Name	Type	Description
parameters	LogQueryParameters	Query parameters specifying the messages to return
recordCount	int	Returns the total number of records that match the query parameters. See Remarks.

Returns

LogMessageCollection

Remarks

The returned collection of messages is filtered to include only messages that the caller has permission to view. In some circumstances (such as when the parameters does not filter by job) the recordCount may indicate the total number of records without security filtering applied. Therefore repeated calls to this method (with a new PageNumber) may return fewer thant recordCount messages before indicating that no more records are available.

See Also

CountLogMessages(LogQueryParameters)

GetLogMessages(LogQueryParameters)

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

GetMessagingServiceProvider(string)

Gets the MessagingServiceProvider with the specified Name

public MessagingServiceProvider GetMessagingServiceProvider(string name)

Parameters

Name	Type	Description
name	string	The name to look for. Matching is case-insensitive. Partial matching is not supported.

Returns

MessagingServiceProvider

The requested provider, or null if the provider does not exist or the caller does not have at least View permission for it.

GetMessagingServiceProviders(params MessagingServiceType[])

Gets MessagingServiceProviders of the specified type(s).

public MessagingServiceProviderCollection GetMessagingServiceProviders(params MessagingServiceType[] providerTypes)

Parameters

Name	Type	Description
providerTypes	MessagingServiceType[]	The types of providers to fetch. If no types are specified, all types are returned.

Returns

MessagingServiceProviderCollection

GetMessagingServiceProviders(MessagingServiceType[], ObjectFetchOptions, int, ref bool)

Gets MessagingServiceProviders of the specified type(s).

public MessagingServiceProviderCollection GetMessagingServiceProviders(MessagingServiceType[] providerTypes, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
providerTypes	MessagingServiceType[]	The types of providers to fetch. If no types are specified, all types are returned.
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

MessagingServiceProviderCollection

GetNotificationGroup(string)

Gets the Notification Group with the specified name.

public NotificationGroup GetNotificationGroup(string groupName)

Parameters

Name	Type	Description
groupName	string	The name of the group to fetch.

Returns

NotificationGroup

The Notification Group, or null if no matching object is found.

GetNotificationIndividual(string)

Gets the Notification Individual with the specified name.

public NotificationIndividual GetNotificationIndividual(string name)

Parameters

Name	Type	Description
name	string	The name of the Individual to fetch.

Returns

NotificationIndividual

The Notification Individual, or null if no matching object is found.

GetNotificationRecipients(params NotificationRecipientType[])

Gets all Notification Recipients of the specified type(s)

public NotificationRecipientCollection GetNotificationRecipients(params NotificationRecipientType[] selectionTypes)

Parameters

Name	Type	Description
selectionTypes	NotificationRecipientType[]	The type(s) of recipients to return, or null to return all recipients

Returns

NotificationRecipientCollection

GetNotificationRecipients(NotificationRecipientType[], ObjectFetchOptions, int, ref bool)

Gets all Notification Recipients of the specified type(s), with paging

public NotificationRecipientCollection GetNotificationRecipients(NotificationRecipientType[] selectionTypes, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
selectionTypes	NotificationRecipientType[]	The type(s) of recipients to return, or null to return all recipients
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

NotificationRecipientCollection

GetNotificationRecipientsForAddress(NotificationAddressType, string)

Gets the NotificationIndividual(s) that have the specified address.

[RequiredVersion(4, 3, 2, 16284)]
public NotificationIndividualCollection GetNotificationRecipientsForAddress(NotificationAddressType addressType, string address)

Parameters

Name	Type	Description
addressType	NotificationAddressType	The type of address to filter on
address	string	The address to find. This method performs an exact (but case-insensitive) match

Returns

NotificationIndividualCollection

The Notification Individuals that have the specified address

GetObject(OID)

Gets the object with the specified OID.

public ADTObject GetObject(OID oid)

Parameters

Name	Type	Description
oid	OID

Returns

ADTObject

The requested object.

Remarks

All fetches of an object through this DataContext (or through objects that belong to it) are guaranteed to return the same copy of the object for as long as the DataContext exists.

This method fetches the requested object and all dependent objects. For example, fetching a Job fetches back to the client all steps, conditions, triggers, etc. In scenarios where the dependent objects are not required (for example, you only are going to be listing the job names), use GetObject(OID, ObjectFetchOptions) to fetch only a "stub" of the object on the initial fetch. This is more efficient as less data needs to be retrieved from the database and returned to the client.

Exceptions

PermissionDeniedException

Thrown if the caller does not have permission for the requested object.

ObjectNotFoundException

Thrown if the object does not exist

GetObject(OID, ObjectFetchOptions)

Gets the object with the specified OID, using options to control the way data is returned.

public ADTObject GetObject(OID oid, ObjectFetchOptions fetchOptions)

Parameters

Name	Type	Description
oid	OID	The OID of the object to fetch
fetchOptions	ObjectFetchOptions	Options that control the fetch operation

Returns

ADTObject

The requested object.

Remarks

This method allows you to select how the requested object is returned. See the remarks for ObjectFetchOptions for more information.

All fetches of an object through this DataContext (or through objects that belong to it) are guaranteed to return the same copy of the object for as long as the DataContext exists.

Exceptions

PermissionDeniedException

Thrown if the caller does not have permission for the requested object.

ObjectNotFoundException

Thrown if the object does not exist

GetObjects(params OID[])

Gets the objects with the specified OIDs.

public ADTObjectCollection GetObjects(params OID[] OIDs)

Parameters

Name	Type	Description
OIDs	OID[]	The OID(s) of the object(s) to fetch

Returns

ADTObjectCollection

The requested objects.

Remarks

Any invalid OIDs or objects for which the caller does not have permission are silently ignored.

GetObjects(OID[], ObjectFetchOptions)

Gets the objects with the specified OIDs.

public ADTObjectCollection GetObjects(OID[] OIDs, ObjectFetchOptions options)

Parameters

Name	Type	Description
OIDs	OID[]	The OID(s) of the object(s) to fetch
options	ObjectFetchOptions	Options controlling the fetch operation

Returns

ADTObjectCollection

The requested object.

Remarks

Any invalid OIDs or objects for which the caller does not have permission are silently ignored.

This method allows you to select how the requested object is returned. See the remarks for ObjectFetchOptions for more information.

GetRemoteAgent(string)

Gets the Remote Agent with the specified name or address.

public RemoteAgent GetRemoteAgent(string agentName)

Parameters

Name	Type	Description
agentName	string	The name or address of the Agent to fetch.

Returns

RemoteAgent

The Remote Agent, or null if no matching object is found.

GetRemoteAgents()

Gets all RemoteAgents that the user has permission for

public RemoteAgentCollection GetRemoteAgents()

Returns

RemoteAgentCollection

All Remote Agents for which the caller has at least List permission.

GetRemoteAgents(ObjectFetchOptions, int, ref bool)

Gets Remote Agents from the server.

public RemoteAgentCollection GetRemoteAgents(ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

RemoteAgentCollection

GetScriptLibraries(params string[])

Gets all script libraries that use the specified language(s)

public ScriptLibraryCollection GetScriptLibraries(params string[] languages)

Parameters

Name	Type	Description
languages	string[]	The language(s) to select for. Set to null to get all Script Libraries or specify any of the ScriptLanguages values.

Returns

ScriptLibraryCollection

GetScriptLibraries(string[], ObjectFetchOptions, int, ref bool)

Gets Script Libraries from the server.

public ScriptLibraryCollection GetScriptLibraries(string[] languages, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
languages	string[]	The language(s) to select for. Set to null to get all Script Libraries or specify any of the ScriptLanguages values.
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

ScriptLibraryCollection

GetScriptLibrary(string)

Gets the Script Library with the specified name.

public ScriptLibrary GetScriptLibrary(string libraryName)

Parameters

Name	Type	Description
libraryName	string	The name of the Script Library to fetch.

Returns

ScriptLibrary

The script library, or null if the script library does not exist.

GetSecurityEntities(ObjectFetchOptions, bool, int, ref bool)

Gets Security Entities from the server, with paging

public SecurityEntityCollection GetSecurityEntities(ObjectFetchOptions fetchOptions, bool includePermissions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
fetchOptions	ObjectFetchOptions
includePermissions	bool
pageSize	int
restartPaging	bool

Returns

SecurityEntityCollection

GetSecurityEntities(bool)

Gets all security entities (logins and roles).

public SecurityEntityCollection GetSecurityEntities(bool includePermissions = false)

Parameters

Name	Type	Description
includePermissions	bool

Returns

SecurityEntityCollection

GetSecurityLogin(string)

Gets the Security Login with the specified name or SID.

public SecurityLogin GetSecurityLogin(string name)

Parameters

Name	Type	Description
name	string	The name or SID of the login to fetch.

Returns

SecurityLogin

The Security Login, or null if no matching object is found.

GetSecurityLogins(LoginType[], ObjectFetchOptions, bool, int, ref bool)

Gets all security logins for the specified type(s), with paging

public SecurityLoginCollection GetSecurityLogins(LoginType[] types, ObjectFetchOptions fetchOptions, bool includePermissions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
types	LoginType[]	The type(s) of logins to return
fetchOptions	ObjectFetchOptions
includePermissions	bool
pageSize	int
restartPaging	bool

Returns

SecurityLoginCollection

All security logins of the specified type(s)

GetSecurityLogins(LoginType[], bool)

Gets all security logins for the specified type(s)

public SecurityLoginCollection GetSecurityLogins(LoginType[] types, bool includePermissions = false)

Parameters

Name	Type	Description
types	LoginType[]	The type(s) of logins to return
includePermissions	bool

Returns

SecurityLoginCollection

All security logins of the specified type(s)

GetSecurityLogins(ObjectFetchOptions, bool, int, ref bool)

Gets all security logins, with paging

public SecurityLoginCollection GetSecurityLogins(ObjectFetchOptions fetchOptions, bool includePermissions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
fetchOptions	ObjectFetchOptions
includePermissions	bool
pageSize	int
restartPaging	bool

Returns

SecurityLoginCollection

All security logins of the specified type(s)

GetSecurityLogins(bool)

Gets all security logins

public SecurityLoginCollection GetSecurityLogins(bool includePermissions = false)

Parameters

Name	Type	Description
includePermissions	bool

Returns

SecurityLoginCollection

All security logins

GetSecurityRole(string)

Gets the Security Role with the specified name.

public SecurityRole GetSecurityRole(string name)

Parameters

Name	Type	Description
name	string	The name of the Role to fetch.

Returns

SecurityRole

The Security Role, or null if no matching object is found.

Remarks

The caller must have permission to administer security on the adTempus server.

GetSecurityRoles(ObjectFetchOptions, bool, int, ref bool)

Gets Security Roles from the server, with paging

public SecurityRoleCollection GetSecurityRoles(ObjectFetchOptions fetchOptions, bool includePermissions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
fetchOptions	ObjectFetchOptions
includePermissions	bool
pageSize	int
restartPaging	bool

Returns

SecurityRoleCollection

GetSecurityRoles(bool)

Gets all security roles

public SecurityRoleCollection GetSecurityRoles(bool includePermissions = false)

Parameters

Name	Type	Description
includePermissions	bool

Returns

SecurityRoleCollection

All security roles

GetServerSettings()

Gets the server settings from the server

public ServerSettings GetServerSettings()

Returns

ServerSettings

GetSharedSchedule(string)

Gets the Shared Schedule with the specified name.

public SharedSchedule GetSharedSchedule(string scheduleName)

Parameters

Name	Type	Description
scheduleName	string	The name of the Shared Schedule to fetch.

Returns

SharedSchedule

The requested schedule, or null if the schedule does not exist.

GetSharedSchedules()

Gets all Shared Schedules the user has permission for.

public SharedScheduleCollection GetSharedSchedules()

Returns

SharedScheduleCollection

All Shared Schedules for which the caller has at least List permission.

GetSharedScript(string)

Gets the Shared Script with the specified name.

public Script GetSharedScript(string scriptName)

Parameters

Name	Type	Description
scriptName	string	The name of the Shared Script to fetch.

Returns

Script

The shared script, or null if the shared script does not exist.

GetSharedScripts(params string[])

Gets Shared Scripts that use the specified language(s)

public ScriptCollection GetSharedScripts(params string[] languages)

Parameters

Name	Type	Description
languages	string[]	The language(s) to select for. Set to null to get all Shared Scripts or specify any of the ScriptLanguages values.

Returns

ScriptCollection

GetSharedScripts(string[], ObjectFetchOptions, int, ref bool)

Gets Shared Scripts from the server.

public ScriptCollection GetSharedScripts(string[] languages, ObjectFetchOptions fetchOptions, int pageSize, ref bool restartPaging)

Parameters

Name	Type	Description
languages	string[]	The language(s) to select for. Set to null to get all Shared Scripts or specify any of the ScriptLanguages values.
fetchOptions	ObjectFetchOptions
pageSize	int
restartPaging	bool

Returns

ScriptCollection

ResyncJobs(OID[], int)

Resynchronizes status data for jobs.

public void ResyncJobs(OID[] jobOIDs, int options)

Parameters

Name	Type	Description
jobOIDs	OID[]	The OIDs of the jobs to resync
options	int	Reserved for future use.

Remarks

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

SearchAndReplace(ObjectSearchOptions, out ReadOnlyCollection<SearchReplaceResult>, out MessageCollection)

Performs a search and optional replace operation

public void SearchAndReplace(ObjectSearchOptions options, out ReadOnlyCollection<SearchReplaceResult> results, out MessageCollection messages)

Parameters

Name	Type	Description
options	ObjectSearchOptions	Options defining the behavior of the search/replace operation
results	ReadOnlyCollection<SearchReplaceResult>	Returns the results of the operation
messages	MessageCollection	Returns any error messages encountered during the operation.

UpdateQueueOrder(IEnumerable<ExecutionHistoryItem>)

Updates the ordering of pending jobs in their queues.

public void UpdateQueueOrder(IEnumerable<ExecutionHistoryItem> instancesToUpdate)

Parameters

Name	Type	Description
instancesToUpdate	IEnumerable<ExecutionHistoryItem>	Collection of ExecutionHistoryItem objects with the PriorityOverride or QueueOrderOverride set.

ViewObjectFromSnapshot(OID, Guid, out MessageCollection)

Retrieves an object from a snapshot.

public ADTObject ViewObjectFromSnapshot(OID objectToView, Guid snapshotID, out MessageCollection messages)

Parameters

Name	Type	Description
objectToView	OID
snapshotID	Guid
messages	MessageCollection

Returns

ADTObject

A copy of the requested object from the snapshot, or null if the snapshot does not contain the object

Remarks

Important: This method can only be called on a new DataContext that has not previously been used to retrieve any objects (use NewDataContext() to create a new DataContext. This is necessary to ensure that the copy of the object that is returned (and all contained and referenced objects) reflect the state they were in at the time of the snapshot. If the DataContext has previously been used, it is possible that the versions of those objects cached on the client might be returned to you instead of the version from the snapshot.

If you call this method on a DataContext that has already been used you will get an InvalidOperationException.

Snapshots are copies of objects created as a backup or to make it possible to revert changes to an object. They can be queried using QueryChangeLog(ChangeLogQueryParameters) to return ObjectChangeLog records.

Once you have an ObjectChangeLog record representing a snapshot, ViewObjectFromSnapshot is used to retrieve an object from that snapshot.

Exceptions

InvalidOperationException

Thrown if the DataContext has previously been used to fetch other objects. See Remarks.