DTO Flow help center

using DtoFlow.Integration;
using DtoFlow.Integration.Models;

namespace DtoFlow.IntegrationExample;

public static class DiscoveryExample
{
    // periodKey is a choice from the returned catalog, for example a selection saved by your UI.
    // Keep the reportVersionKey, selection and file bytes for retries of this report version.
    public static async Task<AutomationSubmission> RunAsync(
        DtoFlowAutomationClient client, string feedSlug, string subfeedKey, string periodKey,
        string reportVersionKey, IReadOnlyList<(string Path, string ContentType)> inputs,
        string downloadDirectory, CancellationToken cancellationToken)
    {
        var connection = await client.GetConnectionAsync(cancellationToken);
        if (!connection.Capabilities.Contains("PeriodSelection"))
            throw new InvalidOperationException("This connection does not support period selection.");
        AutomationAccessibleFeed? feed = null;
        for (var page = 1; ; page++)
        {
            var feeds = await client.ListAccessibleFeedsAsync(page, cancellationToken);
            feed = feeds.Items.SingleOrDefault(item => item.Slug == feedSlug);
            if (feed is not null || !feeds.HasNextPage) break;
        }
        if (feed is null) throw new InvalidOperationException("The token cannot access the configured feed.");

        AutomationSubfeedResourceResponse? destination = null;
        for (var page = 1; ; page++)
        {
            var subfeeds = await client.ListSubfeedsAsync(feed.Slug, page, cancellationToken);
            destination = subfeeds.Items.SingleOrDefault(item => item.SubfeedKey == subfeedKey);
            if (destination is not null || !subfeeds.HasNextPage) break;
        }
        if (destination is null) throw new InvalidOperationException("The upload destination is unavailable.");
        var manifest = await client.GetSubfeedManifestBySubfeedKeyAsync(feed.Slug, destination.SubfeedKey, cancellationToken);
        var periods = await client.ListSubfeedScheduledPeriodsBySubfeedKeyAsync(feed.Slug, destination.SubfeedKey,
            cancellationToken: cancellationToken);
        var period = periods.Single(item => item.PeriodKey == periodKey);
        if (!period.UploadAllowed) throw new InvalidOperationException(period.UploadBlockedReason);
        if (inputs.Count > manifest.Feed.UploadLimits.MaxFileCount)
            throw new InvalidOperationException("Too many files for one submission.");
        var selection = new AutomationPeriodSelection(period.PeriodKey, period.ScheduleRevision);
        var files = inputs.Select(input => new CreateAutomationUploadFileRequest(null,
            System.IO.Path.GetFileName(input.Path), input.ContentType, new FileInfo(input.Path).Length)).ToArray();
        var session = await client.CreateSubfeedUploadSessionByPeriodAndSubfeedKeyAsync(feed.Slug, destination.SubfeedKey,
            selection, files, new AutomationUploadRequestOptions { IdempotencyKey = reportVersionKey }, cancellationToken);
        // Save session.SubmissionId before uploading. A recovered session contains only missing targets.
        foreach (var target in session.Files)
        {
            var input = inputs.Single(input => System.IO.Path.GetFileName(input.Path) == target.OriginalFileName);
            await using var source = File.OpenRead(input.Path);
            await client.UploadFileAsync(target, source, cancellationToken);
        }
        await client.CompleteSubfeedUploadBySubfeedKeyAsync(feed.Slug, destination.SubfeedKey, session.SubmissionId, cancellationToken);
        AutomationSubmission submission;
        for (var attempt = 0; ; attempt++)
        {
            submission = await client.GetSubmissionAsync(session.SubmissionId, cancellationToken);
            if (submission.Accepted || submission.Status is "ValidationFailed" or "Rejected" or "Archived") break;
            if (attempt == 29) throw new TimeoutException($"Check submission {session.SubmissionId} again later.");
            await Task.Delay(TimeSpan.FromSeconds(2), cancellationToken);
        }
        Directory.CreateDirectory(downloadDirectory);
        foreach (var file in submission.Files)
        {
            var link = await client.GetOriginalDownloadAsync(submission.SubmissionId, file.SubmittedFileId, cancellationToken);
            // A local name based on the file ID avoids trusting remote names as filesystem paths.
            var destinationPath = System.IO.Path.Combine(downloadDirectory, $"{file.SubmittedFileId:N}.original");
            await SaveDownloadAsync(destinationPath,
                (output, ct) => client.DownloadOriginalFileAsync(link, output, ct), cancellationToken);
        }
        return submission; // Inspect validation details in the GUI when Status is ValidationFailed.
    }

