Skip to main content

Class RoutineInstance

Represents a configured instance of a routine type that can execute methods and manage runs.

Namespace: Workspace.XBR.Xperiflow.Routines.Instances

Assembly: Xperiflow.dll

Declaration
public class RoutineInstance

Examples​

Working with a routine instance:

// Create a new routine instance
var instance = routineClient.CreateRoutineInstanceAsync(
    "data-processor",
    "1.2.0",
    "Daily Processing Instance"
).Result;

// Execute a constructor run for initialization
var constructorRun = instance.CreateConstructorRunAsync(
    inputParams: new JObject { ["config"] = "production" }
).Result;
constructorRun.WaitForCompletionAsync().Wait();

// Execute a method run for processing
var methodRun = instance.CreateMethodRunAsync(
    "process_data",
    inputParams: new JObject { ["date"] = "2023-12-01" },
    storeArtifacts: true,
    includeStatistics: true
).Result;

// Monitor run progress
methodRun.WaitForCompletionAsync().Wait();
var artifacts = methodRun.GetArtifactsAsync().Result;

Remarks​

A Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance is a specific, configured instance of a routine type within the Xperiflow system. It acts conceptually like a class instance in object-oriented programming, maintaining its own state, configuration, and execution context. Routine instances serve as the primary interface for executing routine methods and managing their associated runs.

Key Concepts:

  • Instance Configuration Each instance has specific configuration including memory limits, labels, and custom attributes

  • Run Management Instances create and manage runs, which represent individual executions of routine methods

  • Shared Resources Provides access to shared file systems and data stores for persistent state across runs

  • Constructor vs Method Runs Supports both constructor runs (for initialization) and method runs (for specific operations)

Lifecycle Management:

Routine instances are typically created through Workspace.XBR.Xperiflow.Routines.IRoutineClient.CreateRoutineInstanceAsync(System.String%2cSystem.String%2cSystem.String%2cSystem.String%2cSystem.Nullable%7bSystem.Double%7d%2cSystem.Collections.Generic.IEnumerable%7bSystem.String%7d%2cNewtonsoft.Json.Linq.JObject%2cWorkspace.XBR.Xperiflow.Utilities.Http.MemoizedCacheInfo%2cSystem.Threading.CancellationToken) methods and can be retrieved, updated, and deleted through the same interface. Each instance maintains metadata about its creation, modification history, and current configuration.

Run Execution Patterns:

Use Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance.CreateConstructorRunAsync(Newtonsoft.Json.Linq.JObject%2cSystem.String%2cSystem.Nullable%7bSystem.Double%7d%2cWorkspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType%2cSystem.String%2cSystem.String%2cSystem.Collections.Generic.IEnumerable%7bSystem.String%7d%2cNewtonsoft.Json.Linq.JObject%2cSystem.Collections.Generic.Dictionary%7bSystem.String%2cSystem.Object%7d%2cSystem.Threading.CancellationToken) for initialization operations and Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstance.CreateMethodRunAsync(System.String%2cNewtonsoft.Json.Linq.JObject%2cSystem.String%2cSystem.Boolean%2cSystem.Boolean%2cSystem.Boolean%2cSystem.Nullable%7bSystem.Double%7d%2cWorkspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType%2cSystem.String%2cSystem.String%2cSystem.Collections.Generic.IEnumerable%7bSystem.String%7d%2cNewtonsoft.Json.Linq.JObject%2cSystem.Collections.Generic.Dictionary%7bSystem.String%2cSystem.Object%7d%2cSystem.Threading.CancellationToken) for specific business logic execution. The instance provides methods to monitor, retrieve, and manage all runs associated with it.

Properties​

InstanceIdentifier​

Gets the instance identifier. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.InstanceIdentifier for more information.

Declaration
public string InstanceIdentifier { get; }

RoutineTypename​

Gets the routine type name. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.RoutineTypename for more information.

Declaration
public string RoutineTypename { get; }

RoutineVersion​

Gets the version of the routine type. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.RoutineVersion for more information.

Declaration
public Version RoutineVersion { get; }

