> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Asana

> Client-mode REST API connector for a curated Asana REST API v1.0 slice: create/update tasks, list project tasks, users/me smoke, workspaces, and webhook create

Technical Preview

## Overview

A client-mode connector for a **curated work-management** slice of the [Asana REST API](https://developers.asana.com/reference/rest-api-reference):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST tasks | `POST /tasks` | Create task from alarm / MQTT (body `{"data":{…}}`) |
| PUT tasks/\{gid} | `PUT /tasks/{task_gid}` | Update task fields / complete |
| GET projects/\{gid}/tasks | `GET /projects/{project_gid}/tasks` | List project tasks |
| GET users/me (smoke) | `GET /users/{user_gid}` with `me` | Credential check → `data.gid` |
| GET workspaces | `GET /workspaces` | Workspace discovery |
| GET tasks/\{gid} | `GET /tasks/{task_gid}` | Single task read |
| POST webhooks | `POST /webhooks` | Register Asana → HTTPS target |

Default `BASE_ADDRESS` is `https://app.asana.com/api/1.0`. Topics use `devops/asana/<object>/<verb>`.

> [!NOTE]
>
> Auth is **Bearer** personal access token or OAuth 2.0 access token (`Authorization: Bearer …`). Prefer Hub secret `ASANA_ACCESS_TOKEN` (aliases `ASANA_PAT`, `ASANA_TOKEN`). Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Asana REST API v1.0
# Auth: Bearer {value.json.access_token} (PAT or OAuth)
# BASE_ADDRESS: https://app.asana.com/api/1.0

DEFINE ROUTE AsanaRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://app.asana.com/api/1.0"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuser
        WITH SOURCE_TOPIC "devops/asana/user/get"
        WITH DESTINATION_TOPIC "devops/asana/user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/users/{value.json.user_gid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getworkspaces
        WITH SOURCE_TOPIC "devops/asana/workspace/list"
        WITH DESTINATION_TOPIC "devops/asana/workspace/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/workspaces"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createtask
        WITH SOURCE_TOPIC "devops/asana/task/create"
        WITH DESTINATION_TOPIC "devops/asana/task/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Updatetask
        WITH SOURCE_TOPIC "devops/asana/task/update"
        WITH DESTINATION_TOPIC "devops/asana/task/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/tasks/{value.json.task_gid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Gettask
        WITH SOURCE_TOPIC "devops/asana/task/get"
        WITH DESTINATION_TOPIC "devops/asana/task/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tasks/{value.json.task_gid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Gettasksforproject
        WITH SOURCE_TOPIC "devops/asana/project/tasks"
        WITH DESTINATION_TOPIC "devops/asana/project/tasks/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/projects/{value.json.project_gid}/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createwebhook
        WITH SOURCE_TOPIC "devops/asana/webhook/create"
        WITH DESTINATION_TOPIC "devops/asana/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuser | GET | `/users/{user_gid}` | `devops/asana/user/get` | `devops/asana/user/get/response` |
| Getworkspaces | GET | `/workspaces` | `devops/asana/workspace/list` | `devops/asana/workspace/list/response` |
| Createtask | POST | `/tasks` | `devops/asana/task/create` | `devops/asana/task/create/response` |
| Updatetask | PUT | `/tasks/{task_gid}` | `devops/asana/task/update` | `devops/asana/task/update/response` |
| Gettask | GET | `/tasks/{task_gid}` | `devops/asana/task/get` | `devops/asana/task/get/response` |
| Gettasksforproject | GET | `/projects/{project_gid}/tasks` | `devops/asana/project/tasks` | `devops/asana/project/tasks/response` |
| Createwebhook | POST | `/webhooks` | `devops/asana/webhook/create` | `devops/asana/webhook/create/response` |

## Auth

1. Create a [personal access token](https://developers.asana.com/docs/personal-access-token) in Asana developer console, **or** obtain an OAuth 2.0 access token.
2. Set connector `BASE_ADDRESS` to `https://app.asana.com/api/1.0`.
3. Pass `access_token` on MQTT JSON payloads so the Bearer header resolves. For path params, also pass `user_gid` / `task_gid` / `project_gid`.
4. Store secrets in Hub / `GET SECRET "ASANA_ACCESS_TOKEN"` (aliases `ASANA_PAT`, `ASANA_TOKEN`). Never commit real credentials.
5. Successful smoke: `GET /users/me` → **HTTP 200** with `data.gid`. Invalid tokens → **HTTP 401**.

## Example payloads

**getUser (smoke):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ASANA_ACCESS_TOKEN",
  "user_gid": "me"
}
```

**createTask:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "data": {
    "name": "Coreflux alarm — Zone A",
    "notes": "RMS exceeded limit",
    "projects": ["YOUR_PROJECT_GID"]
  }
}
```

**updateTask:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "task_gid": "YOUR_TASK_GID",
  "data": {
    "completed": true
  }
}
```

**createWebhook:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "data": {
    "resource": "YOUR_PROJECT_GID",
    "target": "https://YOUR_PUBLIC_HTTPS_CALLBACK/asana-webhook"
  }
}
```

## Server / inbound companion

`POST /webhooks` is **client-mode** registration (MQTT → Asana). Asana then POSTs events to your `target` URL (handshake with `X-Hook-Secret`). Receiving those callbacks into MQTT requires a separate companion `ENABLE_SERVER` connector — not included in `AsanaRestApi.lot`.

## Deploy notes

* Deploy `AsanaRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/asana](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/asana)

## Sources

* [Asana REST API reference](https://developers.asana.com/reference/rest-api-reference)
* [Personal access token](https://developers.asana.com/docs/personal-access-token)
* [OAuth](https://developers.asana.com/docs/oauth)
* [Webhooks guide](https://developers.asana.com/docs/webhooks-guide)
* [Official OpenAPI](https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.