Asana Usage with Kiluth API
Department
Summary
How Kiluth uses Asana with the Kiluth API: OAuth, rule actions, and Evaluate Task. Defines Asana card rules (dependency chain, actionable title with Definition of Done, no PII) for consistent evaluation by the API and by people. Single reference for operators and RAG/Chatbot.
Table of Contents
Purpose
This document describes how Kiluth uses Asana with the Kiluth API: OAuth, rule action, and Evaluate Task. It states the Asana card rules used for evaluation (dependency chain, actionable title with Definition of Done) so that both the API and people can apply them consistently.
| Outcome |
|---|
| A single reference for Asana integration (setup, Evaluate Task behaviour, and card rules) for operators and for RAG/Chatbot. |
What the API Provides
- OAuth: Connect an Asana app to the API so it can act on behalf of users. Endpoints: GET
/v1/auth/asana, GET/v1/auth/asana/callback. - Rule action: The API exposes endpoints for Asana rule actions: form-metadata, form-submit, and run. When a rule runs, the API can evaluate the task and post a comment.
- Evaluate Task: The main automation. For a given task, the API fetches the task, its blocking dependencies and dependents; checks the dependency chain rule; evaluates title and Definition of Done using an LLM; then posts a comment with the result (e.g. Passed/Failed and optional note). This can be triggered by an Asana rule (POST to the run endpoint) or by calling POST
/v1/asana/rule-action/runwith the task GID.
Setup (Asana Developer App)
To use the API with Asana you must configure an app in Asana Developer (developer.asana.com):
| # | Step | Details |
|---|---|---|
| 1 | Redirect URIs | Add the API OAuth callback URL, e.g. https://your-api-domain/v1/auth/asana/callback. |
| 2 | Form action URLs | Point the rule action (form-metadata, form-submit, run) to your API base, e.g. https://your-api-domain/v1/asana/rule-action/form-metadata, .../form-submit, .../run. |
| 3 | Environment variables | The API needs ASANA_CLIENT_ID, ASANA_CLIENT_SECRET, ASANA_REDIRECT_URI, and ASANA_OAUTH_SUCCESS_REDIRECT. After OAuth, the API stores the token and uses it for Evaluate Task and other Asana API calls. |
Evaluate Task: What It Does
When Evaluate Task runs (e.g. from a rule or POST /v1/asana/rule-action/run):
| # | Step | Details |
|---|---|---|
| 1 | Fetch task data | The API gets the task and its blocking dependencies and dependents from the Asana API. |
| 2 | Dependency chain rule | It checks that from this task, following blocking (what does this task block?) eventually leads to the project card on the Projects board. For billable project tasks, the dependency chain must link back to the same project’s card on the Projects board. If the chain does not lead there, the task fails this criterion. |
| 3 | Title and Definition of Done | The API uses an LLM (completion with JSON output) to evaluate whether the task title is actionable and implies a Definition of Done (or that DoD is clear from description/checklist). Noun-style or vague titles fail. |
| 4 | Comment | The API posts a comment to the task with an evaluation table (Passed/Failed per criterion) and an optional note. Optionally it can prepend a prefix to the task title (e.g. [✅] or [❌]) and create a follow-up task on failure; this is controlled by environment variables. |
Asana Card Rules (for Evaluation and for People)
These are the rules the API and reviewers use to evaluate Asana cards.
Dependency chain rule
From any project task card (e.g. billable work in Technology), following blocking (what does this task block?) must eventually lead to the project card on the Projects board. Example: Develop a website → (blocking) → Test the website → (blocking) → Deploy the website → (blocking) → Website Project (project card on Projects board). If the chain does not reach the project card on the Projects board, the card is not set up correctly.
Exception: Project cards on the Projects board themselves are containers; they do not need to satisfy the dependency chain in the same way.
Actionable title with Definition of Done
The card title must describe a task (verb or outcome), not a noun or topic. “Done” must be clear from the title or from the Definition of Done in the description or checklist.
| Wrong | Right |
|---|---|
| ”UI Feedback” (noun; no clear action) | “Revise UI design based on client feedback” (actionable; implies DoD) |
| “Meeting notes” (topic only) | “Publish meeting notes to the shared drive and link in Asana” (actionable; implies DoD) |
Exception: Project cards on the Projects board do not need to follow the actionable-title rule in the same way.
No lead/contact PII in card content
Do not put lead or client PII (e.g. full names, email addresses, phone numbers) in Asana task descriptions or titles. Such data must live in secure, access-controlled storage (e.g. CRM); in Asana use only links to the lead or record and, if needed, a short redacted summary (e.g. “Contact: see linked record”). This applies to any card that might reference leads or client contacts. See Privacy & Data Handling Guideline for the full rule.
Expectation: reject incorrectly used cards
Everyone at Kiluth should reject (or not accept) tasks that do not meet these criteria. Do not start work on a card that fails evaluation; ask for the card to be adjusted first.
Evaluation Criteria Table (for Comments and Self-Check)
When evaluating a card (manually or via the API), use this table in comments or for self-check:
| Criteria | Description |
|---|---|
| Title and DoD | Card title must be actionable and can imply Definition of Done (or DoD is in description/checklist). |
| Dependency chain | Billable project card must have a dependency (blocking) of the same project; following blocking must lead to the project card on the Projects board. |
Result: Passed (both criteria met) or Failed (one or both failed). Optionally add a note (e.g. “Project not yet opened so no dependency needed”; “Card is actionable.”).
Title prefix (optional)
To make status visible in list view, prepend the result to the existing title:
| Result | Format |
|---|---|
| Failed | [❌] + original title (e.g. [❌] [ระบบบริหารสถานศึกษา] SOW). |
| Passed | [✅] + original title (e.g. [✅] [Wandee Project] สอบถามความคืบหน้า Content). |
Keep the original title; only add the prefix at the front.
Related
| Document | Purpose |
|---|---|
| Engineering Architecture & Data Flow Guideline | Architecture and contract-first workflow; references Asana card templates. |
| Onboarding Guideline | How Kiluth uses Asana and other tools. |
| Privacy & Data Handling Guideline | No lead/contact PII in Asana; store in secure storage, link in task. |