Name​

Gets the name of the routine instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.Name for more information.

Declaration
public string Name { get; }

Description​

Gets the description of the routine instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.Description for more information.

Declaration
public string Description { get; }

CreatedBy​

Gets the identifier of the user who created the routine instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.CreatedBy for more information.

Declaration
public string CreatedBy { get; }

ModifiedBy​

Gets the identifier of the user who last modified the routine instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.ModifiedBy for more information.

Declaration
public string ModifiedBy { get; }

CreatedByUserName​

Gets the name of the user who created the routine instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.CreatedByUserName for more information.

Declaration
public string CreatedByUserName { get; }

ModifiedByUserName​

Gets the name of the user who last modified the routine instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.ModifiedByUserName for more information.

Declaration
public string ModifiedByUserName { get; }

CreationTime​

Gets the UTC date and time the routine instance was created. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.CreationTime for more information.

Declaration
public DateTime CreationTime { get; }

ModifiedTime​

Gets the UTC date and time the routine instance was last modified. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.ModifiedTime for more information.

Declaration
public DateTime ModifiedTime { get; }

MemoryOverride​

Gets the overidden memory capacity for the routine instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.MemoryOverride for more information.

Declaration
public double? MemoryOverride { get; }

SolutionName​

The name of the solution that this routine instance is associated with. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.SolutionName for more information.

Declaration
public string SolutionName { get; }

Labels​

Arbitrary user defined labels that were defined at the creation of the Routine Instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.Labels for more information.

Declaration
public IEnumerable<string> Labels { get; }

Attributes​

Arbitrary attributes that are associated with the routine instance. This is a JSON object that contains additional metadata that that was put here during the instantiation of the instance. See Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceMetadata.Attributes for more information.

Declaration
public JObject? Attributes { get; }

RootDirPath​

The root directory path to where all the routine instance data is stored.

Declaration
public string RootDirPath { get; }

SharedDirPath​

The directory path to where shared data can be stored for the routine instance.

Declaration
public string SharedDirPath { get; }

SharedStoreDirPath​

The shared store directory path. This is a special directory within the Routine Instances shared directory that is used to store shared data for the SharedDataStore.

