Reads or sets which sync group a job belongs to, and which parts of it (steps/name, security, schedules) opt into sync. As with the group itself, setting this today only records the intent -- see the caveat in Manage Job Sync Groups about propagation not being built yet.

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

  1. Authenticate to the API.
  2. Get the job's id (from Get a Job by Name) and the sync group's id (from Manage Job Sync Groups).
  3. Read or write the job's sync config.

The calls

GET /api/jobs/{jobId}/sync
PUT /api/jobs/{jobId}/sync

Permission needed: Job.View to read, Job.Edit to write.

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 job's id and the sync group's id.
var jobId = 214;
var syncGroupId = Guid.Parse("8f1b2c3d-4e5f-6789-a0b1-c2d3e4f56789");

// Step 3: Read the current config.
var current = await client.GetFromJsonAsync<JobSyncConfig>($"/api/jobs/{jobId}/sync", jsonOptions);
Console.WriteLine($"Currently in group: {current!.SyncGroupId}");

// Step 3: Opt the job into the group, syncing its steps/name and schedules but not security.
var update = new SetJobSyncConfigRequest(SyncGroupId: syncGroupId, SyncRoleCode: 1, SyncStepsAndName: true, SyncSecurity: false, SyncSchedules: true);
var response = await client.PutAsJsonAsync($"/api/jobs/{jobId}/sync", update, jsonOptions);
response.EnsureSuccessStatusCode();
Console.WriteLine("Updated.");

record JobSyncConfig(Guid? SyncGroupId, byte? SyncRoleCode, bool SyncStepsAndName, bool SyncSecurity, bool SyncSchedules, Guid? SyncJobKey);
record SetJobSyncConfigRequest(Guid? SyncGroupId, byte? SyncRoleCode, bool SyncStepsAndName, bool SyncSecurity, bool SyncSchedules);

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 job's id and the sync group's id.
$jobId = 214
$syncGroupId = "8f1b2c3d-4e5f-6789-a0b1-c2d3e4f56789"

# Step 3: Read the current config. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$current = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$jobId/sync" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Currently in group: $($current.syncGroupId)"

# Step 3: Opt the job into the group, syncing its steps/name and schedules but not security.
$update = @{ SyncGroupId = $syncGroupId; SyncRoleCode = 1; SyncStepsAndName = $true; SyncSecurity = $false; SyncSchedules = $true } | ConvertTo-Json
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$jobId/sync" `
    -Method Put -Body $update -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Updated."

What you get back

GET -- 200 OK:

{ "syncGroupId": "8f1b2c3d-4e5f-6789-a0b1-c2d3e4f56789", "syncRoleCode": 1, "syncStepsAndName": true, "syncSecurity": false, "syncSchedules": true, "syncJobKey": "a1b2c3d4-..." }

syncJobKey is server-generated and read-only -- it isn't part of the PUT body.

PUT -- 204 No Content -- no body.

Codes this call can return

See API Response Codes for what each one means in general. For these calls:

  • 200 -- the config.
  • 204 -- updated.
  • 400 -- (PUT) a sync option (SyncRoleCode, SyncStepsAndName, SyncSecurity, or SyncSchedules) was set without also picking a SyncGroupId.
  • 403 -- you don't have Job.View/Job.Edit on this job.
  • 404 -- (GET) no job exists with that id.

What gets audited

The PUT is recorded as Job / Alter Job Sync Config, with the full request in the after-state. The GET isn't audited.

See also: Manage Job Sync Groups, Get a Job.