Robovue.Sdk 0.2.0

Robovue.Sdk

Report your bots' runs to Robovue, which watches every bot in one place and tells you when one fails or doesn't run. This package signs each report, retries when the network or Robovue has a problem, checks a report against Robovue's rules before sending it, and can send dry runs while you set it up.

Install

dotnet add package Robovue.Sdk

Requirements

• .NET Framework 4.6.2 or later, or .NET 6 or later. The package targets netstandard2.0 and net8.0, and is tested on .NET Framework 4.8 and .NET 10.
• A Robovue workspace. Signing up is free.

Can't add a package where your bot runs? Connections → HTTP API in Robovue gives you the same request as plain C#, Python and shell code to paste in, and the wire contract below describes it for any language.

Quickstart

1. Sign up at robovue.co.uk.
2. Copy your credentials from Settings → Connections → HTTP API: the webhook secret, and your tenant ID, which is the long id in the address shown there (https://app.robovue.co.uk/ingest/<tenant ID>/runs).
3. Keep them out of your code. Set them as environment variables on the machine that runs the bot, ROBOVUE_TENANT_ID and ROBOVUE_WEBHOOK_SECRET, or in your platform's credential store, and create one client:

using System.Text.Json;
using Robovue.Sdk;

// One client for the whole process: it's safe to share between threads.
var robovue = new RobovueClient(new RobovueClientOptions
{
    BaseAddress = new Uri("https://app.robovue.co.uk"),
    TenantId = Guid.Parse(Environment.GetEnvironmentVariable("ROBOVUE_TENANT_ID")!),
    WebhookSecret = Environment.GetEnvironmentVariable("ROBOVUE_WEBHOOK_SECRET"),
});

4. Wrap your bot's job. Report the run as Running when it starts, then as Success or Failure when it ends, with the same delivery id so Robovue knows it's one run:

var deliveryId = Guid.NewGuid().ToString(); // one per run: it ties the run's reports together
var startedAt = DateTimeOffset.UtcNow;

await robovue.TryReportRunAsync(new RunReport
{
    BotId = "invoice-bot-01",
    Platform = "dotnet",
    Status = RunStatus.Running,
    StartedAt = startedAt,
}, deliveryId);

try
{
    ProcessInvoices(); // your bot's work
}
catch (Exception ex)
{
    await robovue.TryReportRunAsync(new RunReport
    {
        BotId = "invoice-bot-01",
        Platform = "dotnet",
        Status = RunStatus.Failure,
        StartedAt = startedAt,
        CompletedAt = DateTimeOffset.UtcNow,
        FailureCategory = FailureCategory.ApplicationException,
        Payload = JsonSerializer.SerializeToElement(new { error = ex.Message }),
    }, deliveryId);
    throw;
}

await robovue.TryReportRunAsync(new RunReport
{
    BotId = "invoice-bot-01",
    Platform = "dotnet",
    Status = RunStatus.Success,
    StartedAt = startedAt,
    CompletedAt = DateTimeOffset.UtcNow,
}, deliveryId);

TryReportRunAsync never throws, so a problem reaching Robovue can't break your bot. The job's own exception is reported, then rethrown, so the bot still fails the way it always did.

5. Check it arrives. Run the bot once with DryRun on, then for real, and watch the report land in the Verify step on Connections → HTTP API, in the request log, and on Fleet.

Make missed runs alert

A failure alerts as soon as it's reported. A run that never happens can only be noticed if Robovue knows when to expect it, so in Manage bots, register the bot (its id is BotId) and give it a schedule. Until a bot is registered, its runs appear under Unregistered ids, and each new id counts toward your plan's bot limit.

Reporting in more detail

Failure categories

On a Failure, set FailureCategory to say why it failed. It's shown on the run, filterable on Runs, and named in the alert. Leave it out if you don't know: Robovue records Uncategorized, and a run can be reclassified later from its page.

var result = await robovue.ReportRunAsync(new RunReport
{
    BotId = "invoice-bot-01",
    Platform = "dotnet",
    Status = RunStatus.Failure,
    StartedAt = startedAt,
    CompletedAt = DateTimeOffset.UtcNow,
    FailureCategory = FailureCategory.BusinessException,
});

Attaching context with Payload

Payload takes any JSON and is stored as sent, shown in full on the run's page. Use it for whatever would help you debug the run later: an invoice number, the step that failed, a stack trace. If it has an error, errorMessage or message field, the alert uses that text to say what went wrong.

var result = await robovue.ReportRunAsync(new RunReport
{
    BotId = "invoice-bot-01",
    Platform = "dotnet",
    Status = RunStatus.Failure,
    StartedAt = startedAt,
    CompletedAt = DateTimeOffset.UtcNow,
    FailureCategory = FailureCategory.Timeout,
    Payload = JsonSerializer.SerializeToElement(new
    {
        invoiceId = "INV-2291",
        error = "Timed out waiting for the vendor portal",
    }),
});

The whole report, payload included, must be under 64 KB.

Attaching a screenshot or log to a failed run

On the Team plan and above, you can attach one screenshot or log excerpt to a Failure run once it's reported. Screenshots are off for each bot until someone turns them on (Manage bots → Screenshots), because a screenshot can capture credentials or other sensitive data on screen.

await robovue.UploadAttachmentAsync(result.RunId, screenshotBytes, "image/png");

contentType is "image/png", "image/jpeg" or "text/plain", up to 5 MB, one per run. Robovue deletes attachments after 30 days, or 7 or 14 if an Admin chose that. An upload for a bot with screenshots off, or on a plan without them, gets the same 404 as an unknown run, so catch it if a missing screenshot shouldn't fail your bot.

Reporting without ever throwing

Monitoring shouldn't become a new way for a bot to fail. TryReportRunAsync never throws for a failed report: an invalid report, a rejection or a network problem comes back in the outcome for you to log. It still honours cancellation of the token you pass.

var outcome = await robovue.TryReportRunAsync(report);
if (!outcome.Succeeded)
    Console.Error.WriteLine($"Couldn't report the run to Robovue: {outcome.Error}");

When a report is rejected

ReportRunAsync throws RobovueApiException. Branch on Code, which is stable; the message is for people. Field names the field at fault when there is one, and RequestId is worth quoting if you contact support.

try
{
    await robovue.ReportRunAsync(report);
}
catch (RobovueApiException ex) when (ex.Code == "timestamp_out_of_range")
{
    // This machine's clock is more than 5 minutes out. The message gives Robovue's time.
    Console.Error.WriteLine(ex.Message);
}

Network errors and 5xx responses are retried automatically (3 attempts by default), and so is a 429 after its Retry-After, unless that's more than a minute, when the 429 is thrown instead of blocking your bot. A report is checked against the server's own rules before anything is sent, so most mistakes fail at once with an ArgumentException. Every code is in the responses table below, with whether a retry can help.

Checking a new integration with a dry run

With DryRun = true, every request is checked exactly as a real one would be (signature, fields, plan limits, delivery id) but nothing is stored. The result says what would have happened, and a request that would fail throws the real error.

using var robovue = new RobovueClient(new RobovueClientOptions
{
    BaseAddress = new Uri("https://app.robovue.co.uk"),
    TenantId = tenantId,
    WebhookSecret = webhookSecret,
    DryRun = true, // checked in full, stored nowhere
});

var result = await robovue.ReportRunAsync(report);
Console.WriteLine($"{result.DryRun} {result.WouldBe}"); // True created

Dry runs show in the request log, which warns you if any arrived in the last day, so a bot left in dry-run mode doesn't go unnoticed. Turn it off before going live.

Runs that take a while

The quickstart reports Running first. That's optional, but it means a bot that starts a job and then hangs shows as Running straight away, rather than only when its next run fails to turn up. Reusing the delivery id is the whole mechanism: a fresh id on the second report makes two runs, one stuck Running and one that looks like nobody started it. A run left Running silences nothing: if it never completes, the bot still goes Late and then Overdue on its schedule.

Using it in your bot

One client per process. RobovueClient holds no state between calls, so share one instance across threads. Dispose it when the process ends; a client you create yourself also disposes the HttpClient it made.

Synchronous code. UiPath's Invoke Code, Blue Prism code stages and other places that can't await can block on the call:

var outcome = robovue.TryReportRunAsync(report).GetAwaiter().GetResult();

Timeouts, proxies and TLS. The client uses .NET's HttpClient defaults: the machine's proxy settings, the operating system's trusted certificates (so a corporate TLS-inspection certificate installed on the machine is trusted), and a 100-second timeout per attempt. To change any of them, pass your own HttpClient, such as one from IHttpClientFactory:

var http = new HttpClient(new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.internal:8080"),
})
{
    Timeout = TimeSpan.FromSeconds(30),
};