Declaration
public string SharedStoreDirPath { 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.Instances.RoutineInstance.SharedDataStore property when more control is needed over type of data that is to be stored and retrieved.

Declaration
public IMetaFileSystemClient SharedFileSystem { get; }

SharedDataStore​

The shared data cache. This is an IFileTypeAccessor instance that is relative to a special directory within the Routine Instance 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.

Declaration
public IDataStoreAccessor SharedDataStore { get; }

Methods​

RenameAsync(string?, string?, CancellationToken)​

Renames the routine instance.

Declaration
public Task RenameAsync(string? name = null, string? description = "", CancellationToken cancellationToken = default)
Returns​

System.Threading.Tasks.Task

Parameters​
TypeNameDescription
System.StringnameThe new name for the routine instance. If not provided, the name will not be changed. This value is subject to additional runtime constraints.
System.StringdescriptionThe new description for the routine instance. If not provided, the description will not be changed.
System.Threading.CancellationTokencancellationToken
Exceptions​

System.ArgumentException Thrown when the name is an empty string. Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceException Thrown when the API call fails or the response is invalid. OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

UpdateMemoryOverrideAsync(double, CancellationToken)​

Updates the memory override for the routine instance.

Declaration
public Task UpdateMemoryOverrideAsync(double gigabytes, CancellationToken cancellationToken = default)
Returns​

System.Threading.Tasks.Task

Parameters​
TypeNameDescription
System.DoublegigabytesThe new memory override value in gigabytes. Must be greater than 0. This setting is subject to additional runtime constraints.
System.Threading.CancellationTokencancellationToken
Exceptions​

System.ArgumentException Thrown when the gigabytes is less than or equal to 0. Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceException Thrown when the API call fails or the response is invalid. OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

CreateConstructorRunAsync(JObject?, string, double?, InvocationMethodType?, string?, string?, IEnumerable<string>?, JObject?, Dictionary<string, object>?, CancellationToken)​

Create a constructor run for the routine instance. This method is specifically for creating a constructor run by providing the method name "init". This method can only be run once per routine instance and is used to initialize the routine instance. If a constructor run already exists, this method will throw an exception.

Note: This method does not start the run. To start the run, call the Workspace.XBR.Xperiflow.Routines.Runs.Run.StartAsync(System.Threading.CancellationToken) method on the returned Run object.

Declaration
public Task<Run> CreateConstructorRunAsync(JObject? inputParams = null, string executionType = "background", double? memoryOverride = null, InvocationMethodType? invocationMethodType = null, string? runName = null, string? description = "", IEnumerable<string>? labels = null, JObject? attributes = null, Dictionary<string, object>? extra = null, CancellationToken cancellationToken = default)
Returns​

Task< Workspace.XBR.Xperiflow.Routines.Runs.Run >

Parameters​
TypeNameDescription
Newtonsoft.Json.Linq.JObjectinputParamsThe input parameters for the method. This is a JSON object that contains the input parameters for the method.
System.StringexecutionTypeThe way in which to execution the Routine Method Run. The supported options are: "background" and "in-memory".
Please see Workspace.XBR.Xperiflow.Routines.Runs.Run class definition for more information.
System.Nullable<System.Double>memoryOverrideThe memory override for the run. If not provided, the memory capacity defined at the routine method level will be used.
Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodTypeinvocationMethodTypeThe type of invocation method to use for the run. Defaults to Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Direct invocation. If you are programmatically creating a run,
it is recommended to use the Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Direct invocation type. If you are looking to have the user provide input parameters later
via component workflow, use the Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Workflow invocation type
System.StringrunNameA user-defined name for the run. If provided null, a name will be automatically generated based on the method name and the datetime.
System.StringdescriptionA user-defined description for the run.
System.Collections.Generic.IEnumerable<System.String>labelsA list of arbitrary labels that are associated with the run. These are often user-defined labels to promote categorization of routines and runs.
Newtonsoft.Json.Linq.JObjectattributesAny additional metadata that will be stored on the run object itself. This is a JSON object that contains additional metadata that will be put here during the instantiation of the run.
System.Collections.Generic.Dictionary<System.String,System.Object>extraAdditional execution related data that may be required for the backend orchestrator. Leave this empty if you are not sure what to put here.
System.Threading.CancellationTokencancellationToken

CreateMethodRunAsync(string, JObject?, string, bool, bool, bool, double?, InvocationMethodType?, string?, string?, IEnumerable<string>?, JObject?, Dictionary<string, object>?, CancellationToken)​

Create a new Method Run for the routine instance.

Note: This can create a constructor run by providing "init" as the methodName. Note: This method does not start the run. To start the run, call the Workspace.XBR.Xperiflow.Routines.Runs.Run.StartAsync(System.Threading.CancellationToken) method on the returned Run object.

Declaration
public Task<Run> CreateMethodRunAsync(string methodName, JObject? inputParams = null, string executionType = "background", bool storeArtifacts = true, bool includeStatistics = false, bool includePreviews = false, double? memoryOverride = null, InvocationMethodType? invocationMethodType = null, string? runName = null, string? description = "", IEnumerable<string>? labels = null, JObject? attributes = null, Dictionary<string, object>? extra = null, CancellationToken cancellationToken = default)
Returns​

Task< Workspace.XBR.Xperiflow.Routines.Runs.Run >

Parameters​
TypeNameDescription
System.StringmethodNameThe name of the method to be invoked. This is the name of the method that is defined for the given Routine Type. Note this
is the "Method Name" attribute defined in the Routine Documentation (not the Method Title).
Newtonsoft.Json.Linq.JObjectinputParamsThe input parameters for the method. This is a JSON object that contains the input parameters for the method.
System.StringexecutionTypeThe way in which to execution the Routine Method Run. The supported options are: "background" and "in-memory".
Please see Workspace.XBR.Xperiflow.Routines.Runs.Run class definition for more information.
System.BooleanstoreArtifactsA flag to indicate whether to store the resulting artifacts that are returned from this run.
System.BooleanincludeStatisticsA flag to indicate whether to generate statistics for this run. It is recommended to set this to false if statistics are not needed as calculating statistics can take extra time.
System.BooleanincludePreviewsA flag to indicate whether to generate previews for this run. It is recommended to set this to false if previews are not needed as generating previews can take extra time.
System.Nullable<System.Double>memoryOverrideThe memory override for the run. If not provided, the memory capacity defined at the routine method level will be used.
Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodTypeinvocationMethodTypeThe type of invocation method to use for the run. Defaults to Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Direct invocation. If you are programmatically creating a run,
it is recommended to use the Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Direct invocation type. If you are looking to have the user provide input parameters later
via component workflow, use the Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Workflow invocation type
System.StringrunNameA user-defined name for the run. If provided null, a name will be automatically generated based on the method name and the datetime.
System.StringdescriptionA user-defined description for the run.
System.Collections.Generic.IEnumerable<System.String>labelsA list of arbitrary labels that are associated with the run. These are often user-defined labels to promote categorization of routines and runs.
Newtonsoft.Json.Linq.JObjectattributesAny additional metadata that will be stored on the run object itself. This is a JSON object that contains additional metadata that will be put here during the instantiation of the run.
System.Collections.Generic.Dictionary<System.String,System.Object>extraAdditional execution related data that may be required for the backend orchestrator. Leave this empty if you are not sure what to put here.
System.Threading.CancellationTokencancellationToken

CreateRunAsync(string, string?, bool, bool, InvocationMethodType, JObject?, string?, double?, Dictionary<string, object>?, bool, string, IEnumerable<string>?, JObject?, CancellationToken)​

Creates a new run for the routine instance.

Declaration
public Task<Run> CreateRunAsync(string methodName, string? runName, bool includeStatistics, bool includePreviews, InvocationMethodType invocationMethodType, JObject? inputParams, string? description = "", double? memoryOverride = null, Dictionary<string, object>? extra = null, bool storeArtifacts = true, string executionType = "background", IEnumerable<string>? labels = null, JObject? attributes = null, CancellationToken cancellationToken = default)
Remarks​

Note: This method does not start the run. To start the run, call the Workspace.XBR.Xperiflow.Routines.Runs.Run.StartAsync(System.Threading.CancellationToken) method on the returned Run object.

Returns​

Task< Workspace.XBR.Xperiflow.Routines.Runs.Run >

A new run object that represents the run that was just created.

Parameters​
TypeNameDescription
System.StringmethodNameThe name of the method to be invoked. This is the name of the method that is defined for the given Routine Type. Note this
is the "Method Name" attribute defined in the Routine Documentation (not the Method Title).
System.StringrunNameA user-defined name for the run. If provided null, a name will be automatically generated based on the method name and the datetime.
System.BooleanincludeStatisticsA flag to indicate whether to generate statistics for this run. It is recommended to set this to false if statistics are not needed as calculating statistics can take extra time.
System.BooleanincludePreviewsA flag to indicate whether to generate previews for this run. It is recommended to set this to false if previews are not needed as generating previews can take extra time.
Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodTypeinvocationMethodTypeThe type of invocation method to use for the run. If you are programmatically creating a run, it is recommended to use the Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Direct invocation type.
If you are looking to have the user provide input parameters later via component workflow, use the Workspace.XBR.Xperiflow.Routines.Runs.InvocationMethodType.Workflow invocation type
Newtonsoft.Json.Linq.JObjectinputParamsThe input parameters for the method. This is a JSON object that contains the input parameters for the method.
System.StringdescriptionA user-defined description for the run.
System.Nullable<System.Double>memoryOverrideThe memory override for the run. If not provided, the memory capacity defined at the routine method level will be used.
System.Collections.Generic.Dictionary<System.String,System.Object>extraAdditional execution related data that may be required for the backend orchestrator. Leave this empty if you are not sure what to put here.
System.BooleanstoreArtifactsA flag to indicate whether to store the resulting artifacts that are returned from this run.
System.StringexecutionTypeThe way in which to execution the Routine Method Run. The supported options are: "background" and "in-memory".
Please see Workspace.XBR.Xperiflow.Routines.Runs.Run class definition for more information.
System.Collections.Generic.IEnumerable<System.String>labelsA list of arbitrary labels that are associated with the run. These are often user-defined labels to promote categorization of routines and runs.
Newtonsoft.Json.Linq.JObjectattributesAny additional metadata that will be stored on the run object itself.
System.Threading.CancellationTokencancellationToken
Exceptions​

System.ArgumentException Thrown when the methodName or runName is an empty string. Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceException Thrown when the Run creation fails or the retrieval of the Run metadata fails. OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

DeleteRunAsync(string, CancellationToken)​

Deletes the Workspace.XBR.Xperiflow.Routines.Runs with the given runIdentifier.

Note: this method will delete the run and all of its associated data. This action is irreversible.

Declaration
public Task DeleteRunAsync(string runIdentifier, CancellationToken cancellationToken = default)
Returns​

System.Threading.Tasks.Task

Parameters​
TypeNameDescription
System.StringrunIdentifierThe identifier of the run to delete.
System.Threading.CancellationTokencancellationToken
Exceptions​

System.ArgumentException Thrown when the runIdentifier is an empty string. Workspace.XBR.Xperiflow.Routines.Instances.RoutineInstanceException Thrown when the API call fails or the response is invalid. OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

GetConstructorRunAsync(CancellationToken)​

Gets the Workspace.XBR.Xperiflow.Routines.Runs for the routine instance that represents the constructor run. If the constructor run does not exist, this method will return null.

Declaration
public Task<Run?> GetConstructorRunAsync(CancellationToken cancellationToken = default)
Returns​

Task< Workspace.XBR.Xperiflow.Routines.Runs.Run >

Parameters​
TypeName
System.Threading.CancellationTokencancellationToken

GetRunByIdentifierAsync(string, CancellationToken)​

Gets the Workspace.XBR.Xperiflow.Routines.Runs with the given runIdentifier. If the run does not exist, this method will return null.

Declaration
public Task<Run?> GetRunByIdentifierAsync(string runIdentifier, CancellationToken cancellationToken = default)
Returns​

Task< Workspace.XBR.Xperiflow.Routines.Runs.Run >

Run or null

Parameters​
TypeNameDescription
System.StringrunIdentifierThe run identifier.
System.Threading.CancellationTokencancellationToken
Exceptions​

System.ArgumentException Thrown when the runIdentifier is an empty string. OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

GetLatestRunAsync(CancellationToken)​

Gets the latest Workspace.XBR.Xperiflow.Routines.Runs.Run for the routine instance. The 'latest' run is determined by the creation time of the run. If no runs exist, this method will return null.

Declaration
public Task<Run?> GetLatestRunAsync(CancellationToken cancellationToken = default)
Returns​

Task< Workspace.XBR.Xperiflow.Routines.Runs.Run >

Run or null

Parameters​
TypeName
System.Threading.CancellationTokencancellationToken
Exceptions​

OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

GetRunsAsync(CancellationToken)​

Gets all the Workspace.XBR.Xperiflow.Routines.Runs.Runs for the routine instance. If no runs exist, this method will return an empty list.

Declaration
public Task<List<Run>> GetRunsAsync(CancellationToken cancellationToken = default)
Returns​

Task<System.Collections.Generic.List{Workspace.XBR.Xperiflow.Routines.Runs.Run}>

A list of run objects. If no runs exist, this method will return an empty list.

Parameters​
TypeName
System.Threading.CancellationTokencancellationToken
Exceptions​

OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

Inherited Members​

  • System.Object.Equals(System.Object)
  • System.Object.Equals(System.Object,System.Object)
  • System.Object.GetHashCode
  • System.Object.GetType
  • System.Object.MemberwiseClone
  • System.Object.ReferenceEquals(System.Object,System.Object)
  • System.Object.ToString
Last updated on by Jeremy Meiss

Was this page helpful?