Add template approvers

POST /walk-creator/v1/template-approvers

Operation id: addTemplateApprovers

Description

Replaces Approvers for a walk template category.

Same product meaning as Fetch template approvers: the modern Approvers screen stores template reviewers of permit type REVIEWER only. This operation follows CategoryV2Service.addTemplateReviewers for the reviewer list and ignores authorize and approver permit data.

Behavior:

  • Each item is saved with permit_type = R and txn_category = C.
  • A request that includes any other permit type (C, A, AUTHORIZE, APPROVER) is rejected (E215).
  • Existing REVIEWER rows for the category are replaced. Authorize and Approver rows are not deleted.
  • Duplicate reviewer keys (category + profile + department + unit level) are stored once.
  • permit_sequence is assigned by the server from the remaining order.
  • The category permitConfig flag REVIEWER is set to Y when the saved list is not empty, and removed when approvers is []. AUTHORIZE and APPROVER flags are preserved.
  • Pass approvers as [] to clear Approvers.
  • unit_id is required and is kept exactly as supplied. The session unit does not replace it. An approver object that omits unit_id is stored with this request unit_id. An explicit unit on the object is kept.

Each object accepts snake_case or camelCase fields. profile_id or department_id is required. category_name is optional; when omitted the stored category name is used as entity_name.

Authentication: X-reflexis-csrf-token-X required. Category EDIT access is required.

Tags: WalkCreatorTemplateApprovers

Security

  • AuthTokenHeader (apiKey)
    • Session authentication token validated server-side against the user session store. Required on every request. Absence returns HTTP 400; invalid/expired token returns HTTP 401.

Responses

200 — Saved Approvers, in server-assigned sequence. Empty array when the list was cleared.

Content type: application/json

400 — Invalid or missing required request parameter.

Content type: application/json

401 — Missing or invalid X-reflexis-csrf-token-X session token.

Content type: application/json

403 — Category EDIT access denied (E202)

Content type: application/json

500 — Unexpected server-side error.

Content type: application/json

Request body

Required: Yes

application/x-www-form-urlencoded

Schema

PropertyTypeRequiredDescription
category_idstringYesWalk template category id.
model_typestringYesCategory model type. W for a walk category.
unit_idstringYesCaller unit id. Accepted as unit_id or unitId. Kept as supplied. The session unit does not replace it. Stored on approver rows that omit their own unit.
category_namestringNoOptional category display name stored on each permit row.
approversstringYesJSON array of Approver objects. Permit type is forced to REVIEWER (R). Do not send authorize or approver rows. [] clears the Approvers list.
{
  "type": "object",
  "required": [
    "category_id",
    "model_type",
    "unit_id",
    "approvers"
  ],
  "properties": {
    "category_id": {
      "type": "string",
      "description": "Walk template category id.",
      "example": "CAT_SAFETY"
    },
    "model_type": {
      "type": "string",
      "description": "Category model type. `W` for a walk category.",
      "example": "W"
    },
    "unit_id": {
      "type": "string",
      "description": "Caller unit id. Accepted as `unit_id` or `unitId`. Kept as supplied.\nThe session unit does not replace it.\nStored on approver rows that omit their own unit.\n",
      "example": "HQ"
    },
    "category_name": {
      "type": "string",
      "description": "Optional category display name stored on each permit row.",
      "example": "Safety"
    },
    "approvers": {
      "type": "string",
      "description": "JSON array of Approver objects. Permit type is forced to REVIEWER (`R`).\nDo not send authorize or approver rows. `[]` clears the Approvers list.\n",
      "example": "[{\"profile_id\":\"STORE_MGR\",\"department_id\":\"OPS\",\"unit_id\":\"HQ\",\"unit_level\":1,\"response_time\":\"1440M\",\"permit_desc\":\"{\\\"PROFILE-STORE_MGR\\\":\\\"Store Manager\\\"}\"}]"
    }
  }
}

Response models

200 — Saved Approvers, in server-assigned sequence. Empty array when the list was cleared.

Content type: application/json

Schema

