Class ApplicationIntegration
- Namespace
- ArcanaDevelopment.adTempus.Client
- Assembly
- ArcanaDevelopment.adTempus.Client.dll
Allows applications run by adTempus to interact with the adTempus server.
public sealed class ApplicationIntegration : IApplicationIntegration- Inheritance
-
objectApplicationIntegration
- Implements
Remarks
This class can only be used from applications that were started by an adTempus job. Attempting to use it from any other application will produce an error.
To use the class, call Connect to create a connection to the adTempus server.
Properties
Checkpoint
Gets or sets the Checkpoint for the job.
public string Checkpoint { get; set; }Property Value
- string
IsAvailable
Indicates whether the ApplicationIntegration system is available.
public static bool IsAvailable { get; }Property Value
- bool
Remarks
This returns true if the calling application is being run by adTempus, or false otherwise. If IsAvailable is false, calls to Connect will fail.
JobID
Gets the unique ID for the job definition.
public string JobID { get; }Property Value
- string
JobInstanceID
Gets the unique ID for this job instance.
public string JobInstanceID { get; }Property Value
- string
Remarks
This a GUID for the instance. For the instance number, use JobInstanceNumber.
JobInstanceNumber
Gets the instance number for this job instance.
public int? JobInstanceNumber { get; }Property Value
- int?
JobInstanceOID
The OID of the ExecutionHistoryItem representing this job instance.
public OID JobInstanceOID { get; }Property Value
JobOID
The OID of the Job being executed.
public OID JobOID { get; }Property Value
JobVariables
Gets the Job Variables for the job.
public IJobVariableDictionary JobVariables { get; }Property Value
Remarks
This collection contains all Job Variables currently defined for this job instance. You can add or modify variables, but those changes only affect this job instance--they are not permanent changes.
To quickly set or create a variable, use SetJobVariable.
- See Also
Result
The result of the script execution
public object Result { get; set; }Property Value
- object
ShouldTerminate
Indicates whether the operation has been terminated.
public bool ShouldTerminate { get; }Property Value
- bool
Remarks
ShouldTerminate returns True if a termination request has been received for the operation. Consumers of this interface can poll ShouldTerminate during lengthy operations to detect termination. When termination has been requested, the operation should terminate as soon as possible.
StepID
Gets the unique ID for the job step definition.
public string StepID { get; }Property Value
- string
StepInstanceOID
The OID of the ExecutionHistoryStep representing the step being executed.
public OID StepInstanceOID { get; }Property Value
StepNumber
Gets the step number
public int StepNumber { get; }Property Value
- int
StepOID
The OID of the JobStep being executed.
public OID StepOID { get; }Property Value
TerminationEvent
Event that is signalled when the script is being terminated.
public EventWaitHandle TerminationEvent { get; }Property Value
- EventWaitHandle
Methods
CaptureFile(string, string)
Captures a file on disk and stores it in the job history.
public void CaptureFile(string fileName, string displayName)Parameters
| Name | Type | Description |
|---|---|---|
fileName |
string | The path/name of an existing file. |
displayName |
string | The name that the file should use after it is captured. Specify null or empty string to use the original name. |
Remarks
The file is copied to the adTempus CapturedFiles directory when you call CaptureFile.
CaptureFile(string, string, string)
Captures a file on disk and stores it in the job history.
public void CaptureFile(string fileName, string originalPath, string displayName)Parameters
| Name | Type | Description |
|---|---|---|
fileName |
string | The path/name of an existing file. |
originalPath |
string | The original path of the file. Specify null or empty string to use the fileName. |
displayName |
string | The name that the file should use after it is captured. Specify null or empty string to use the original name. |
Remarks
The file is copied to the adTempus CapturedFiles directory when you call CaptureFile.
CaptureFileData(byte[], string, string, DateTime, bool)
Stores data as a Captured File in the job history.
public void CaptureFileData(byte[] fileContents, string displayName, string originalPath, DateTime fileDate, bool treatAsCapturedConsole = false)Parameters
| Name | Type | Description |
|---|---|---|
fileContents |
byte[] | The contents to write to the file |
displayName |
string | The file name to display for the data. |
originalPath |
string | The path to display for the file. Can be null or empty. |
fileDate |
DateTime | The timestamp to display for the file. |
treatAsCapturedConsole |
bool | If true, this file is treated as captured console output for various purposes |
Connect()
Establishes a connection to the adTempus server.
public static IApplicationIntegration Connect()Returns
Remarks
Connects to the server and returns a new ApplicationIntegration object representing the connection. If the connection fails, throws an exception.
Connect(out Message)
Establishes a connection to the adTempus server.
public static IApplicationIntegration Connect(out Message failureMessage)Parameters
| Name | Type | Description |
|---|---|---|
failureMessage |
Message |
Returns
Remarks
Connects to the server and returns a new ApplicationIntegration object representing the connection. If the
connection fails, returns null and the failureMessage contains an error message.
ExecuteOnDemandResponses(string)
Executes on-demand Responses defined for the job or step.
public void ExecuteOnDemandResponses(string eventTag)Parameters
| Name | Type | Description |
|---|---|---|
eventTag |
string | The tag used to match Response Events. |
Remarks
This method will invoke any Responses that have a ResponseEvent with type
OnDemand
and a CustomEventID that matches the eventTag.
Responses are invoked asynchronously (the script does not wait for completion of Response evaluation).
ExecuteOnDemandResponses(string, ResponseParameters)
Executes on-demand Responses defined for the job or step.
public void ExecuteOnDemandResponses(string eventTag, ResponseParameters parms)Parameters
| Name | Type | Description |
|---|---|---|
eventTag |
string | The tag used to match Response Events. |
parms |
ResponseParameters | Additional parameters for Response evaluation. Can be null. |
Remarks
This method will invoke any Responses that have a ResponseEvent with type
OnDemand
and a CustomEventID that matches the eventTag.
Responses are invoked asynchronously (the script does not wait for completion of Response evaluation).
IsRunning()
Indicates whether the job step is still active.
public bool IsRunning()Returns
- bool
Remarks
The ApplicationIntegration connection is only valid while the job step it is running under is active. If you attempt to perform any operations after the step ends, they will throw an InvalidOperationContextException exception. Use IsRunning to see if the context is still valid.
LogDebug(string)
Logs a message to the Script Debug Log for the job.
public void LogDebug(string message)Parameters
| Name | Type | Description |
|---|---|---|
message |
string | The message text. |
Remarks
Equivalent to calling LogMessage with Debug.
- See Also
-
LogInfo(string)LogWarning(string)LogError(string)
LogError(string)
Logs an Error message to the Job Log for the job.
public void LogError(string message)Parameters
| Name | Type | Description |
|---|---|---|
message |
string | The message text. |
Remarks
Equivalent to calling LogMessage with Error.
- See Also
-
LogDebug(string)LogInfo(string)LogWarning(string)
LogInfo(string)
Logs an Informational message to the Job Log for the job.
public void LogInfo(string message)Parameters
| Name | Type | Description |
|---|---|---|
message |
string | The message text. |
Remarks
Equivalent to calling LogMessage with Informational.
- See Also
-
LogDebug(string)LogWarning(string)LogError(string)
LogMessage(MessageType, int, string)
Logs a message to the Job Log for the job.
public void LogMessage(MessageType messageType, int messageCode, string message)Parameters
| Name | Type | Description |
|---|---|---|
messageType |
MessageType | The message type (severity) |
messageCode |
int | The message code. Can be used to filter messages. Note: The value 100000 will be added to the messageCode when the message is recorded in adTempus. |
message |
string | The message text. |
Remarks
Each message logged with LogMessage creates a log message in the Job Log for the job and a record in the adTempus database. To avoid cluttering the job log and using large amounts of database space, use MessageType.Debug for debug-level messages. These messages will be written to the Job Detail Log instead of the main Job Log. The detail log is a single log file with detailed/diagnostic information for the job, available from the Captured Files list for the job.
- See Also
-
LogDebug(string)LogInfo(string)LogWarning(string)LogError(string)
LogMessage(MessageType, string)
Logs a message to the Job Log for the job.
public void LogMessage(MessageType messageType, string message)Parameters
| Name | Type | Description |
|---|---|---|
messageType |
MessageType | The message type (severity) |
message |
string | The message text. |
Remarks
This method is equivalent to calling LogMessage(messageType, 0, message)
Each message logged with LogMessage creates a log message in the Job Log for the job and a record in the adTempus database. To avoid cluttering the job log and using large amounts of database space, use MessageType.Debug for debug-level messages. These messages will be written to the Job Detail Log instead of the main Job Log. The detail log is a single log file with detailed/diagnostic information for the job, available from the Captured Files list for the job.
- See Also
LogWarning(string)
Logs a Warning message to the Job Log for the job.
public void LogWarning(string message)Parameters
| Name | Type | Description |
|---|---|---|
message |
string | The message text. |
Remarks
Equivalent to calling LogMessage with Warning.
ReplaceVariableTokens(string)
Expands variable tokens in a string
public string ReplaceVariableTokens(string sourceString)Parameters
| Name | Type | Description |
|---|---|---|
sourceString |
string | The string to expand tokens in. |
Returns
- string
Remarks
This method replaces any valid variable tokens it finds with the corresponding values.
For example, if Job Variable "SomeVariable" has the value of "423", calling ReplaceVariableTokens("Current value: %SomeVariable%") returns the result "Current value: 423".
This method does not support the expansion of inline functions.
SendNotificationMessage(NotificationMessage)
Sends a notification message through the adTempus notification system.
public void SendNotificationMessage(NotificationMessage message)Parameters
| Name | Type | Description |
|---|---|---|
message |
NotificationMessage | The message to send. |
SetAdditionalResult(string, string)
Communicates additional result information to the host.
public void SetAdditionalResult(string key, string value)Parameters
| Name | Type | Description |
|---|---|---|
key |
string | |
value |
string |
SetCheckpoint(string)
Sets the current checkpoint for the job.
public void SetCheckpoint(string value)Parameters
| Name | Type | Description |
|---|---|---|
value |
string | The new value for the checkpoint |
SetJobOutcome(ExecutionOutcome, string)
Sets the success or failure state of the job in which the script is executing
public void SetJobOutcome(ExecutionOutcome outcome, string message = null)Parameters
| Name | Type | Description |
|---|---|---|
outcome |
ExecutionOutcome | Indicates whether the job should be reported as Succeeded or Failed. |
message |
string | Optional message to log to the Job Log |
Remarks
When the outcome is set using SetStepOutcome, this overrides the normal success/failure determination rules for the step. This is equivalent to using a JobControlAction with a ControlType of SucceedJob or FailJob
SetJobVariable(string, string)
Sets a value for an existing or new Job Variable.
public void SetJobVariable(string name, string value)Parameters
| Name | Type | Description |
|---|---|---|
name |
string | The name of the variable to add or update. |
value |
string | The value for the variable. |
Remarks
This method updates the existing variable with Name name, or creates a new variable if none exists with that name.
The variable is only defined for the current execution of the job.
- See Also
SetStepOutcome(ExecutionOutcome, string)
Sets the success or failure state of the step in which the script is executing
public void SetStepOutcome(ExecutionOutcome outcome, string message = null)Parameters
| Name | Type | Description |
|---|---|---|
outcome |
ExecutionOutcome | Indicates whether the step should be reported as Succeeded or Failed. |
message |
string | Optional message to log to the Job Log |
Remarks
When the outcome is set using SetStepOutcome, this overrides the normal success/failure determination rules for the step. This is equivalent to using a JobControlAction with a ControlType of SucceedJob or FailJob
Sleep(int)
Delays execution for the specified number of milliseconds.
public bool Sleep(int timeoutMS)Parameters
| Name | Type | Description |
|---|---|---|
timeoutMS |
int | The number of milliseconds to sleep. |
Returns
- bool
true if the wait period elapsed, or false if the script/step/job was aborted before the wait elapsed.
Remarks
Use this method to sleep safely inside a script and abort processing if the script is terminated.
Sleep(TimeSpan)
Delays execution for the specified time
public bool Sleep(TimeSpan timeout)Parameters
| Name | Type | Description |
|---|---|---|
timeout |
TimeSpan | The time to sleep. |
Returns
- bool
true if the wait period elapsed, or false if the script/step/job was aborted before the wait elapsed.
Remarks
Use this method to sleep safely inside a script and abort processing if the script is terminated.