Custom Workflow Steps

Mesh workflows ship with steps for group membership, attributes, email and webhooks, plus a Run PowerShell script step for the common “run my script” case. That last step is delivered as a step package, the same kind of package you build here. When none of those fit, you build your own step with the Step SDK: a .NET class library that you sign and drop into a folder on the Admin API host. The console then shows your step in the designer palette, draws its form, stores its secrets and records its outputs exactly as it does for a shipped step.

This runbook takes you from an empty project to a custom step running in a workflow. Read it once end to end before starting, because the trust rules in Step 4 reject any package that is unsigned or from an unlisted publisher. The reason is shown in Settings → Workflows and in the event log.

If a script is all you need, you do not need the SDK. Use the Run PowerShell script step described in the Mesh workflows runbook, under Run a PowerShell script.

Before you start

• .NET 10 SDK on the machine where you build, and Visual Studio 2022 or later (or any editor that builds .NET projects).
• The Step SDK kit. It ships with IdentityMesh: open Settings → Workflows in the console and click Download Step SDK. The zip holds the SDK as a NuGet package, a nuget.config that restores from it, a sample step solution with its tests, the sample script and the licence. The SDK package restores from the zip’s own package folder, and dotnet test needs access to nuget.org for the test packages. Unzip it somewhere outside Program Files. If the button is missing, the server was installed from a release that predates the kit; upgrade it or ask your IdentityMesh contact for the zip.
• A code-signing certificate. The Admin API loads only Authenticode-signed step packages from publishers you list as trusted. An unsigned step is never loaded. The one exception is a development machine, covered under the heading “Development environments” below.
• Administrator access to the IdentityMesh console with permission to read Settings, and local administrator rights on the Admin API host to copy files, edit its configuration and restart the service.
• The Enterprise tier, because mesh workflows require it.

How a step works

A step is one class. It tells IdentityMesh four things:

The designer builds the form from the description, so there is no console work. The parameter kinds are text, multiline text, number, toggle, choice, URL, secret, group, attribute name, attribute assignments, expression, template, recipients, attribute list and script.

• Parameters. Each has a key, a label and a kind, and may be required, carry help text and a default, a minimum and maximum, a pattern, a list of options, or be shown only when another parameter has a given value (source=Inline).
• Outputs. Each has a key, a label and a kind (text, number, bool or json). Later steps read an output as steps.<key>.<output>, the same as for shipped steps. An output marked as a prefix stands for a family of values, such as result.MailboxGuid.
• Secrets. A parameter of kind secret is stored per step in the IdentityMesh secret store. It never appears in the saved workflow, in the run history or in the audit log. The step reads its own secret at run time, and any output or log line that contains it is masked.
• Timeout. Every custom step gets a timeout setting (in seconds) from IdentityMesh, between 5 and the step’s maximum (3600 by default). A step that does not return in time is stopped and retried. You do not declare it, and a step that declares its own timeoutSeconds is rejected.

The step runs inside the Admin API service, as the service account. It reaches IdentityMesh only through the context it is given: the run and object identity, the object’s attributes, secrets, the rules-language evaluator, the template renderer and a logger. There is no database access.

Step 1: Create the project

Start from the sample solution. It is the Run PowerShell script step under its own name, complete with its tests, small enough to read in one sitting.

1. Build and test the kit as downloaded first, so you know the toolchain works before you change anything:

   dotnet build
   dotnet test

2. Copy the kit folder and rename the sample project. Keep nuget.config and the packages folder beside your solution. They restore the SDK package:

   <PackageReference Include="IdentityMesh.Workflow.Sdk" Version="1.0.0" />

3. Set the assembly name so it matches the pattern the Admin API scans for:

   <AssemblyName>IdentityMesh.Steps.YourStep</AssemblyName>

   The Admin API loads only files named IdentityMesh.Steps.*.dll. A DLL with any other name is never looked at, and the step simply never appears.

4. Pick your own type key. The sample ships with the type key powershellSample and the assembly name IdentityMesh.Steps.Sample so that deploying it untouched never collides with the installed powershell step package. Replace both with names of your own.

