AlmondTill/G3N API

On this page

revokeTrainingCertificate

mutation · in the family Training

What it does

Withdraw a certificate with a reason — the person passes the course again to be certified anew.

Withdraw a certificate (valid → revoked, terminal) WITH a reason — required (1..256 characters), it rides the revision's cause; the requirement reads unmet until the person passes again. Requires the unrestricted capability + the training-manage right + the CURRENT revision.

What happens

Permanent for that certificate; the requirement reads as unmet until a new pass.

Who may call it

Capability area: Training — Courses, tests, certificates and the training rules of your team.

Arguments

NameTypeRequiredNotes
idID ID!yesThe id of the record.
revisionID ID!yesThe revision id you read on the record; the change is refused if an edit landed in the meantime.
reasonString String!yesNo further notes.

Returns

TrainingCertificate TrainingCertificate! — A TrainingCertificate (🎓 — THE TRAINING PROGRAM, THE WIRE): the platform's own record that a person passed a course — MINTED BY THE API at a passing submit, in the SAME transaction as the attempt's transition, NEVER by a client (no create op exists on the wire). The holder (userId), the course, the passing sitting (attemptId), the score and the pass mark, the issue instant and the course's content version (curriculumVersion). valid (live) → revoked (terminal; manage authority, a reason required) · valid → superseded (terminal; SYSTEM-ONLY — the person's next pass of the same course supersedes it and keeps it as history). expiresAt is null — 's refresh rule sets it. The by-id read answers the holder or the training-manage right; the listing is the manage right's (revoked drops from it, superseded stays as history; both stay point-readable). NOT searchable.

Example request

mutation ExampleRevokeTrainingCertificate($id: ID!, $revision: ID!, $reason: String!) {
  revokeTrainingCertificate(id: $id, revision: $revision, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    userId
    courseKey
    attemptId
    score
    passMark
    issuedAt
    curriculumVersion
    expiresAt
    refreshDue
  }
}

Variables:

{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "reason": "Correcting a miscount."
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "revokeTrainingCertificate": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TC-EXMP-0000-000F",
      "type": "TrainingCertificate",
      "caption": "Blue jeans",
      "status": "valid",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "userId": "01900000-0000-7000-8000-11f967df0000",
      "courseKey": "<course key>",
      "attemptId": "01900000-0000-7000-8000-ca1745530000",
      "score": 1,
      "passMark": 1,
      "issuedAt": "2027-01-31T00:00:00.000Z",
      "curriculumVersion": "<curriculum version>",
      "expiresAt": "2027-01-31T00:00:00.000Z",
      "refreshDue": true
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer