ConnectCloud Developers

Save the work settings (hr:work:manage)

PUT /api/hr/v1/work-entry-settings

Module: HR · operationId: setWorkEntrySettings · Tag: Work entries · Auth: access token (Authorization: Bearer <accessToken>)

Replaces only the work part of HR's module configuration, at its version (0 before anything was saved; stale: 409 version_conflict). Configured kinds and billing types each name exactly one default; configured billing types include one nonBillable (internal work).

Request body

application/json (required)

  • activityDefaults (object): Booking defaults per activity kind (call, meeting, remote_session, appointment) of the activity list; a kind without an entry books with HR's default kind and billing type, no minimum and no rounding.
  • billingTypes (array of object): How work is billed (Nach Aufwand, Pauschale, Kontingent, Nicht verrechenbar)
    • flags (array of string): Meaning for the code: the default type, nothing billed, a flat rate billed, a contract quota consumed
    • key (string): Stable key of the billing type
    • label (string): Display name
  • kinds (array of object): Kinds of work (Remote, Vor Ort, Intern, …)
    • flags (array of string): Meaning for the code: the default kind, travel time and km allowed, internal work
    • key (string): Stable key of the kind
    • label (string): Display name
  • rounding (object): How the seconds of a stopped stopwatch become minutes, once, when it stops. Manual entries, edits and an explicit endedAt are never rounded; the exact seconds stay in durationSeconds. Always returned; a save without it means nearest and 1.
    • direction (string): nearest rounds half up (one of up, down, nearest; default "nearest")
    • stepMinutes (integer): Rounds to a multiple of this many minutes (one of 1, 5, 10, 15, 30, 60; default 1)
  • selfApproval (boolean): Approvers may approve their own work
  • tax (number): Tax rate of hourly invoice lines (default 19)
  • trafficLight (object): The time traffic light: booked time as a share of the time worked or of the target
    • denominator (string): What it is compared with: time worked so far or the target of the day (one of worked, target)
    • greenAt (integer): Green from this percentage
    • numerator (string): What booked time counts (one of all, billable, nonBillable)
    • yellowAt (integer): Yellow from this percentage (else red)
  • unit (string): Unit of hourly invoice lines (default Std)
  • version (integer (int64)): The configuration's version; send it back on save

Example:

{
  "activityDefaults": {
    "call": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 60,
      "roundMinutes": 15,
      "timeKind": "remote"
    },
    "remote_session": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 120,
      "roundMinutes": 5,
      "timeKind": "remote"
    }
  },
  "billingTypes": [
    {
      "flags": [
        "default"
      ],
      "key": "hourly",
      "label": "Nach Aufwand"
    },
    {
      "flags": [
        "flatRate"
      ],
      "key": "flat",
      "label": "Pauschale"
    },
    {
      "flags": [
        "quota"
      ],
      "key": "quota",
      "label": "Kontingent"
    },
    {
      "flags": [
        "nonBillable"
      ],
      "key": "none",
      "label": "Nicht verrechenbar"
    }
  ],
  "kinds": [
    {
      "flags": [
        "internal"
      ],
      "key": "internal",
      "label": "Intern"
    },
    {
      "flags": [
        "default"
      ],
      "key": "remote",
      "label": "Remote"
    },
    {
      "flags": [
        "allowsTravel"
      ],
      "key": "onsite",
      "label": "Vor Ort"
    }
  ],
  "rounding": {
    "direction": "up",
    "stepMinutes": 5
  },
  "selfApproval": false,
  "tax": 19,
  "trafficLight": {
    "denominator": "worked",
    "greenAt": 80,
    "numerator": "all",
    "yellowAt": 50
  },
  "unit": "Std",
  "version": 3
}

Responses

  • 200 Saved (application/json)
  • 400 Error (application/json)
  • 409 Error (application/json)

