Class Run
The Run class provides a representation of a routine run with the Routine system. This allows for programmatic execution control and monitoring of runs, including starting, cancelling, and retrieving artifacts.
Namespace: Workspace.XBR.Xperiflow.Routines.Runs
Assembly: Xperiflow.dll
public class Run
Remarks
Many of the methods of this object accept an 'executionType' which denotes the way in which to execution the Routine Method Run. The supported options are: "background" and "in-memory".
"background" will execute the Run as a background job which means the Run will execute in a separate python process. This method should be used in the case where it is expected that the Run will take more than 5 seconds to run or consumes a lot of compute and memory.
"in-memory" will execute the Run at the web service tier of the xperiflow engine. This can be used to provide fast response to the user. This method should be used in the case where the Run is expected to run in under 60 seconds and does not consume significant compute and memory resources. Note that there are protection mechanisms at the web service tier that will immediately kill the Run if it takes more than a certain amount of time or memory to run. Additionally, it can run as "in-memory" if it is that particular Routine Method is enabled to do so. Lastly, the "in-memory" method won't leave this StartAsync until it finishes running.
Properties
InstanceIdentifier
The Routine Instance Identifier that this run belongs to. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.InstanceIdentifier for more information.
public string InstanceIdentifier { get; }
RunIdentifier
The unique identifier for the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.RunIdentifier for more information.
public string RunIdentifier { get; }
ExecutionIdentifier
The unique identifier for the execution. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.ExecutionIdentifier for more information.
public string ExecutionIdentifier { get; }
ExecutionType
The type of execution. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.ExecutionType for more information.
public string ExecutionType { get; }
MethodName
The method name that was invoked for this run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.MethodName for more information.
public string MethodName { get; }
CallableType
The callable type. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.RoutineCallableType for more information.
public RoutineCallableType CallableType { get; }
RunName
The user-defined name of the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.RunName for more information.
public string RunName { get; }
RunDescription
The user-defined description of the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.RunDescription for more information.
public string RunDescription { get; }
CreationTime
The UTC time the run was created. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.CreationTime for more information.
public DateTime CreationTime { get; }
ModifiedTime
The UTC time the run was last modified. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.ModifiedTime for more information.
public DateTime ModifiedTime { get; }
CreatedByUserId
The unique identifier of the user that created the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.CreatedByUserId for more information.
public string CreatedByUserId { get; }
CreatedByUserName
The name of the user that created the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.CreatedByUserName for more information.
public string CreatedByUserName { get; }
ModifiedByUserId
The unique identifier of the user that last modified the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.ModifiedByUserId for more information.
public string ModifiedByUserId { get; }
ModifiedByUserName
The name of the user that last modified the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.ModifiedByUserName for more information.
public string ModifiedByUserName { get; }
ArtifactPath
The file path to the artifacts for this run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.ArtifactPath for more information.
public string ArtifactPath { get; }
InputParams
The input parameters for the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.InputParams for more information.
public JObject InputParams { get; }
InvocationMethod
The invocation method of this run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.InvocationMethod for more information.
public InvocationMethod InvocationMethod { get; }
MemoryCapacity
The memory capacity of the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.MemoryCapacity for more information.
public double MemoryCapacity { get; }
Labels
Arbitrary user defined labels that were defined at the creation of the Routine Run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.Labels for more information.
public IEnumerable<string> Labels { get; }
Attributes
Arbitrary attributes that are associated with the runs. This is a JSON object that contains additional metadata that that was put here during the instantiation of the run. See Workspace.XBR.Xperiflow.Routines.Runs.RunMetadata.Attributes for more information.
public JObject? Attributes { get; }
RootDirPath
The root directory path for the run.
ex: /instances/{instanceIdentifier}/runs/{runIdentifier}
public string RootDirPath { get; }
SharedDirPath
The shared directory path for the run. This is where arbitrary run-level files can be written, read, and stored from both the OneStream and Xperiflow systems.
public string SharedDirPath { get; }
SharedStoreDirPath
The shared store directory path. This is a special directory within the Run shared directory that is used to store shared data for the SharedDataStore.
public string SharedStoreDirPath { get; }
ArtifactDirPath
The artifact directory path for the run. This is where the artifacts for the run are stored.
public string ArtifactDirPath { get; }
SharedFileSystem
The shared MetaFileSystem. This is a MetaFileSystemClient instance that is relative to the Routine Instances shared directory. This can be used to store and retrieve shared data using the standard MetaFileSystemClient methods. This is useful over the Workspace.XBR.Xperiflow.Routines.Runs.Run.SharedDataStore property when more control is needed over type of data that is to be stored and retrieved.
public IMetaFileSystemClient SharedFileSystem { get; }
SharedDataStore
The shared data cache. This is an IFileTypeAccessor instance that is relative to a special directory within the Run shared directory. Use this to store and retrieve shared data without needing to bother with the actual file paths and file types by using key based access.
public IDataStoreAccessor SharedDataStore { get; }
Methods
RenameAsync(string?, string?, CancellationToken)
Rename the run's name and/or description.
public Task RenameAsync(string? name = null, string? description = "", CancellationToken cancellationToken = default)
Returns
System.Threading.Tasks.Task
Parameters
| Type | Name | Description |
|---|---|---|
System.String | name | The new name for the run. If not provided, the name will not be changed. |
System.String | description | The new description for the run. If not provided, the description will not be changed. |
System.Threading.CancellationToken | cancellationToken |
GetExecutionStatusAsync(CancellationToken)
The current execution status of the run. The refresh is rate limited to only allow a refresh every statusCheckInterval seconds.
public Task<ExecutionStatus> GetExecutionStatusAsync(CancellationToken cancellationToken = default)
Returns
Task< Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus >
Parameters
| Type | Name | Description |
|---|---|---|
System.Threading.CancellationToken | cancellationToken | The cancellation token to cancel the operation. |
WaitForCompletionAsync(CancellationToken)
Waits for a run process to reach a completion state before proceeding. This method is essential for ensuring that a dependent task does not start until the current run has either successfully completed, been manually cancelled, or failed. It actively monitors the execution status by periodically refreshing it at predefined intervals, thereby facilitating timely and efficient execution flow control.
public Task<ExecutionStatus> WaitForCompletionAsync(CancellationToken cancellationToken = default)
Remarks
This method utilizes a polling mechanism to query the execution status at regular intervals specified by the statusCheckInterval. It is designed to minimize resource consumption while keeping the application responsive to state changes in the execution process.
Returns
Task< Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus >
The Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus at the point of completion, which can be used to determine the outcome of the run and make decisions in subsequent operations or error handling routines.
Parameters
| Type | Name |
|---|---|
System.Threading.CancellationToken | cancellationToken |
Exceptions
OneStream.Shared.Common.XFException
Throws an OneStream.Shared.Common.XFException encapsulating any underlying exceptions that occur during the
execution status refresh process. This custom exception provides additional context and details for
troubleshooting and is logged for audit purposes.
WaitForSuccessfulCompletionAsync(CancellationToken)
Waits for a run process to not only reach a completion state but also to ensure that completion is successful. This method is vital for scenarios where subsequent operations depend on the successful completion of the current run, distinguishing between simply completed runs and those that have completed successfully without being cancelled or failing.
public Task<ExecutionStatus> WaitForSuccessfulCompletionAsync(CancellationToken cancellationToken = default)
Remarks
Similar to Workspace.XBR.Xperiflow.Routines.Runs.Run.WaitForCompletionAsync(System.Threading.CancellationToken), this method employs a polling mechanism to monitor the run's execution status at intervals specified by statusCheckInterval. However, it adds a layer of validation to confirm that the run has neither been cancelled nor failed, ensuring that only successful completions allow the workflow to progress. This rigorous check is particularly useful in workflows where the integrity of subsequent operations is contingent upon the successful execution of preceding tasks.
Returns
Task< Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus >
The Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus at the point of successful completion, signaling that the run has concluded without errors or cancellations, ready for subsequent tasks to be initiated.
Parameters
| Type | Name |
|---|---|
System.Threading.CancellationToken | cancellationToken |
Exceptions
System.InvalidOperationException
Thrown if the run concludes in a state other than success, specifically if it has been cancelled or
has failed. The exception message includes the final execution state, providing immediate feedback
for error handling or debugging purposes.
OneStream.Shared.Common.XFException
Throws an OneStream.Shared.Common.XFException encapsulating any underlying exceptions that occur during the
execution status refresh process. This ensures that all exceptions are logged and detailed for
analysis and resolution.
StartAsync(CancellationToken)
Initiates the execution of a run process by sending a start request to the underlying execution system. This method is the first step in the lifecycle of a run, transitioning its state from idle or prepared to actively executing. This operation can be thought of as an asynchronous trigger that sets the run in motion, allowing it to progress through its defined sequence of activities while returning control to the caller for subsequent operations.
Note that if the underlying Run has an ExecutionType of "in-memory", then this will be a blocking execution, this method will run synchronously.
public Task StartAsync(CancellationToken cancellationToken = default)
Remarks
Upon successfully starting the run, this method also refreshes both the run and execution metadata to reflect the latest state post-initiation. This dual-refresh approach ensures that subsequent operations have access to the most current data, facilitating accurate monitoring and management of the run's execution.
Should the start request fail, either due to system errors or validation issues, this method throws an exception with a detailed message derived from the response, enabling immediate troubleshooting and corrective actions.
Returns
System.Threading.Tasks.Task
Parameters
| Type | Name |
|---|---|
System.Threading.CancellationToken | cancellationToken |
Exceptions
System.InvalidOperationException
Thrown if the start request fails, indicating that the run could not be initiated. The exception
includes a detailed error message based on the response from the execution system, providing
clarity on the nature of the failure.
OneStream.Shared.Common.XFException
Throws an OneStream.Shared.Common.XFException encapsulating any underlying exceptions that occur during the
start request or the metadata refresh process. This custom exception is logged for audit purposes
and provides a structured approach to error handling and resolution.
StartAndWaitForCompletionAsync(CancellationToken)
Initiates the execution of a run process and waits for it to reach a conclusive state. This combined operation streamlines the workflow by ensuring that the run is both started and seen through to completion, facilitating a seamless transition to subsequent tasks based on the outcome of the run. This can be thought of as a synchronous operation that encapsulates the asynchronous start and wait for completion steps, providing a convenient way to lock the execution flow until the run concludes.
public Task<ExecutionStatus> StartAndWaitForCompletionAsync(CancellationToken cancellationToken = default)
Remarks
This method encapsulates the operations of starting the run and monitoring its progress until it concludes, either successfully or due to failure or cancellation. It's an essential utility for workflows that require runs to be executed in a controlled, sequential manner. In the event that starting the run or waiting for its completion encounters any issues, exceptions are systematically logged to provide a detailed error context, enhancing the robustness of error handling and facilitating troubleshooting efforts.
Returns
Task< Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus >
A Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus reflecting the final state of the run upon completion. This status can be used to make informed decisions about subsequent operations, based on whether the run concluded successfully, was cancelled, or failed.
Parameters
| Type | Name |
|---|---|
System.Threading.CancellationToken | cancellationToken |
Exceptions
OneStream.Shared.Common.XFException
An OneStream.Shared.Common.XFException is thrown if any errors occur during the start or wait operations. This
custom exception type encapsulates underlying exceptions, ensuring that error details are not lost and
that they can be properly logged and addressed. The logging mechanism provides vital insights into the
error conditions, facilitating swift and effective resolution.
StartAndWaitForSuccessfulCompletionAsync(CancellationToken)
Initiates the execution of a run process and waits for it to successfully complete. This method enhances the workflow by ensuring not only the initiation and completion of the run but also verifying its successful conclusion before moving forward. It represents a synchronous operation that combines the asynchronous start of a run with the critical requirement of its successful completion, thereby providing a robust solution for workflows that cannot proceed with subsequent tasks until the run has successfully ended.
public Task<ExecutionStatus> StartAndWaitForSuccessfulCompletionAsync(CancellationToken cancellationToken = default)
Remarks
By ensuring the successful completion of the run, this method adds a level of reliability to the execution flow, ideal for critical operations where the success of subsequent tasks is contingent upon the run's outcome. It encapsulates starting the run, monitoring its execution, and verifying its successful completion, making it a key component in controlled, sequential execution patterns. Any encountered exceptions, either during the start or the wait for successful completion, are meticulously logged, offering detailed insights for troubleshooting and reinforcing the error handling process.
Returns
Task< Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus >
The Workspace.XBR.Xperiflow.Routines.Runs.ExecutionStatus indicating the run's successful completion, which is pivotal for determining the feasibility of subsequent operations. It ensures that only runs that have ended successfully influence the next steps of the execution flow.
Parameters
| Type | Name |
|---|---|
System.Threading.CancellationToken | cancellationToken |
Exceptions
OneStream.Shared.Common.XFException
Throws an OneStream.Shared.Common.XFException when any error arises during the start process or while waiting for the
run's successful completion. This exception encapsulates the underlying issue, providing a clear context for
logging and resolution, thus facilitating an efficient troubleshooting process.
StartAndWaitForSuccessfulCompletionResultAsync(CancellationToken)
Initiates the execution of a run process and waits for it to successfully complete. Upon succesful completion, it will return a RunResult which contains the run metadata, execution metadata, and the artifacts (in-memory and background) generated by the run.
public Task<RunResult> StartAndWaitForSuccessfulCompletionResultAsync(CancellationToken cancellationToken = default)
Returns
Task< Workspace.XBR.Xperiflow.Routines.Runs.RunResult >
Parameters
| Type | Name |
|---|---|
System.Threading.CancellationToken | cancellationToken |
CancelAsync(CancellationToken)
Attempts to cancel an ongoing run. This method sends a cancellation request for a specified run, identified by its unique run identifier. It is designed to allow for graceful termination of runs that are no longer needed or where continuing execution is deemed unnecessary.
public Task CancelAsync(CancellationToken cancellationToken = default)
Remarks
Upon issuing a cancellation request, this method immediately attempts to refresh the run metadata to reflect the updated status. It is important to handle potential failures in cancellation as the operation's success is contingent on the current state and responsiveness of the underlying execution system. Failures to cancel a run are communicated through exceptions, providing detailed error messages for troubleshooting.
Returns
System.Threading.Tasks.Task
Parameters
| Type | Name |
|---|---|
System.Threading.CancellationToken | cancellationToken |
Exceptions
System.InvalidOperationException
Thrown if the cancellation request fails. This exception contains detailed information regarding the
failure reason, aiding in understanding why the cancellation could not be processed.
OneStream.Shared.Common.XFException
Throws an OneStream.Shared.Common.XFException encapsulating any underlying exceptions encountered during the
operation. This includes errors in sending the cancellation request or refreshing the run metadata.
Such exceptions are logged for audit and debugging purposes.
GetArtifactsAsync(bool, CancellationToken)
Retrieves all the artifacts generated by the run. This method can only be called after the run has completed successfully.
public Task<List<Artifact>> GetArtifactsAsync(bool includeAggregates = true, CancellationToken cancellationToken = default)
Returns
Task<System.Collections.Generic.List{Workspace.XBR.Xperiflow.Routines.Artifacts.Artifact}>
A list of artifact objects.
Parameters
| Type | Name | Description |
|---|---|---|
System.Boolean | includeAggregates | Whether or not to include aggregate artifacts. Note that aggregate artifacts do not have their own data (only have statistics, previews, metadata). |
System.Threading.CancellationToken | cancellationToken |
Exceptions
Workspace.XBR.Xperiflow.Routines.Runs.RunException Thrown if the run has not completed successfully.
GetArtifactAsync(string, CancellationToken)
Get an artifact by its qualified key. If the artifact does not exist, null is returned. This method can only be called after the run has completed successfully.
public Task<Artifact?> GetArtifactAsync(string qualifiedKey, CancellationToken cancellationToken = default)
Returns
Task< Workspace.XBR.Xperiflow.Routines.Artifacts.Artifact >
An artifact object or null.
Parameters
| Type | Name | Description |
|---|---|---|
System.String | qualifiedKey | The qualified artifact key (ex: dataframes.0.dataframe). |
System.Threading.CancellationToken | cancellationToken |
Exceptions
Workspace.XBR.Xperiflow.Routines.Runs.RunException Thrown if the run has not completed successfully.
Inherited Members
System.Object.Equals(System.Object)System.Object.Equals(System.Object,System.Object)System.Object.GetHashCodeSystem.Object.GetTypeSystem.Object.MemberwiseCloneSystem.Object.ReferenceEquals(System.Object,System.Object)System.Object.ToString