SophonaPluginTemplate 1.0.2

SophonaPluginTemplate

Nodes for Sophona Studio (RobotForce), built against RobotForce.Sophona.PluginConnector 1.0.18.

Build, test, install

dotnet build -c Release        # also creates bin\Release\SophonaPluginTemplate.1.0.0.nupkg
dotnet test                    # tests\SophonaPluginTemplate.Tests

In Sophona Studio click the package icon in the status bar → Package Manager → drop the .nupkg (or Upload .nupkg). The nodes appear without a restart. To publish a new build, raise <Version> first.

What the Package Manager checks

Errors block the installation and say what to change; warnings are shown and the package installs.

Adding a node

1. Copy SophonaHelloWorld.cs, rename the tile class and the method to the same name.
2. description of the tile and tooltip of every field are for the person who builds the workflow - they are shown in the Actions panel and in the node settings: what the node does, what it returns, allowed values, format, default. The agent never sees them (see below).
3. Keep the [RobotInstruction] method thin - it reads its fields and calls Run(...). Every decision goes into an internal static XxxCore(string …) method returning ToolResult, which the tests call directly:

[RobotInstruction]
public Task<object> CountWords(/* fields… */ ScriptVariable text, ScriptVariable outputVariable)
{
    return Run(nameof(CountWords), outputVariable, () => CountWordsCore(ToolKit.Text(text)));
}

internal static ToolResult CountWordsCore(string text)
{
    if (string.IsNullOrWhiteSpace(text))
        return ToolResult.Error("text is empty.", "Pass the text to count, e.g. the output of ReadFile.");

    var words = text.Split((char[])null, StringSplitOptions.RemoveEmptyEntries).Length;
    return ToolResult.Ok(words.ToString());
}

4. Nodes run synchronously - RobotExecutor does not await the returned Task. Asynchronous APIs are called through Task.Run(...).GetAwaiter().GetResult() (see HttpGetText.cs).
5. Once a node is used in workflows, do not change its fields (add, remove, reorder). RobotExecutor passes the saved values by position - such workflows fail with Parameter count mismatch until the node is dropped on them again. Need another field? Add a new node.

Results a workflow and an agent understand

Who sees what:

So a node reaches the agent only through the text it writes into its output variable (when that variable is, or feeds, what the skill returns) and through its exception message. ToolKit.cs implements the contract for both:

Write messages for someone who cannot see the screen:

Say when not to retry (401, 404, invalid certificate) - otherwise an agent that runs the skill will try variations of the same call.

Stop the workflow or keep going (throwOnError)

Some workflows must stop at the first error; others handle errors themselves (a loop over 500 addresses should not die on the first 404). HelloWorld and HttpGetText have the field that lets the workflow author choose - the same idea as throwOnNonZero of RunPowerShell in SystemActions. Put it right before the output variable:

[RobotFieldConfig(
    fieldType = typeof(string),
    isDropdown = true,
    dropdownArray = new string[] { "Yes", "No" },
    defaultValue = "Yes",
    tooltip = "Allowed values: Yes | No. Yes = an error stops the workflow. " +
              "No = the workflow continues and the output variable starts with \"ERROR:\". Optional, default Yes."
)]
ScriptVariable throwOnError,

// …

return Run(nameof(MyNode), outputVariable, () => MyNodeCore(ToolKit.Text(input)),
    stopWorkflowOnError: ToolKit.StopOnError(ToolKit.Text(throwOnError)));

Two things stop the workflow even with No, because the error would otherwise be lost: an unexpected exception (a bug) and a node without an output variable. A value typed into the output field instead of a picked variable counts as no variable - RobotExecutor keeps it in an internal temp_… variable. Without an output variable throwOnError makes no difference: an error stops the workflow, no error leaves it green.

Try it on a workflow

Hello World has a simulateError field (No | Yes, default No) just for this - Studio fills an empty name with the default World, so clearing the name does not produce an error.

1. Install the plugin and drop Hello World on a workflow (a node added before this field existed must be added again). In the Variables panel create a string variable result and pick it as the output variable.
2. Set simulateError = Yes, throwOnError = Yes and run: the run stops at Hello World with HelloWorld: simulated error (simulateError = Yes) ….
3. Switch to throwOnError = No and run again: the step is green, the robot console shows the ⚠️ line and result holds ERROR: simulated error ….
4. Add an If after Hello World with the condition result.StartsWith("ERROR:") - one branch handles the error, the other one uses the greeting. Set simulateError = No to see the second branch.
5. Clear the output variable: with simulateError = Yes the run stops for both values of throwOnError.

Dependencies

Add other NuGet packages with a normal <PackageReference>; the Package Manager installs them together with the plugin and checks version conflicts with other plugins. Packages Sophona Studio already contains (the .NET runtime, the connector and its dependencies) are not copied - use the versions the Studio has or older ones.

Publishing on nuget.org

dotnet nuget push bin\Release\SophonaPluginTemplate.1.0.0.nupkg -k <api key> -s https://api.nuget.org/v3/index.json

The Browse tab lists packages owned by the nuget.org account set in packageManager:pluginOwner (default RobotForce). Keep the sophona-plugin tag. A version on nuget.org cannot be replaced - publish a new one.

A new plugin from this template

dotnet new install RobotForce.Sophona.Plugin.Template      # or: dotnet new install <path to this folder>
dotnet new sophona-plugin -n Acme.InvoiceNodes             # --IncludeTests false = without the test project

The name becomes the project, the namespace, the package id and the library name.