    static async Task SaveDownloadAsync(string destinationPath,
        Func<Stream, CancellationToken, Task> download, CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(download);
        cancellationToken.ThrowIfCancellationRequested();
        var fullPath = Path.GetFullPath(destinationPath);
        if (File.Exists(fullPath)) throw new IOException("The download destination already exists.");
        var temporaryPath = Path.Combine(Path.GetDirectoryName(fullPath)!, $".dtoflow-{Guid.NewGuid():N}.partial");
        var output = new FileStream(temporaryPath, FileMode.CreateNew, FileAccess.Write, FileShare.None);
        try
        {
            await using (output)
            {
                await download(output, cancellationToken);
            }
            cancellationToken.ThrowIfCancellationRequested();
            File.Move(temporaryPath, fullPath); // Same directory; never replace an existing destination.
        }
        finally
        {
            File.Delete(temporaryPath); // Only this attempt's file; a completed move leaves nothing here.
        }
    }
}

using DtoFlow.Integration;
using DtoFlow.Integration.Models;

var baseUrl = Environment.GetEnvironmentVariable("DTOFLOW_BASE_URL") ?? "https://api.dtoflow.com";
var token = Environment.GetEnvironmentVariable("DTOFLOW_TOKEN")
    ?? throw new InvalidOperationException("Set DTOFLOW_TOKEN.");
var feedSlug = Environment.GetEnvironmentVariable("DTOFLOW_FEED_SLUG") ?? "supplier-prices";
var partnerKey = Environment.GetEnvironmentVariable("DTOFLOW_PARTNER_KEY") ?? "northwind";
var subfeedKey = Environment.GetEnvironmentVariable("DTOFLOW_SUBFEED_KEY") ?? "northwind-prices";

using var httpClient = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseDefaultCredentials = false }) { BaseAddress = new Uri(baseUrl) };
var client = new DtoFlowAutomationClient(httpClient, token);

var readiness = await client.CheckPartnerReadinessBatchAsync(feedSlug, new[]
{
    new AutomationPartnerReadinessItem(
        "recipient-1", partnerKey, "Northwind Foods", "recipient@example.invalid",
        "PartnerObserver", subfeedKey, "Active")
});

foreach (var result in readiness.Results)
{
    Console.WriteLine($"{result.CorrelationId}: {result.Outcome} {result.Error?.Code}");
    Console.WriteLine($"Upload ready: {result.SubfeedUploadReady}; portal ready: {result.PortalReady}");
    Console.WriteLine(string.Join(", ", result.RequiredActions));
}

using System.Globalization;
using DtoFlow.Integration;
using DtoFlow.Integration.Models;

var baseUrl = Environment.GetEnvironmentVariable("DTOFLOW_BASE_URL") ?? "https://api.dtoflow.com";
var token = Environment.GetEnvironmentVariable("DTOFLOW_TOKEN")
    ?? throw new InvalidOperationException("Set DTOFLOW_TOKEN.");
var feedSlug = Environment.GetEnvironmentVariable("DTOFLOW_FEED_SLUG") ?? "supplier-prices";
var filePath = args.Length > 0 ? args[0] : "prices.csv";
var deadlineAt = DateTimeOffset.Parse(
    Environment.GetEnvironmentVariable("DTOFLOW_DEADLINE_AT") ?? "2026-06-01T12:00:00Z",
    CultureInfo.InvariantCulture);

using var httpClient = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseDefaultCredentials = false }) { BaseAddress = new Uri(baseUrl) };
var client = new DtoFlowAutomationClient(httpClient, token);
var fileInfo = new FileInfo(filePath);

