Video chapters
- AppEngine Workflow, Handling and Approvals
- Definition, task and source record
- Connect an organization staff session
- Start with the built-in action
- Configure stages and collection ownership
- Choose the effective workflow
- Start a task and read its position
- Advance, supply required input and verify
- Assignment, notes and transition history
- Claim a record and leave an outcome
- SLA timers and escalation
- Build a board and read its measurements
- Archive, restore, restart and cancel
- A decision is more than a board move
- Record approved and rejected outcomes
- Request access and follow the answer
- Inspect the same workflow in Studio
- Connect the action to its saved outcome
Written guide
Companion source code
Get the course source code on GitHub. The folder includes the supplied examples and setup instructions. Keep credentials in your own environment; use the maintained API reference when adapting recorded request examples.
A developer course covering process definitions, business actions, record-linked tasks, required stage inputs, assignment, handling, timers, lifecycle controls and decisions. The demonstrations use isolated training records; the API concepts apply to your own AppEngine application.
Video ready for review · 11:37 · 18 chapters · 1440p30.
Watch the review video · Download complete requests and observed responses
Before you start
Use your organization's AppEngine endpoint and organization identifier. Obtain a staff token through POST /profile/user/signin, with the orgid header and your staff email/password in JSON. Keep the returned token private. Subsequent requests use the same organization and Authorization: Bearer YOUR_STAFF_TOKEN. The Database & Repository APIs course, chapter 2 demonstrates staff sign-in; the customer session in API Foundations is a different actor. Your account needs access to the workflow, record and approval operations you intend to use.
The examples use workflow_lab_1010, a new collection with title, status and result fields. Replace this with your own unique training collection name and substitute every returned ID. Keep workflow IDs, source record IDs and task IDs distinct. All responses shown were observed in a controlled local training deployment. Deployment URLs and credentials are not exposed. Outbound email was disabled; no real access grants or publications were made.
The complete JSON examples are in the download. On-screen selected fields illustrate the current explanation, and are not always a complete request body. Do not copy an excerpt as a full workflow definition.
1. AppEngine Workflow, Handling and Approvals
Your application can show where a record stands, who is working on it, and which decision it is waiting for, without building three separate tracking systems. We'll start with the work AppEngine already handles, then configure a small workflow, move a real record through it, enforce an input, and inspect the saved result. We'll also claim work, manage timers and history, and record both an approval and a rejection.
2. Definition, task and source record
A workflow definition describes the process. A task is one record travelling through that process. Its owner points back to the source record, so your application can show a ticket or custom record beside its current stage. Handling answers a different question: who has taken responsibility for this record right now? Assignment can name several people; handling records the person who actually took it. An approval is a decision with a saved outcome. Those pieces work together, but changing a status field directly is not the same as running their actions.
Concept illustration of the mapped collection, not an application screenshot.
3. Connect an organization staff session
Use your AppEngine API address and organization ID. These are staff operations. The Database and Repository course shows the staff sign-in procedure; its second chapter is linked in the companion. Here is the same request: send the staff email and password to profile user signin with the organization header. Keep the returned token private. Subsequent requests send that token as a bearer credential alongside orgid. The examples show placeholders, not reusable credentials. A customer sign-in token is not a replacement for the staff session used to manage this workflow.
Concept illustration: the organization and staff session belong together.
Selected fields from the verified request demonstration. Complete payloads are in the download.
4. Start with the built-in action
For a ticket, start with the ticket API. Creating this ticket also creates its workflow task. The returned record ID is the value used in the next request; the ticket's name is its human-readable number. The ticket workflow endpoint shows its stage and assigned people. Resolving it through the ticket status action moves the associated workflow and saves the resolution. That is why a direct database edit of status is insufficient. Use the business action when AppEngine provides it; use a custom workflow when your own record needs a process.
Selected fields from the verified request demonstration. Complete payloads are in the download.
5. Configure stages and collection ownership
Our custom collection has a title and status. Its Enable Workflow switch is on; the complete collection request is included in the companion. Now create the workflow definition. Enabled turns this process on. Auto Fire is false because this example starts records explicitly. Collections lists the datatype whose state and status this workflow may update. Stage zero receives the work, stage one reviews it, and stage two completes it. Each stage has its own model status. Reviewing also requires a result before the task can move forward. The saved definition has an ID; keep that ID for the fire request.
Set up the full definition
- Create the collection using
05-create-collection/request.json;enableWorkflowis true and the schema requires a title. - POST the complete
06-create-definition/request.jsonbody to/workflow/definition. Substitute your collection and staff assignment email. - Keep
enabled: true,autoFire: false, and the collection incollections. Stage IDs are 0, 1, 2. Received starts new; Reviewing maps to inprogress; Completed ends done. - Reviewing has a required string input named
result. The complete file includes its label, assignments and timer options. Empty notification templates make this an isolated process. - Read the definition by its returned ID and compare the saved stages. A returned ID proves creation; readback establishes what was saved.
Selected fields from the verified request demonstration. Complete payloads are in the download.
6. Choose the effective workflow
The workflow for endpoint explains which definition applies to a datatype and why. Here it finds our review workflow because the definition lists this collection. A collection can also select a default workflow, and an explicit workflow ID selects the intended process for a particular start. The collection switch and the workflow's enabled state still matter. For a shipped process, from template creates the organization's definition when needed and returns the existing one on a repeat. It does not mean you need to reconstruct the built-in stages by hand.
Selected fields from the verified request demonstration. Complete payloads are in the download.
7. Start a task and read its position
Create the source record first. Then send its datatype and ID, the workflow ID, and a readable title to workflow fire. The response contains both the new task and its source reference. Keep the task ID separately from the record ID: task actions use the former, while record and handling routes use the latter. Position returns the current stage, assignments, clock and history for a record. Your application can use this response to display the process without rebuilding its interpretation of every stage.
Connect the source and task
Create a source record with the custom datatype. Use its returned ID with POST /workflow/fire, passing datatype, id and the explicit workflowId. Save the returned task ID separately. Query the record's workflow position to see stage, task status, assignment and deadline. Since two demonstration definitions eventually share the collection, an explicit workflow ID avoids an ambiguous choice.
Selected fields from the verified request demonstration. Complete payloads are in the download.
8. Advance, supply required input and verify
Advance moves this task from Received to Reviewing. Another advance is refused because Reviewing requires a result. The response names the missing field and the stage; the record has not silently finished. Send inputs with result, then advance again. Now stage two is current, status is done, and completedAt is set. The result is stored on the task. Reading the source record confirms its status became done too, because this definition owns the collection. Required input belongs to the stage you are leaving, not the stage you are entering.
Advance, direct movement and completion
advance moves to the next numbered stage. move-to/:stageId targets a specified stage. complete selects an end stage. These are different actions. Forward movement checks required inputs on the current stage; do not assume jumping to an end stage visits every intermediate stage or validates their inputs. This course proves both an input refusal from Reviewing and direct completion of a separate task from Received.
- Advance the main task once to Reviewing.
- Advance with an empty body. Expect HTTP 422 with
reason: inputs-required, missingresult, and stage Reviewing. - Repeat with
{"inputs":{"result":"Connection checked successfully"}}. - Read the task's done status, completion time and saved inputs. Then read the source record with
/repository/get/{datatype}/{id}and inspect its mirrored status.
Stage inputs are saved on the task. They do not automatically become every similarly named source field. Source status/state mirroring depends on the workflow owning that collection.
Selected fields from the verified request demonstration. Complete payloads are in the download.
9. Assignment, notes and transition history
Use reassign with an array of staff sign-in emails to change who the task is assigned to. A note is separate: it is stored as a comment, so it does not become a false stage transition. History records the stages the task left, when it left them, and any recorded actor. This direct completion has no actor in its history. Read the task or position alongside history to see the current stage as well. For a direct move use move to with the stage ID; advance follows the next numeric stage. Keep stage IDs ordered and stable when designing a process.
The assignment demonstration uses a separate completed task, named Completed assignment example. It is not the earlier task moving backwards. Reassign receives an array of staff email addresses. Add a note independently. History lists departed stages with time and any recorded actor; the task supplies its current stage. Reassigning or commenting does not itself undo the completed outcome.
Selected fields from the verified request demonstration. Complete payloads are in the download.
10. Claim a record and leave an outcome
Handling uses the source datatype and record ID. Take claims this record for the signed-in person. Repeating take as that same person returns taken true again. When the work is finished, send done with an outcome; the saved handling tells the next person what happened. Release makes it available again. No action closes handling with a reason when no work is needed. These calls record responsibility. They do not themselves send a reply, issue a refund, or replace the business action that performs the work.
Use the source datatype and source record ID for handling operations. take records who took it; done saves an outcome; release returns handling to open; no-action closes handling with a reason. Handling is not the workflow task's assignment list. Confirm the returned handling state after each operation.
Selected fields from the verified request demonstration. Complete payloads are in the download.
11. SLA timers and escalation
A stage can define escalation tiers. Our first tier gives Received sixty minutes; the next gives it another two-hour window. The SLA endpoint returns the due date, tier and remaining time. Snooze adds minutes to the existing due date, so adding thirty minutes does not necessarily make overdue work current. Escalate now applies the next tier and returns true when it runs. Here the tier becomes one and the due date changes. Escalation can add assignees and notify through configured templates. This example verifies the timer and tier; it does not claim a delivered message.
Selected fields from the verified request demonstration. Complete payloads are in the download.
12. Build a board and read its measurements
The task list accepts workflow, stage, status, assignee and source-record filters. Page and page size make the result usable in a table; q searches the task text. By default the board includes active tasks and recently completed decisions, while archived records stay out. Wait-time analytics describe the observed transitions and completed samples. This training run has only one completed sample, so its very short timings are not a prediction for your business. The task estimate is useful only with enough representative history behind it.
Selected fields from the verified request demonstration. Complete payloads are in the download.
13. Archive, restore, restart and cancel
Archiving a task removes it from the default board while preserving its outcome. Include archived shows it again, and unarchive returns it to the normal view. Restart uses the source datatype and ID to return that record's tasks to stage zero. Inspect its position afterward; this run returned to Received but did not re-establish a due date. Cancel records a cancelled outcome. Archiving the whole definition is different: it stops new work entering that process. The fire request is refused while it is archived, and restoring the definition makes it available again.
Archive hides a task from normal results while preserving its completed data status. Include archived results to retrieve it, and unarchive to restore its visibility. Cancel records a canceled outcome. Restart addresses the source record and returns its task to the starting stage. In the observed restart, dueDate became null even though the original start had timers: check SLA after restart rather than assuming the old deadline was restored.
Archiving a definition prevents new fire operations for that process. It is separate from archiving a single task. Restore the definition and read enabled/status before using it again.
Selected fields from the verified request demonstration. Complete payloads are in the download.
14. A decision is more than a board move
A normal workflow asks where the work should go next. A decision asks whether a requested outcome is allowed. Our decision definition has Waiting, Approved and Rejected. The approval endpoint records that decision and moves the task to the matching stage. On an access request, approval also applies the specified grant. On a publishing request, it performs publication. Moving one of those tasks to an end column directly would skip the effect, so AppEngine refuses that shortcut. Keep the decision and its effect together.
15. Record approved and rejected outcomes
This decision workflow is enabled, starts explicitly, and assigns Waiting to the staff account performing the review. Fire a source record into it, then call approval task approve with the task ID and a note. The response says approve and the task status is approved. Reading the source record confirms that outcome there too. A second record follows the rejection route: reject stores a rejected outcome instead. These are real decisions on our own records. They neither grant a role nor publish content; those effects belong to the corresponding request types.
The controlled decision workflow contains Waiting, Approved and Rejected. The approve call moved one disposable record to approved; the reject call moved a separate record to rejected. Both outcomes were read back. These generic decisions did not grant access or publish content. An assigned or otherwise authorized decision actor is still required.
Selected fields from the verified request demonstration. Complete payloads are in the download.
16. Request access and follow the answer
An access request starts with approval ask: identify the screen, application and reason. The response returns a request ID, task ID and the people it waits on. Asking again while it is pending returns already pending with the same request. The requester cannot decide their own access request; that attempt returns own request. Completing its task through the generic workflow route is refused too. For this demonstration, the requester cancels the ask and the record becomes cancelled. An actual access approval must come from a permitted reviewer with the existing role or group to grant; the companion shows that separate contract.
The course requests access only to the isolated dummy screen /course-training-only. Repeating the request returns the pending request rather than a duplicate. The requester's own decision receives 403. Trying the generic completion shortcut receives 409 with decide-through-approvals. Canceling the request yields cancelled status. No access was granted. Do not substitute this limited test for a successful end-to-end access grant demonstration.
Selected fields from the verified request demonstration. Complete payloads are in the download.
17. Inspect the same workflow in Studio
In Workflow Center, select None, then choose API Record Review. Open Completed assignment example. Its detail shows Completed, and History separates Left Received from Now at Completed. Close the drawer, select None, and choose API Record Decision. The same approved and rejected tasks appear in their matching columns, with the decision notes visible.
Actual training application capture. The camera moves into the drawer for readable history.
18. Connect the action to its saved outcome
You now have the core pieces for a workflow-aware application: a definition, a source record, a task, a handling outcome and a recorded decision. Choose the built-in business action when it exists, use explicit workflow actions for your own process, and show the saved result after every transition. The companion contains complete requests, the collection and definition payloads, and links to the staff authentication and repository lessons. Use the chapter links when you need to revisit one operation.
Access approval contract — reference, not executed
A permitted reviewer, distinct from the requester, sends POST /approval/task/{TASK_ID}/approve with the existing role or group selected for the intended access. These fields are source-verified; this request was not executed in the course.
{
"note": "Reviewed the requested access",
"grant": {
"via": "group",
"name": "YOUR_EXISTING_GROUP_NAME"
}
}grant.via accepts role or group. grant.name identifies the existing selection; for the role route replace via with role and use the intended permitted role name. A missing grant returns grant-required, an invalid via/group returns grant-invalid, and restricted grants are refused. Do not copy a role merely to make a request succeed. Read the returned decision/granted effect, the access-request record and the requester's resulting access before calling a real approval complete. Reject uses the corresponding /reject route and a note, without a grant. The generic workflow complete route is not a substitute.
Empty successful responses
Restart returned HTTP201 with an empty body in the observed run. Read the HTTP status, then parse JSON only when response text/content is present. The downloadable clients show this guard. Follow restart with the position readback; empty content does not establish its resulting stage by itself.
Advanced reference and alternatives
These controls extend the demonstrated core. Inspect the current contract and rehearse the intended effect in your own controlled deployment before connecting a live business operation.
| Capability | Use and boundary |
|---|---|
| Definition edit/delete/template | Edit a saved definition deliberately; deleting is different from archiving. Template creation can return an existing definition. Read back the returned definition. |
| Stage assignment rules | Static assignTo and computed rules supply task responsibility. Confirm the resulting people; an email string alone does not prove delivery. |
| All-approvers mode | A decision can collect individual answers before reaching a terminal stage. The video proves single-actor custom decisions, not every multi-person policy. |
| Approval tray and history | Read pending work and past decisions separately. Filter for the relevant actor/process; inspect the actual request payload before deciding. |
| Approval reassignment/escalation | These change responsibility or attention for the approval task. They are not the same as escalating a normal workflow SLA tier. |
| Request cancellation and notices | Cancel an unwanted request through its request operation. Reading/dismissing a notice does not approve the underlying request. |
| Access and publication effects | These approval kinds perform real authorization or publication work. They were explained from the current contract; successful grants/publication were not performed in this training fixture. |
| Notifications | Stage and escalation templates may send notifications when configured. Outbound delivery was disabled here, so no external delivery is claimed. |
| Timer processing | SLA read, snooze and one task escalation were demonstrated. No global escalation scan was run against unrelated tasks. |
| Analytics | Rapid disposable examples produce tiny millisecond timings. They demonstrate response shape, not a useful production forecast. |
Verification and application findings
The companion contains 75 sanitized request/response pairs, including configuration, transitions, expected refusals and final readbacks. An HTTP success alone is not the complete proof: inspect task position, history and the source record where appropriate. The restart deadline behavior is an observed application finding. The failed /repository/one operator attempts and an incorrectly named ticket assignment payload were corrected and excluded from the teaching examples; they are not product defects.
No application source was changed for this course. No privileged credential was created. The course keeps current observed behavior distinct from advanced configuration references.