5. Do not change the package’s build settings. The package keeps IdentityMesh.Workflow.Sdk.dll out of your build output on purpose. The reason is in Step 4.

Step 2: Implement the step

Derive from WorkflowStepBase and implement the type key, the description and the execute method. Override Validate to check settings when a workflow author saves.

using System.Text.Json;
using IdentityMesh.Workflow.Sdk;

public sealed class NotifyChatStep : WorkflowStepBase
{
    public override string Type => "notifyChat";

    public override StepDescriptor Describe() => new(
        Type, "Post to chat", "Posts a message to a chat room.", "Integrate", "webhook",
        [
            new StepParameterDeclaration("room", "Room", StepParameterKind.Text, Required: true,
                Help: "The room name, for example it-alerts."),
            new StepParameterDeclaration("message", "Message", StepParameterKind.Template, Required: true),
            new StepParameterDeclaration("token", "API token", StepParameterKind.Secret, Required: true),
        ],
        [
            new StepOutputDeclaration("messageId", "Message id", "text"),
        ]);

    public override IReadOnlyList<StepValidationError> Validate(JsonElement config, IStepValidationContext ctx)
    {
        var cfg = Config<ChatConfig>(config);
        return cfg.Room.StartsWith('#')
            ? [new StepValidationError("room", "Enter the room name without the leading #.")]
            : [];
    }

    public override async Task<StepResult> ExecuteAsync(IStepExecutionContext ctx, JsonElement config, CancellationToken ct)
    {
        var cfg = Config<ChatConfig>(config);
        var token = await ctx.GetSecretAsync("token", ct)
            ?? throw Fail("The API token has not been set on this step.");

        var text = ctx.RenderTemplate(cfg.Message);      // {{displayName}}, {{steps.x.y}}
        var id = await ChatClient.PostAsync(cfg.Room, text, token, ct);   // your own code

        return new StepResult($"Posted to {cfg.Room}.", new Dictionary<string, string?> { ["messageId"] = id });
    }
}

Four helpers on the base class and context cover most steps:

• Fail(message) returns a failure that retrying cannot fix, such as a missing setting or a refused credential. throw Fail("...") ends the run as Failed at once.
• Retry(message) returns a transient failure, such as a timeout or a 503 from the service you call. throw Retry("...") makes the run wait and try again on the normal schedule. Any other exception your code throws is treated as retryable.
• ctx.GetSecretAsync(key, ct) returns the value of a secret parameter, or nothing when none is set.
• ctx.Evaluate(expression) evaluates an expression in the same rules language as Set attributes, over the object, the workflow and trigger values and earlier steps’ outputs. A bad expression fails the step without a retry.

Rules that are easy to get wrong:

• Make the step safe to run twice. If the service restarts after your step did its work but before the result was saved, the step runs again.
• Honour the cancellation token. It is cancelled on timeout, on a lost lease and on service shutdown. A step that ignores it holds up the run.
• Never put a secret in an output. Outputs are visible to everyone who can read runs. IdentityMesh masks the secret values your step reads, but only exact matches.
• Keep outputs small. A step publishes at most 50 outputs, each cut at 500 characters, 32 KB in all.
• Declare each parameter key once, ignoring capitalisation.

IdentityMesh checks the declaration before it calls your Validate: required parameters (when visible), number ranges, choice options and patterns. A secret may not appear in the settings JSON, and unknown keys are rejected. You only need Validate for rules the declaration cannot express.

Step 3: Test it

The sample’s test project shows the pattern: hand-written stubs for the context, no service and no mocking library. Test the described form, each validation error, a successful run, and both failure kinds.

dotnet build
dotnet test

The output you deploy is the one DLL in your bin folder named IdentityMesh.Steps.YourStep.dll, plus any third-party libraries it needs. There must be no IdentityMesh.Workflow.Sdk.dll beside it. If there is, something changed the package’s build settings.

Step 4: Deploy

IdentityMesh loads a step package only if its publisher is on the Admin API’s trusted list. Sign first, trust second, copy third.

