Class Artifact

Represents a single Artifact produced by a Workspace.XBR.Xperiflow.Routines.Runs.Run?text=routine+run.

Namespace: Workspace.XBR.Xperiflow.Routines.Artifacts

Assembly: Xperiflow.dll

Declaration

public class Artifact

Examples

Retrieve a prediction CSV as a string, then list its backing files:

Artifact a  = run.GetArtifactAsync("predictions.csv").Result!;
string csv  = a.GetDataAsObjectAsync().Result;
List files = a.GetDataFilePathsAsync().Result;

Remarks

An Artifact is any file-based output generated by a routine method: Parquets, CSVs, JSON documents, images, model binaries, etc. Each artifact is backed by one or more physical files in a configured file-system backend (MetaFileSystem, Azure Blob, S3, SMB share …).

Key concepts

• Artifact Key The name of an artifact within a single run. Not necessarily unique across nested outputs.

• Artifact Qualified Key A dot-delimited path that is unique within the run: my_list.0.dataframe → key dataframe, qualified key my_list.0.dataframe.

• Aggregate Artifact A logical grouping (directory) of other artifacts; it contains statistics and previews but no primary data files of its own.

Choosing an access method

• Use Workspace.XBR.Xperiflow.Routines.Artifacts.Artifact.GetDataAsObjectAsync%60%601(System.Threading.CancellationToken) to download & deserialize common formats directly into .NET types such as DataTable, string, or JObject:

DataTable tbl = artifact.GetDataAsObjectAsync().Result;

• Call Workspace.XBR.Xperiflow.Routines.Artifacts.Artifact.GetDataFilePathsAsync(System.Threading.CancellationToken) when you need raw file paths — for example: querying files directly from MetaDB, streaming very large datasets, or working with non-standard formats (images, model checkpoints, proprietary blobs).

Threading guidance

The SDK exposes asynchronous methods for scalability, but synchronous patterns are fully supported—returning objects via .Result and awaiting void methods with .Wait().

Properties

Key

The key of the artifact. Note that this is not unique, but rather a human-readable identifier. Please use the Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactMetadata.QualifiedKey as a unique identifier within the context of a Routine Method Run.

Declaration

public string Key { get; }

QualifiedKey

The qualified key of the artifact. This uniqely identifiers the artifact in the context of a routine method. The difference between the Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactMetadata.Key and Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactMetadata.QualifiedKey is that the Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactMetadata.QualifiedKey is the fully qualified key and accounts for nested artifacts. The Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactMetadata.QualifiedKey is guaranteed to be unique within the Artifacts returned by a given Routine Method Run. An example of a Qualified Key may be "outer_artifact.inner_table_artifact" where the "outer_artifact" is the key of the outer artifact and "inner_table_artifact" is the key of the inner artifact. The Key for this Qualified Key example would just be "inner_table_artifact".

Declaration

public string QualifiedKey { get; }

Title

The human-readable alias of the artifact.

Declaration

public string Title { get; }

Description

The human-readable description of the artifact.

Declaration

public string Description { get; }

Path

The directory path to the artifact. Note that this is not the path to the artifact data, but rather the path to the artifact directory.

Declaration

public string Path { get; }

InstanceIdentifier

The instance identifier that this artifact belongs to.

Declaration

public string InstanceIdentifier { get; }

RunIdentifier

The run identifier that this artifact belongs to. This run generated this artifact.

Declaration

public string RunIdentifier { get; }

RoutineTypename

The Routine type that this artifact was generated from.

Declaration

public string RoutineTypename { get; }

MethodName

The routine method name that this artifact was generated from.

Declaration

public string MethodName { get; }

CreationTime

The UTC time that the artifact was created.

Declaration

public DateTime CreationTime { get; }

ArtifactPythonDataType

The python datatype of the artifact. This is the object type that was serialized to the file system using the IO factory.

Declaration

public string ArtifactPythonDataType { get; }

IsAggregateArtifact

Whether or not the artifact is an aggregate artifact. An aggregate artifact is an artifact that does not directly contain data, but rather it is a 'parent' of other artifacts. An aggregate artifact will still have its own metadata, statistics, and previews.

Declaration

public bool IsAggregateArtifact { get; }

Annotation

The annotation of the artifact. This is useful to inform the user about the type of data files that are stored in the artifact.

Declaration

public ArtifactAnnotation? Annotation { get; }

IoFactoryTypename

The python typename of the IO factory that is used for serializing and deserializing the artifact data. This will be null if the artifact is an aggregate artifact.

Declaration

public string? IoFactoryTypename { get; }

IoFactoryKwargs

The python keyword arguments that are used to instantiate.

Declaration

public JObject? IoFactoryKwargs { get; }

IoFactorySerializedInstanceData

The serialized instance data of the IO factory. This will be null if the artifact is an aggregate artifact.

Declaration

public JObject? IoFactorySerializedInstanceData { get; }

StatisticFactoryTypename

The python typename of the statistic factory that is used for generating the artifact statistics.

Declaration

public string? StatisticFactoryTypename { get; }

StatisticFactoryKwargs

The python keyword arguments that are used to instantiate the statistic factory.