PropertyTypeRequiredDescription
statusstringYes
template_approversarrayYes
{
  "type": "object",
  "required": [
    "status",
    "template_approvers"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "template_approvers": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One walk-category Approver. Stored as a template reviewer of permit type REVIEWER\n(`permit_type` = `R`, `txn_category` = `C`). Authorize (`C`) and Approver (`A`)\npermit rows are not part of this resource.\n",
        "required": [
          "txn_category",
          "permit_type",
          "entity_id",
          "permit_sequence",
          "model_type"
        ],
        "properties": {
          "domain_id": {
            "type": "integer"
          },
          "txn_category": {
            "type": "string",
            "description": "Creation transaction. Category Approvers are always `C`.",
            "enum": [
              "C"
            ]
          },
          "permit_type": {
            "type": "string",
            "description": "REVIEWER. This API never returns `C` (authorize) or `A` (approver).",
            "enum": [
              "R"
            ]
          },
          "entity_id": {
            "type": "string",
            "description": "Walk template category id."
          },
          "entity_name": {
            "type": "string",
            "description": "Walk template category name."
          },
          "permit_sequence": {
            "type": "integer",
            "description": "1-based order on the Approvers screen."
          },
          "user_id": {
            "type": "string"
          },
          "profile_id": {
            "type": "string"
          },
          "department_id": {
            "type": "string"
          },
          "unit_id": {
            "type": "string"
          },
          "unit_level": {
            "type": "integer"
          },
          "response_time": {
            "type": "string",
            "description": "Response window, for example `1440M`.",
            "example": "1440M"
          },
          "created_by": {
            "type": "string"
          },
          "creation_time": {
            "type": "integer",
            "format": "int64",
            "description": "UTC creation time in epoch milliseconds."
          },
          "permit_desc": {
            "type": "string",
            "description": "JSON string of display labels (profile, department, unit, org level)."
          },
          "model_type": {
            "type": "string",
            "description": "Category model type. `W` for a walk category.",
            "example": "W"
          }
        }
      }
    }
  }
}

400 — Invalid or missing required request parameter.

Content type: application/json

Schema

Error envelope shape depends on how the error is produced:

  • HTTP 200 — business or validation failure after the request is accepted: { "status": "ER", "error": "<string or JSON>" } (no errorCode).
  • HTTP 4xx/5xx — structured API error: { "status": "ER", "errorCode": "<code>", "response": "<localized message>" }.
PropertyTypeRequiredDescription
statusstringNo
errorCodestringNoStructured error code for HTTP 4xx/5xx responses.
responsestringNoHuman-readable message when errorCode is present (HTTP 4xx/5xx responses).
erroroneOfNoPayload for HTTP 200 error bodies (string, array, or object).
{
  "type": "object",
  "description": "Error envelope shape depends on how the error is produced:\n\n- **HTTP 200** — business or validation failure after the request is accepted:\n  `{ \"status\": \"ER\", \"error\": \"<string or JSON>\" }` (no `errorCode`).\n- **HTTP 4xx/5xx** — structured API error:\n  `{ \"status\": \"ER\", \"errorCode\": \"<code>\", \"response\": \"<localized message>\" }`.\n",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Structured error code for HTTP 4xx/5xx responses."
    },
    "response": {
      "type": "string",
      "description": "Human-readable message when `errorCode` is present (HTTP 4xx/5xx responses)."
    },
    "error": {
      "description": "Payload for HTTP 200 error bodies (string, array, or object).",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object"
        }
      ]
    }
  }
}

Example:

{
  "status": "ER",
  "errorCode": "E110",
  "response": "model_id is mandatory"
}

401 — Missing or invalid X-reflexis-csrf-token-X session token.

Content type: application/json

Schema

Error envelope shape depends on how the error is produced:

  • HTTP 200 — business or validation failure after the request is accepted: { "status": "ER", "error": "<string or JSON>" } (no errorCode).
  • HTTP 4xx/5xx — structured API error: { "status": "ER", "errorCode": "<code>", "response": "<localized message>" }.