try
{
    var session = await client.CreateUploadSessionAsync(
        feedSlug,
        deadlineAt,
        new[]
        {
            new CreateAutomationUploadFileRequest(
                FeedFileSlug: null,
                OriginalFileName: fileInfo.Name,
                ContentType: "text/csv",
                SizeBytes: fileInfo.Length)
        });

    using var upload = File.OpenRead(filePath);
    await client.UploadFileAsync(session.Files[0], upload);
    await client.CompleteUploadAsync(feedSlug, session.SubmissionId);

    AutomationPeriodStatus? period = null;
    for (var attempt = 0; attempt < 30; attempt++)
    {
        period = await client.GetPeriodStatusByDeadlineAsync(feedSlug, deadlineAt);
        if (period.AcceptedFilesAvailable)
        {
            break;
        }

        if (period.Status is "ValidationFailed" or "Rejected" or "Archived")
        {
            throw new InvalidOperationException(
                $"Submission {period.SubmissionId} finished with status {period.Status}.");
        }

        await Task.Delay(TimeSpan.FromSeconds(2));
    }

    if (period?.AcceptedFilesAvailable != true)
    {
        throw new TimeoutException("The accepted file was not ready within one minute.");
    }

    var accepted = await client.GetAcceptedFilesByDeadlineAsync(feedSlug, deadlineAt);
    foreach (var acceptedFile in accepted.Files)
    {
        var destinationPath = ResolveDownloadPath(
            Directory.GetCurrentDirectory(),
            acceptedFile.SubmittedFileId);
        await SaveDownloadAsync(destinationPath,
            (destination, ct) => client.DownloadAcceptedFileAsync(acceptedFile, destination, ct));
        Console.WriteLine($"Downloaded {destinationPath}");
    }
}
catch (DtoFlowAutomationException ex) when (ex.IsTenantAccessReadOnly)
{
    Console.Error.WriteLine($"Tenant access is {ex.TenantAccessState}; required action: {ex.TenantAccessRequiredAction}.");
    Environment.ExitCode = 2;
}

static string ResolveDownloadPath(string downloadDirectory, Guid submittedFileId)
{
    // Use the file identity, never an untrusted remote filename, as the local name.
    return Path.Combine(Path.GetFullPath(downloadDirectory), $"{submittedFileId:N}.original");
}

static async Task SaveDownloadAsync(string destinationPath,
    Func<Stream, CancellationToken, Task> download, CancellationToken cancellationToken = default)
{
    ArgumentNullException.ThrowIfNull(download);
    cancellationToken.ThrowIfCancellationRequested();
    var fullPath = Path.GetFullPath(destinationPath);
    if (File.Exists(fullPath)) throw new IOException("The download destination already exists.");
    var temporaryPath = Path.Combine(Path.GetDirectoryName(fullPath)!, $".dtoflow-{Guid.NewGuid():N}.partial");
    var output = new FileStream(temporaryPath, FileMode.CreateNew, FileAccess.Write, FileShare.None);
    try
    {
        await using (output)
        {
            await download(output, cancellationToken);
        }
        cancellationToken.ThrowIfCancellationRequested();
        File.Move(temporaryPath, fullPath); // Same directory; never replace an existing destination.
    }
    finally
    {
        File.Delete(temporaryPath); // Only this attempt's file; a completed move leaves nothing here.
    }
}

using System.Globalization;
using System.Linq;
using DtoFlow.Integration;

var baseUrl = Environment.GetEnvironmentVariable("DTOFLOW_BASE_URL") ?? "https://api.dtoflow.com";
var token = Environment.GetEnvironmentVariable("DTOFLOW_TOKEN")
    ?? throw new InvalidOperationException("Set DTOFLOW_TOKEN.");
var feedSlug = Environment.GetEnvironmentVariable("DTOFLOW_FEED_SLUG") ?? "supplier-prices";
var deadlineAt = DateTimeOffset.Parse(
    Environment.GetEnvironmentVariable("DTOFLOW_DEADLINE_AT") ?? "2026-06-01T12:00:00Z",
    CultureInfo.InvariantCulture);

using var httpClient = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseDefaultCredentials = false }) { BaseAddress = new Uri(baseUrl) };
var client = new DtoFlowAutomationClient(httpClient, token);

var manifest = await client.GetManifestAsync(feedSlug);
Console.WriteLine($"Feed: {manifest.Name} ({manifest.Slug})");
Console.WriteLine($"Direction: {manifest.Direction}; status: {manifest.Status}");
Console.WriteLine($"Token scopes: {string.Join(", ", manifest.TokenScopes)}");

foreach (var file in manifest.Files.OrderBy(file => file.SortOrder))
{
    Console.WriteLine(
        $"- {file.Slug}: {file.ExpectedExtension}, required={file.RequiredInSubmission}, validation={file.IsValidationEnabled}");
}

var period = await client.GetPeriodStatusByDeadlineAsync(feedSlug, deadlineAt);
if (!period.HasSubmission)
{
    Console.WriteLine("No submission has been completed for this period yet.");
    return;
}

if (!period.Accepted || !period.AcceptedFilesAvailable)
{
    Console.WriteLine($"Submission {period.SubmissionId} is {period.Status}; validation is {period.ValidationStatus}.");
    return;
}

var accepted = await client.GetAcceptedFilesByDeadlineAsync(feedSlug, deadlineAt);
Console.WriteLine($"{accepted.Files.Count} accepted file(s) are ready from {accepted.SubmissionId}.");

using System.Globalization;
using System.Linq;
using DtoFlow.Integration;
using DtoFlow.Integration.Models;