The Run PowerShell script step is a worked example of a deployed package. It was deployed this way: it sits in the Steps folder, it is signed, and it appears in the Step packages table. Look at its row in Settings → Workflows before you deploy your own, so you know what a healthy package looks like.

1. Sign the DLL with your code-signing certificate.

2. Open the Admin API’s configuration file:

   C:\Program Files\IdentityMesh\api\appsettings.json

   and add your certificate to the trusted publishers under Workflows:StepVerification. The common name is the certificate’s subject CN and the thumbprint is its SHA-1 thumbprint:

   "Workflows": {
     "StepVerification": {
       "RequireRevocationCheck": true,
       "AllowedPublishers": [
         { "SubjectCommonName": "Contoso Ltd", "Thumbprint": "<your certificate thumbprint>" }
       ]
     }
   }

   Keep any entry that is already there. It is the publisher of the PowerShell step package and the other shipped components. If the section already holds other settings, add the entry beside them.

3. Copy your DLL, and only the third-party libraries it needs, into the steps folder:

   C:\Program Files\IdentityMesh\api\Steps\

   Copy individual files. Do not mirror your whole bin folder, which is how the SDK DLL ends up there.

4. Restart the Admin API. Step packages are read once at start-up.

   sc stop IdentityMeshAdmin
   sc start IdentityMeshAdmin

5. Confirm it loaded. In the console open Settings → Workflows. The Step packages table lists every DLL in the folder with its version, publisher and a status of Loaded or Rejected. A rejected package shows the reason under the status. The same reason is written as an error to the IdentityMesh event log (Event Viewer, Applications and Services Logs → IdentityMesh, source IdentityMesh Admin API). Open a workflow in the designer: a loaded step appears in the Custom section of the palette, with the package name and version under it.

Never put IdentityMesh.Workflow.Sdk.dll in the Steps folder. The SDK is the contract between your step and the Admin API, and the Admin API already has its own copy. A second copy beside your step is loaded separately, your step’s interface becomes a different type from the Admin API’s, and the package is rejected as having loaded the contract twice. If a package you deployed is rejected for that reason, delete the extra file and restart.

Development environments

On a development or test machine you can skip the signature check, so you can try an unsigned build without a certificate. It works only when both of these are true:

• The IdentityMeshAdmin service runs with the environment variable ASPNETCORE_ENVIRONMENT set to Development.

• Workflows:StepVerification:SkipVerification is true in appsettings.Development.json, in the Admin API folder:

  "Workflows": { "StepVerification": { "SkipVerification": true } }

If either one is missing, packages are verified as usual. The setting is honoured only in the Development environment.

Warning: never use this in production. With the check skipped, the Admin API runs any DLL placed in the Steps folder, signed or not, with the service account’s rights. Production hosts must keep the service in its normal environment and sign every package.

Use the step in a workflow

1. Open Workflows and create or edit a workflow.
2. Drag your step from the Custom section of the palette onto the canvas. The properties panel shows the form you described.
3. Fill in the fields. Secret fields are stored when you save and shown only as a mask with a Change button. Change the timeout if the default of 300 seconds does not suit.
4. Use Validate to run your checks, then Save.
5. Use Run now against a test object. The run detail page lists the step’s outputs.

Upgrades

The IdentityMesh installer does not remove files it did not install, so your step stays in the Steps folder across upgrades. Two things can still require action:

• A new SDK version. Each step is stamped with the SDK version it was built against. A step built against a newer SDK than the Admin API carries is rejected with a message that names both versions. Upgrade the Admin API first, then rebuild your step. A step built against an older SDK keeps loading.
• An expired signing certificate. The signature is checked on every start, so re-sign and redeploy before the certificate expires, and add the new certificate’s thumbprint to the trusted publishers.

Replacement DLLs go in the same way: stop the service, copy the file over the old one, start the service.

Troubleshooting

A rejected package shows its reason in the Step packages table and in the event log. Fix the cause, then restart IdentityMeshAdmin.