Adapter SDK

The OT Backup Adapter SDK is used to build custom sequence steps. A step is a small .NET class that can be added to a backup or restore sequence, for example to export a project, copy files, call a robot controller API, or restore data to a device.

This page is for integrators and adapter developers who need to extend OT Backup with custom functionality.

flowchart LR
  A[Adapter assembly] --> B[Step class]
  B --> C[Step attributes]
  B --> D[Parameters]
  B --> E[Execute]
  E --> F[Progress + Job log]
  E --> G[Outputs + Storage]
  B --> H[Sequence editor]

Where this fits in the application

Custom steps appear in the sequence editor, where users can add them to backup and restore sequences.

For day-to-day sequence configuration, see Configuring Backup and Restore Sequences.

Access

This SDK documentation is part of the new Markdown documentation site under Docs. It is portable with the rest of the Documentation/ folder and replaces the old generated SDK documentation.

Creating a step

Every custom step should:

1. Reference SDK/SDK.csproj or the published OT Backup SDK package.
2. Inherit from StepBase.
3. Add a [Step] attribute.
4. Add one or more [StepParameter] attributes if the step needs user input.
5. Implement Execute(CancellationToken cancellationToken).
6. Report progress and useful job log messages.
7. Return 0 when the step succeeds.

using OTBackup.Common.Entities;
using OTBackup.SDK;

[Step(
    Name = "Example Export",
    DisplayName = "Example Export",
    CompactDisplayName = "Export",
    Path = "Examples",
    Icon = "upload",
    Documentation = "Exports data from the target system.",
    Usage = StepUsage.Backup)]
[StepParameter(
    Name = "TargetPath",
    Type = StepParameterType.Target,
    DefaultValue = "",
    Description = "Where the export should be stored")]
public sealed class ExampleExportStep : StepBase
{
    public ExampleExportStep(StepSettings settings) : base(settings)
    {
    }

    public override async Task<int> Execute(CancellationToken cancellationToken)
    {
        Progress(0, "Starting export");

        string targetPath = GetParameterValue("TargetPath");
        Log($"Exporting to {targetPath}");

        await Task.Delay(1000, cancellationToken);

        Progress(100, "Export complete");
        SaveOutput("exportPath", targetPath);

        return 0;
    }
}

Step metadata

The [Step] attribute controls how the step appears in the sequence editor.

Use a clear Path so users can find the step. Use Documentation and Ports to help integrators understand what the step needs before a job runs.

Use a stable, descriptive Name such as Vendor Device Export, rather than a short action such as Export. DisplayName and CompactDisplayName are presentation metadata; they may be refined in later adapter versions.

Step parameters

Use [StepParameter] to define values users configure in the sequence editor.

Parameter types:

[StepParameter(
    Name = "Mode",
    Type = StepParameterType.SingleChoice,
    Options = "Full;Incremental",
    DefaultValue = "Full",
    Description = "Backup mode")]

Saved sequence compatibility

OT Backup stores only the configurable runtime state of a sequence: each step and parameter identity, the selected worker, parameter values, and parameter results. When a sequence is opened or run, OT Backup resolves that state against the current adapter definitions to supply display labels, types, options, descriptions, and validation rules.

This allows display metadata and defaults to evolve without changing existing sequences. Keep step and parameter Name values stable. If a parameter has been removed from an adapter definition, an existing saved value is preserved as a legacy parameter so it can be reviewed during migration.

Reading parameters at runtime

StepBase gives the step helper methods for reading configured values:

Prefer the helper methods over parsing parameter values yourself.

Storage options

StorageConfig.Options is a System.Text.Json.Nodes.JsonObject for storage-specific settings. It defaults to an empty object; a null options value is normalized to an empty object. Each storage implementation defines the keys it understands; options are copied, including nested objects, when creating child storage instances.

FTP supports these string-valued options:

{
    "Options": {
        "ConnectionMode": "Passive",
        "TransferType": "ASCII"
    }
}

The two FTP options are independent. Unsupported values fail when creating FTP storage. Other storage implementations currently preserve options without interpreting them.

Options replaces the previous StorageConfig.ConfigMode string. Custom adapters using that property must update their initializers and rebuild against the updated Common/SDK assemblies; legacy mode strings are not migrated.

Progress, logs and output

Use progress and logging so users can follow the job from the equipment details dialog and the Jobs page.

Guidelines:

• Report meaningful milestones: start, major phases and completion.
• Pass the CancellationToken to long-running or async operations.
• Avoid logging secrets, passwords, tokens or sensitive file contents.
• Throw or return an error instead of hiding failures.

Revert behavior

Override Revert(CancellationToken cancellationToken) if the step can safely undo its work after a later step fails.

public override Task Revert(CancellationToken cancellationToken)
{
    Log("Reverting exported files");
    return Task.CompletedTask;
}

If reverting fails, throw an exception so the job result shows what happened.

Storage and Backup Storage

Source and Target parameters can use the application's configured Backup Storage. When a parameter uses Backup Storage, CreateStorageFromParameter creates storage using the configured type/path/account. Otherwise it creates file-system storage from the parameter path.

This lets adapter steps work with backup storage without needing to know whether the installation uses a local path, network share or another supported storage type.

See also:

• Configuring Backup and Restore Sequences
• Configuring OT Backup - Backup Storage

Packaging and discovery

In this repository, adapter projects follow the naming convention Adapters.[Vendor].[Name] and are placed under Adapters/.

At runtime, TEE loads adapter assemblies from its Adapters/ output folder and discovers classes decorated with [Step] that inherit from StepBase.

For an adapter to be available to users:

1. Build or publish the adapter assembly.
2. Make sure the DLL is placed in the TEE Adapters/ folder.
3. Restart or reload the TEE process as required by the installation.
4. Open the sequence editor and confirm the step appears under its configured Path.

Recommended checklist

Before handing a custom step to users:

• The class inherits from StepBase.
• The class has a clear [Step] attribute.
• Parameters have useful names, defaults and descriptions.
• Advanced-only settings are marked with Advanced = true.
• The step reports progress and writes useful job log entries.
• Long-running work respects the CancellationToken.
• Required network ports are declared in Ports.
• Secrets are not logged.
• The step has been tested in a real backup/restore sequence.

See Also

• Configuring Backup and Restore Sequences
• Configuring OT Backup
• Adapters