var baseUrl = Environment.GetEnvironmentVariable("DTOFLOW_BASE_URL") ?? "https://api.dtoflow.com";
var token = Environment.GetEnvironmentVariable("DTOFLOW_TOKEN")
    ?? throw new InvalidOperationException("Set DTOFLOW_TOKEN.");
var feedSlug = Environment.GetEnvironmentVariable("DTOFLOW_FEED_SLUG") ?? "weekly-pack";
var deadlineAt = DateTimeOffset.Parse(
    Environment.GetEnvironmentVariable("DTOFLOW_DEADLINE_AT") ?? "2026-06-01T12:00:00Z",
    CultureInfo.InvariantCulture);
var downloadDirectory = Environment.GetEnvironmentVariable("DTOFLOW_DOWNLOAD_DIR") ?? "accepted";

var uploadFiles = new[]
{
    new { FeedFileSlug = "prices", Path = "incoming/prices.csv", ContentType = "text/csv" },
    new { FeedFileSlug = "inventory", Path = "incoming/inventory.xlsx", ContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" },
};

using var httpClient = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseDefaultCredentials = false }) { BaseAddress = new Uri(baseUrl) };
var client = new DtoFlowAutomationClient(httpClient, token);

try
{
var session = await client.CreateUploadSessionAsync(
    feedSlug,
    deadlineAt,
    uploadFiles.Select(file =>
    {
        var fileInfo = new FileInfo(file.Path);
        return new CreateAutomationUploadFileRequest(
            file.FeedFileSlug,
            fileInfo.Name,
            file.ContentType,
            fileInfo.Length);
    }).ToArray());

var uploadTargets = session.Files.ToDictionary(
    file => file.OriginalFileName,
    StringComparer.OrdinalIgnoreCase);

foreach (var uploadFile in uploadFiles)
{
    var fileName = Path.GetFileName(uploadFile.Path);
    await using var stream = File.OpenRead(uploadFile.Path);
    await client.UploadFileAsync(uploadTargets[fileName], stream);
    Console.WriteLine($"Uploaded {fileName}.");
}

await client.CompleteUploadAsync(feedSlug, session.SubmissionId);

var period = await client.GetPeriodStatusByDeadlineAsync(feedSlug, deadlineAt);
if (!period.AcceptedFilesAvailable)
{
    Console.WriteLine($"Submission {session.SubmissionId} is {period.Status}; try download after validation completes.");
    return;
}

Directory.CreateDirectory(downloadDirectory);
var accepted = await client.GetAcceptedFilesByDeadlineAsync(feedSlug, deadlineAt);

foreach (var acceptedFile in accepted.Files)
{
    var destinationPath = ResolveDownloadPath(downloadDirectory, acceptedFile.SubmittedFileId);
    await SaveDownloadAsync(destinationPath,
        (destination, ct) => client.DownloadAcceptedFileAsync(acceptedFile, destination, ct));
    Console.WriteLine($"Downloaded {destinationPath}.");
}
}
catch (DtoFlowAutomationException ex) when (ex.IsTenantAccessReadOnly)
{
    Console.Error.WriteLine($"Tenant access is {ex.TenantAccessState}; required action: {ex.TenantAccessRequiredAction}.");
    Environment.ExitCode = 2;
}

static string ResolveDownloadPath(string downloadDirectory, Guid submittedFileId)
{
    // Use the file identity, never an untrusted remote filename, as the local name.
    return Path.Combine(Path.GetFullPath(downloadDirectory), $"{submittedFileId:N}.original");
}

static async Task SaveDownloadAsync(string destinationPath,
    Func<Stream, CancellationToken, Task> download, CancellationToken cancellationToken = default)
{
    ArgumentNullException.ThrowIfNull(download);
    cancellationToken.ThrowIfCancellationRequested();
    var fullPath = Path.GetFullPath(destinationPath);
    if (File.Exists(fullPath)) throw new IOException("The download destination already exists.");
    var temporaryPath = Path.Combine(Path.GetDirectoryName(fullPath)!, $".dtoflow-{Guid.NewGuid():N}.partial");
    var output = new FileStream(temporaryPath, FileMode.CreateNew, FileAccess.Write, FileShare.None);
    try
    {
        await using (output)
        {
            await download(output, cancellationToken);
        }
        cancellationToken.ThrowIfCancellationRequested();
        File.Move(temporaryPath, fullPath); // Same directory; never replace an existing destination.
    }
    finally
    {
        File.Delete(temporaryPath); // Only this attempt's file; a completed move leaves nothing here.
    }
}