Fields of the 200 answer:

  • activityDefaults (object): Booking defaults per activity kind (call, meeting, remote_session, appointment) of the activity list; a kind without an entry books with HR's default kind and billing type, no minimum and no rounding.
  • billingTypes (array of object): How work is billed (Nach Aufwand, Pauschale, Kontingent, Nicht verrechenbar)
    • flags (array of string): Meaning for the code: the default type, nothing billed, a flat rate billed, a contract quota consumed
    • key (string): Stable key of the billing type
    • label (string): Display name
  • kinds (array of object): Kinds of work (Remote, Vor Ort, Intern, …)
    • flags (array of string): Meaning for the code: the default kind, travel time and km allowed, internal work
    • key (string): Stable key of the kind
    • label (string): Display name
  • rounding (object): How the seconds of a stopped stopwatch become minutes, once, when it stops. Manual entries, edits and an explicit endedAt are never rounded; the exact seconds stay in durationSeconds. Always returned; a save without it means nearest and 1.
    • direction (string): nearest rounds half up (one of up, down, nearest; default "nearest")
    • stepMinutes (integer): Rounds to a multiple of this many minutes (one of 1, 5, 10, 15, 30, 60; default 1)
  • selfApproval (boolean): Approvers may approve their own work
  • tax (number): Tax rate of hourly invoice lines (default 19)
  • trafficLight (object): The time traffic light: booked time as a share of the time worked or of the target
    • denominator (string): What it is compared with: time worked so far or the target of the day (one of worked, target)
    • greenAt (integer): Green from this percentage
    • numerator (string): What booked time counts (one of all, billable, nonBillable)
    • yellowAt (integer): Yellow from this percentage (else red)
  • unit (string): Unit of hourly invoice lines (default Std)
  • version (integer (int64)): The configuration's version; send it back on save

Example 200 answer:

{
  "activityDefaults": {
    "call": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 60,
      "roundMinutes": 15,
      "timeKind": "remote"
    },
    "remote_session": {
      "billing": "",
      "minMinutes": 15,
      "minSeconds": 120,
      "roundMinutes": 5,
      "timeKind": "remote"
    }
  },
  "billingTypes": [
    {
      "flags": [
        "default"
      ],
      "key": "hourly",
      "label": "Nach Aufwand"
    },
    {
      "flags": [
        "flatRate"
      ],
      "key": "flat",
      "label": "Pauschale"
    },
    {
      "flags": [
        "quota"
      ],
      "key": "quota",
      "label": "Kontingent"
    },
    {
      "flags": [
        "nonBillable"
      ],
      "key": "none",
      "label": "Nicht verrechenbar"
    }
  ],
  "kinds": [
    {
      "flags": [
        "internal"
      ],
      "key": "internal",
      "label": "Intern"
    },
    {
      "flags": [
        "default"
      ],
      "key": "remote",
      "label": "Remote"
    },
    {
      "flags": [
        "allowsTravel"
      ],
      "key": "onsite",
      "label": "Vor Ort"
    }
  ],
  "rounding": {
    "direction": "up",
    "stepMinutes": 5
  },
  "selfApproval": false,
  "tax": 19,
  "trafficLight": {
    "denominator": "worked",
    "greenAt": 80,
    "numerator": "all",
    "yellowAt": 50
  },
  "unit": "Std",
  "version": 3
}

Example request

curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/work-entry-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"activityDefaults":{"call":{"billing":"","minMinutes":15,"minSeconds":60,"roundMinutes":15,"timeKind":"remote"},"remote_session":{"billing":"","minMinutes":15,"minSeconds":120,"roundMinutes":5,"timeKind":"remote"}},"billingTypes":[{"flags":["default"],"key":"hourly","label":"Nach Aufwand"},{"flags":["flatRate"],"key":"flat","label":"Pauschale"},{"flags":["quota"],"key":"quota","label":"Kontingent"},{"flags":["nonBillable"],"key":"none","label":"Nicht verrechenbar"}],"kinds":[{"flags":["internal"],"key":"internal","label":"Intern"},{"flags":["default"],"key":"remote","label":"Remote"},{"flags":["allowsTravel"],"key":"onsite","label":"Vor Ort"}],"rounding":{"direction":"up","stepMinutes":5},"selfApproval":false,"tax":19,"trafficLight":{"denominator":"worked","greenAt":80,"numerator":"all","yellowAt":50},"unit":"Std","version":3}'

View as Markdown · Interactive reference · OpenAPI