var robovue = new RobovueClient(options, http); // the SDK never disposes a client you pass in

Options

Troubleshooting

The request log, in Connections, shows every request from the last 7 days and the exact reason any was turned away.

The wire contract (any language)

This is exactly what RobovueClient sends. From a language with no Robovue SDK, send the same request yourself. The tables below are generated from the server's own contract, so they list every field, header, response and limit, including the optional ones.

POST /ingest/{tenantId}/runs

The endpoint both SDKs call, and the one to use from any other language. A JSON object with the fields below.

Headers

Body fields

Responses

Every error body is {"error": "…", "code": "…", "field": "…", "requestId": "…"} — field only when the error is about one field — and every response carries an X-Request-Id header.

Limits

Signing, in one line: "v1=" + hex(HMAC-SHA256(key: webhook secret, message: timestamp + "\nrun\n" + delivery id + "\n" + the exact body bytes)), lowercase, sent with the same timestamp in X-Robovue-Timestamp (Unix seconds). Sign each attempt, retries included, just before sending it. Sign the bytes you actually send: re-serialising the JSON after signing (a different key order, different whitespace) changes them and the request is rejected with invalid_signature. Connections → HTTP API has a signature checker to compare yours against.

The attachment upload (POST /ingest/{tenantId}/runs/{runId}/attachment) uses the same scheme with the word attachment in place of run and the run id (lowercase, hyphenated) in place of the delivery id, computed over the raw file bytes instead of a JSON body. It has no delivery-id header: one attachment per run is what makes it safe to retry.

This scheme is only for the /ingest/{tenantId}/runs endpoint. UiPath Orchestrator, Power Automate and Automation Anywhere connect to Robovue without code; Connections in Robovue sets each one up.

Versions and support

• The package follows semantic versioning. The changelog lists what changed in each version.
• For bots written in Python, robovue-sdk is the same client.
• Questions and problems: contact@robovue.co.uk. Quote the RequestId from the error if there is one.
• Found a security problem? See robovue.co.uk/security.

Licence

MIT, so you can use, change and ship this package freely (see LICENSE in the package). Using the Robovue service is covered by the terms.