Turns a normal job into a global job -- one shared out to other fleet members, who each get their own subscribed copy. This installation becomes the master (the one place edits are made and pushed out). This can't be undone through the API.

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 (by name or from the list).
  3. Request the promotion.

The call

POST /api/jobs/{jobId}/promote-to-global

Permission needed: Job.ManageGlobal on this job.

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: Get the job's id by name.
var jobName = Uri.EscapeDataString("Nightly ETL Load");
var job = await (await client.GetAsync($"/api/jobs/by-name/{jobName}")).Content.ReadFromJsonAsync<JobRef>(jsonOptions);

// Step 3: Request the promotion.
var response = await client.PostAsync($"/api/jobs/{job!.JobID}/promote-to-global", content: null);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<PromoteResult>(jsonOptions);
Console.WriteLine($"Promoted. Global definition id: {result!.GlobalJobDefinitionId}");

record JobRef(int JobID);
record PromoteResult(Guid GlobalJobDefinitionId);

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: Get the job's id by name. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$jobName = [Uri]::EscapeDataString("Nightly ETL Load")
$job = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/by-name/$jobName" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

# Step 3: Request the promotion.
$result = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$($job.jobID)/promote-to-global" `
    -Method Post -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Promoted. Global definition id: $($result.globalJobDefinitionId)"

What you get back

200 OK:

{ "globalJobDefinitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }

Codes this call can return

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

  • 200 -- promoted.
  • 400 -- the job is already global, or no Fleet is configured on this installation yet.
  • 403 -- you don't have Job.ManageGlobal on this job.
  • 404 -- no job exists with that id.

See also: Get a Job, Rename a Job / Change Its Description.