PropertyTypeRequiredDescription
statusstringNo
errorCodestringNoStructured error code for HTTP 4xx/5xx responses.
responsestringNoHuman-readable message when errorCode is present (HTTP 4xx/5xx responses).
erroroneOfNoPayload for HTTP 200 error bodies (string, array, or object).
{
  "type": "object",
  "description": "Error envelope shape depends on how the error is produced:\n\n- **HTTP 200** — business or validation failure after the request is accepted:\n  `{ \"status\": \"ER\", \"error\": \"<string or JSON>\" }` (no `errorCode`).\n- **HTTP 4xx/5xx** — structured API error:\n  `{ \"status\": \"ER\", \"errorCode\": \"<code>\", \"response\": \"<localized message>\" }`.\n",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Structured error code for HTTP 4xx/5xx responses."
    },
    "response": {
      "type": "string",
      "description": "Human-readable message when `errorCode` is present (HTTP 4xx/5xx responses)."
    },
    "error": {
      "description": "Payload for HTTP 200 error bodies (string, array, or object).",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object"
        }
      ]
    }
  }
}

403 — Category EDIT access denied (E202)

Content type: application/json

Schema

Error envelope shape depends on how the error is produced:

  • HTTP 200 — business or validation failure after the request is accepted: { "status": "ER", "error": "<string or JSON>" } (no errorCode).
  • HTTP 4xx/5xx — structured API error: { "status": "ER", "errorCode": "<code>", "response": "<localized message>" }.
PropertyTypeRequiredDescription
statusstringNo
errorCodestringNoStructured error code for HTTP 4xx/5xx responses.
responsestringNoHuman-readable message when errorCode is present (HTTP 4xx/5xx responses).
erroroneOfNoPayload for HTTP 200 error bodies (string, array, or object).
{
  "type": "object",
  "description": "Error envelope shape depends on how the error is produced:\n\n- **HTTP 200** — business or validation failure after the request is accepted:\n  `{ \"status\": \"ER\", \"error\": \"<string or JSON>\" }` (no `errorCode`).\n- **HTTP 4xx/5xx** — structured API error:\n  `{ \"status\": \"ER\", \"errorCode\": \"<code>\", \"response\": \"<localized message>\" }`.\n",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Structured error code for HTTP 4xx/5xx responses."
    },
    "response": {
      "type": "string",
      "description": "Human-readable message when `errorCode` is present (HTTP 4xx/5xx responses)."
    },
    "error": {
      "description": "Payload for HTTP 200 error bodies (string, array, or object).",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object"
        }
      ]
    }
  }
}

500 — Unexpected server-side error.

Content type: application/json

Schema

Error envelope shape depends on how the error is produced:

  • HTTP 200 — business or validation failure after the request is accepted: { "status": "ER", "error": "<string or JSON>" } (no errorCode).
  • HTTP 4xx/5xx — structured API error: { "status": "ER", "errorCode": "<code>", "response": "<localized message>" }.
PropertyTypeRequiredDescription
statusstringNo
errorCodestringNoStructured error code for HTTP 4xx/5xx responses.
responsestringNoHuman-readable message when errorCode is present (HTTP 4xx/5xx responses).
erroroneOfNoPayload for HTTP 200 error bodies (string, array, or object).
{
  "type": "object",
  "description": "Error envelope shape depends on how the error is produced:\n\n- **HTTP 200** — business or validation failure after the request is accepted:\n  `{ \"status\": \"ER\", \"error\": \"<string or JSON>\" }` (no `errorCode`).\n- **HTTP 4xx/5xx** — structured API error:\n  `{ \"status\": \"ER\", \"errorCode\": \"<code>\", \"response\": \"<localized message>\" }`.\n",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Structured error code for HTTP 4xx/5xx responses."
    },
    "response": {
      "type": "string",
      "description": "Human-readable message when `errorCode` is present (HTTP 4xx/5xx responses)."
    },
    "error": {
      "description": "Payload for HTTP 200 error bodies (string, array, or object).",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object"
        }
      ]
    }
  }
}

Example:

{
  "status": "ER",
  "errorCode": "E500",
  "response": "Unexpected server error."
}