Update a Step : MinionWare

Updates a step's fields -- the same full save the Console's own step editor does. There's also a narrower PATCH /api/job-steps/{jobStepId} that only touches name/type/command text, but this endpoint is the one to reach for since it covers everything: credential, target server, parent/pool, actions, and every step-type-specific setting (cursor, file operation, SSIS, Availability Group gate).

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

Authenticate to the API.
Get the step's id (from Get a Job's steps array, or List a Job's Steps).
Send the updated fields.
Only if the step belongs to a global job and this isn't the master: confirm severing it, and retry (same pattern as Rename a Job).

The call

PUT /api/job-steps/{jobStepId}/fields?confirmSever={true|false}

confirmSever is optional, defaults to false.

Permission needed: Job.Edit on this step.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Step 2: You already have the jobStepId (from Get a Job's steps array).
var jobStepId = 214;

// Step 3: Send the updated fields. Only the common ones are shown --
// leave step-type-specific fields (cursor/file-op/SSIS/AG-gate) at their
// defaults unless this step's StepTypeCode actually uses them.
var edit = new UpdateStepFieldsRequest(
    StepName: "Stage table 3 (retry-enabled)", StepTypeCode: 0, CommandText: "EXEC dbo.usp_LoadStage3 @Retries = 3",
    CredentialId: null, TargetServerId: null, ParentStepId: null, OnSuccessActionCode: 0, OnFailureActionCode: 0);

var response = await client.PutAsJsonAsync($"/api/job-steps/{jobStepId}/fields", edit, jsonOptions);

if (response.StatusCode == System.Net.HttpStatusCode.Conflict)
{
    Console.WriteLine("This step belongs to a global job managed elsewhere. Retrying with confirmSever=true.");
    response = await client.PutAsJsonAsync($"/api/job-steps/{jobStepId}/fields?confirmSever=true", edit, jsonOptions);
}

response.EnsureSuccessStatusCode();
Console.WriteLine("Updated.");

record UpdateStepFieldsRequest(string StepName, byte StepTypeCode, string CommandText,
    int? CredentialId, int? TargetServerId, int? ParentStepId, byte OnSuccessActionCode, byte OnFailureActionCode);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2: You already have the jobStepId (from Get a Job's steps array).
$jobStepId = 214

# Step 3: Send the updated fields. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$edit = @{
    StepName = "Stage table 3 (retry-enabled)"
    StepTypeCode = 0
    CommandText = "EXEC dbo.usp_LoadStage3 @Retries = 3"
    OnSuccessActionCode = 0
    OnFailureActionCode = 0
} | ConvertTo-Json

try {
    Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/job-steps/$jobStepId/fields" `
        -Method Put -Body $edit -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
    "Updated."
}
catch [Microsoft.PowerShell.Commands.HttpResponseException] {
    if ($_.Exception.Response.StatusCode -eq 409) {
        Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/job-steps/$jobStepId/fields?confirmSever=true" `
            -Method Put -Body $edit -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
        "Updated (detached from global tracking)."
    } else {
        throw
    }
}

What you get back

204 No Content on success -- no body.

Codes this call can return

See API Response Codes for what each one means in general. For this specific call:

204 -- updated.
400 -- CommandText contains a blacklisted phrase, or a step-type-specific field is missing something it requires (e.g. a cursor step without a database scope, an AG-gated step missing its AG fields).
403 -- you don't have Job.Edit on this step.
404 -- no step exists with that id.
409 -- this step belongs to a global job, this installation isn't the master, and confirmSever wasn't passed as true. Body: { "requiresSever": true, "message": "..." }.

Update a Step Print