Declaration

public JObject? StatisticFactoryKwargs { get; }

StatisticFactorySerializedInstanceData

The serialized instance data of the statistic factory.

Declaration

public JObject? StatisticFactorySerializedInstanceData { get; }

PreviewFactoryTypename

The python typename of the preview factory that is used for generating and serializing the artifact previews.

Declaration

public string? PreviewFactoryTypename { get; }

PreviewFactoryKwargs

The python keyword arguments that are used to instantiate the preview factory.

Declaration

public JObject? PreviewFactoryKwargs { get; }

PreviewFactorySerializedInstanceData

The serialized instance data of the preview factory.

Declaration

public JObject? PreviewFactorySerializedInstanceData { get; }

Methods

GetDataFilePathsAsync(CancellationToken)

Enumerates the physical data files that back this Workspace.XBR.Xperiflow.Routines.Artifacts.Artifact.

Declaration

public Task<List<string>> GetDataFilePathsAsync(CancellationToken cancellationToken = default)

Remarks

Which API should I use?

Internally the method:

Returns

Task<System.Collections.Generic.List{System.String}>

A list of absolute file paths. The list is empty when the artifact is aggregate or when the data directory contains no files.

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	Optional token that aborts the directory scan in the OneStream file-system.

Exceptions

OneStream.Shared.Common.XFException Wraps any I/O or unexpected error; the original exception is logged via OneStream.Shared.Database.ErrorHandler.LogWrite(OneStream.Shared.Common.SessionInfo%2cSystem.Exception).

GetPreviewDataFilePathsAsync(CancellationToken)

Get the preview data file paths for the artifact. This will return an empty list if there are no preview data files that exist.

Declaration

public Task<List<string>> GetPreviewDataFilePathsAsync(CancellationToken cancellationToken = default)

Returns

Task<System.Collections.Generic.List{System.String}>

list of file paths

Parameters

Type	Name
System.Threading.CancellationToken	cancellationToken

Exceptions

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

GetStatisticFilePathsAsync(CancellationToken)

The statistic file paths for the artifact. This will return an empty list if there are no statistic files that exist.

Declaration

public Task<List<string>> GetStatisticFilePathsAsync(CancellationToken cancellationToken = default)

Returns

Task<System.Collections.Generic.List{System.String}>

list of file paths

Parameters

Type	Name
System.Threading.CancellationToken	cancellationToken

Exceptions

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

GetArtifactStatisticsAsync(CancellationToken)

Retrieves the Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactStatistic objects of the artifact. If there are no statistics, an empty list will be returned.

Declaration

public Task<List<ArtifactStatistic>> GetArtifactStatisticsAsync(CancellationToken cancellationToken = default)

Returns

Task<System.Collections.Generic.List{Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactStatistic}>

a list of Workspace.XBR.Xperiflow.Routines.Artifacts.ArtifactStatisticobjects

Parameters

Type	Name
System.Threading.CancellationToken	cancellationToken

Exceptions

System.Collections.Generic.KeyNotFoundException If there are any missing keys in the statistic file. OneStream.Shared.Common.XFException The OneStream aggregate exception that wraps any exception thrown.

GetDataAsObjectAsync<T>(CancellationToken)

Deserializes the primary data files of the current Workspace.XBR.Xperiflow.Routines.Artifacts.Artifact into a strongly-typed .NET object of type T.

Declaration

public Task<T?> GetDataAsObjectAsync<T>(CancellationToken cancellationToken = default)

Remarks

The method delegates responsibility for selecting the correct Workspace.XBR.Xperiflow.Routines.Io.IArtifactIoFactory%601 and Workspace.XBR.Xperiflow.Routines.Io.IArtifactReader%601 to the injected Workspace.XBR.Xperiflow.Routines.Io.IArtifactDataResolver. The resolver:

If Workspace.XBR.Xperiflow.Routines.Artifacts.Artifact.IsAggregateArtifact is true, the call fails; aggregate artifacts do not contain direct data streams.

Returns

Task<{T}>

A fully populated instance of T containing the artifact’s data, or null when the artifact contains no data that can be read as T.

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	A token that can be used to cancel the asynchronous read operation.

Type Parameters

Name

Description

T

Target .NET type—for example System.Data.DataTable, System.String, Newtonsoft.Json.Linq.JObject, or a domain-specific POCO. Important: Not every artifact format can be mapped to every .NET type. The mapping rules are determined at runtime by registered Workspace.XBR.Xperiflow.Routines.Io.IArtifactIoFactory%601 implementations. See Workspace.XBR.Xperiflow.Routines.Io.IArtifactDataResolver for extension guidelines.

Exceptions

OneStream.Shared.Common.XFException Thrown when:

• The artifact is aggregate.

• No compatible Workspace.XBR.Xperiflow.Routines.Io.IArtifactIoFactory%601 is registered.

• The selected reader deems the artifact’s file annotations incompatible.

• An I/O or deserialization error occurs while reading.

The original exception is wrapped and logged through OneStream.Shared.Database.ErrorHandler.LogWrite(OneStream.Shared.Common.SessionInfo%2cSystem.Exception).

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