Skip to content

DHI.Services.Jobs.Executer — Internal Developer Guide

This utility posts a Job to a DHI Jobs API using bearer auth and a resilient HTTP policy. Ship it with CI/CD, operators, or other services when you need to enqueue work from scripts or containers.

What it does

  1. Parses CLI arguments (supports -, --, /, :, = and quotes)
  2. Fetches a bearer token from <urlAuth>/api/tokens
  3. POSTs the job to <url>/api/jobs/{connectionId} with a JSON body:
{
  "taskId": "My.Task.Id",
  "hostGroup": "prod",
  "priority": 1,
  "tag": "my-run",
  "parameters": { "Key": "Value" }
}
  1. Optionally writes the HTTP response JSON to a file
  2. Exits 0 on success, 1 otherwise

Installing

dotnet add package DHI.Services.Jobs.Executer

Place an appsettings.json next to the executable (see below) or rely on the defaults.

Command line

Required

  • -taskId <id> — the job’s task id
  • -connectionId <id> — the server-side connection id
  • -url <https://host:port/> — base URL for the Jobs API (trailing / okay; tool adds one)
  • -username <user>
  • -password <pass>
  • -parametersFileName <path> — JSON file with job parameters (see “Parameters”)

Warning

Current behavior: -parametersFileName is required even if you also pass -parameters. If you want to use only -parameters, provide a small empty JSON file (e.g., {}) and point -parametersFileName at it. (The help text says “ignored,” but the code throws if the file is missing.)

  • -urlAuth <https://auth-host:port/> — base URL for auth; if auth shares the same base as -url, pass the same URL here. (The tool attempts to call <urlAuth>api/tokens.)

Optional

  • -hostGroup <name> — force execution on a host group
  • -priority <int> — lower is higher priority (e.g., 1)
  • -tag <text> — annotate the job
  • -parameters "<k1>:<v1>;<k2>:<v2>" — quick overrides (see note above)
  • -responseFileName <path> — save the JSON API response

Examples

Windows (PowerShell)

.\DHI.Services.Jobs.Executer.exe `
  -username $env:JOB_USER `
  -password $env:JOB_PASS `
  -url https://jobs.example.local/ `
  -urlAuth https://auth.example.local/ `
  -connectionId wf-job `
  -taskId My.Workflow.Run `
  -hostGroup prod `
  -priority 1 `
  -tag nightly `
  -parametersFileName params.json `
  -parameters "Region:EU;DryRun:false" `
  -responseFileName last-response.json

Linux / macOS (bash)

./DHI.Services.Jobs.Executer \
  -username "$JOB_USER" \
  -password "$JOB_PASS" \
  -url https://jobs.example.local/ \
  -urlAuth https://auth.example.local/ \
  -connectionId wf-job \
  -taskId My.Workflow.Run \
  -hostGroup prod \
  -priority 1 \
  -tag nightly \
  -parametersFileName params.json

Parameters

  • -parametersFileName points to a JSON file that deserializes into Dictionary<string, object>, e.g.:

    {
    "InputPath": "/data/in",
    "OutputPath": "/data/out",
    "Iterations": 3,
    "Verbose": true
}

  • -parameters (inline) supplies key:value pairs separated by ;. Values are strings; the tool will send them as strings unless the file already set a typed value.

Merge rule: File is read first. If -parameters is also provided, the inline replaces the entire set (not a merge).

Authentication

  • The tool POSTs to POST <urlAuth>api/tokens with:

    { "Id": "<username>", "Password": "<password>" }

  • It expects a response shaped like:

    { "accessToken": { "token": "<jwt>" } }

  • The token is then used as Authorization: Bearer <token> for the Jobs API POST.

VariablesOverride.json

If present in the working directory, this file overrides CLI credentials:

{
  "AuthUserName": "ci-bot",
  "AuthPassword": "s3cr3t",
  "UrlAuth": "https://auth.example.local/"
}

Keys:

  • AuthUserName → overrides -username
  • AuthPassword → overrides -password
  • UrlAuth → overrides -urlAuth

Resilience & logging

HTTP retry policy

  • Retries: 5
  • Triggers on: HttpRequestException, TaskCanceledException, or any non-2xx response
  • Backoff: jittered exponential, roughly Random(50..500ms) * 2^retry
  • Fallback: after retries, returns a synthetic 403 with text message (so callers can handle uniformly)

Logging

  • Configured via appsettings.json in the executable folder:

    {
    "LoggerType": "DHI.Services.Notifications.SimpleLogger, DHI.Services",
    "LoggerConnectionString": "[Path]DHI.Services.Jobs.Executer.log"
}

  • [Path] is replaced with the executable folder. If LoggerType cannot be created, it falls back to SimpleLogger.

Exit codes

  • 0 — job successfully posted (2xx response)
  • 1 — any failure (missing args, auth failure, non-2xx after retries, exceptions)

Notes

  • Always supply -urlAuth (even if same as -url) to avoid relative-URL issues when fetching tokens.
  • The command-line parser is flexible with -, --, / and quoting (e.g., -tag "a b" or -tag:'a b').
  • If you must run with no parameters, create an empty file {} and pass its path to -parametersFileName.

Programmatic use

If you embed parts of the package:

  • JobDto is the serialized body.

  • HttpFailureRetryPolicy wraps an HttpClient call:

    var retry = new HttpFailureRetryPolicy(logger);
var rsp = await retry.ExecuteAsync(() => client.PostAsync(url, content));

  • CommandLineParser maps args like -k v, --k=v, /k:"v" to a case-insensitive dictionary (this["k"]).