14.6Changes that wait for approval

Why a change can wait

In SYNERGY Management Gateway, approval is a control on machine credentials, not on people. A person working in the console is never queued. An API key, however, is always a machine credential, so every change the node makes is checked against the key's supervision level:

Under Guarded, everyday work runs straight away: creating and updating objects, enabling, disabling and unlocking accounts, password resets, moves, renames and adding members.

Some changes wait at every level, whatever the key's own:

• A change to an object Active Directory protects (adminCount=1 — members of Domain Admins and the other protected groups, and those groups themselves).
• A change inside, or into, a protected container that an administrator set on the connection.
• An operation an administrator has pinned to "always ask agents" — unless the key has Skip the always-ask wait turned on.
• Any change once the key has made more than a set number of destructive changes in one rolling hour (20 by default). This volume brake then holds everything the key does until its count falls back under the threshold.

A change that would wait and carries a password — for example resetting the password of a protected account, or any password reset by a Supervised key — is refused outright with 403 Agent.ApprovalImpossible, because a queued request would have to store the password in clear text.

Supervision levels, protected containers and pins are set by administrators and are explained in Chapter 10, Operation policies, attribute policies and agent supervision. Approving and rejecting is described in Chapter 9, Operations log, approvals and waiting operations.

Tip: An integration that must run unattended, such as an overnight leavers job that deletes accounts, needs its API key set to Act without asking. Only a person who may approve operations can choose that level, and it holds only while the key's owner may approve operations. Even then, protected objects still wait for a person.

What the gateway answers

When a change has to wait, the gateway does not carry it out. It records it as an operation in the WaitingToApprove state and answers 202 Accepted with a handle: the operation ID, its status, when the request expires, and a URL to poll. The object you asked to create does not exist yet, so the node cannot return it.

The On Approval Required option

The node has an Options collection with On Approval Required; it matters for operations that change the directory. It decides what the node does with that answer:

A queued change is never reported as a success. With Continue and Output Operation ID, the item that flows on is the approval handle, not { success: true }, so an IF node can branch on {{ $json.approvalRequired }}.

The approval handle does not say why the change is waiting. To find out, read the operation with Operation > Get By ID: its gateReason field explains the reason in plain text (for example "This agent asks before destructive and security changes."), and impactSummary, when present, says what the change would affect.

The Options collection is not offered on the Operation resource, whose operations never change the directory.

When Continue On Fail is on in the node settings and a request fails, the node emits an item with error (the message), errorCode (the gateway's error code, such as Operation.Disabled), httpCode, and — for a queued change — approvalRequired and operationId.

Waiting for the decision

The Wait for Approval operation of the Operation resource polls a queued operation until somebody decides it.

The wait ends when the operation leaves WaitingToApprove. The emitted item is the operation record plus four fields:

• status — Success, Failed, Rejected, Cancelled or Expired.
• approved — true only when the status is Success.
• decided — true when the status is final.
• expired — true when the approval window closed without a decision.

An approval request expires after its window closes (72 hours by default). Approvers no longer see an expired request, so nobody can decide it. Wait for Approval then reports status: "Expired" (or fails the item, with Fail on Rejection on), so the workflow can submit the change again rather than wait forever. A request the requester withdraws in the console ends as Cancelled.

The result block

When an operation has been carried out, its record contains a result block:

• entityId — the object's objectGUID. For a create, this is the new object.
• distinguishedName — the object's distinguished name.
• objectClass — its class.
• action — what was done, as a number: 1 for a create, 2 for an update, 3 for a delete (0 for anything else).

result is missing while the operation is waiting, and for operations that never reached the directory (rejected, cancelled, blocked or failed early). So when result is present, the change happened and you can use what it produced, for example {{ $json.result.entityId }} in the next node.

Get By ID returns the same record without waiting, if you prefer to poll on your own schedule. Get Waiting lists everything your key's owner still has waiting.