How to Set Up Asana for synchronizing

Moral Fabric syncs your team structure and projectsfrom Asana. Your circles (teams) and roles live in Asana, and the app pulls them in automatically.
There are two sync modes:
Mode
Structure
Project Mode (Recommended)
One root project containing circles as linked sub-projects
Portfolio Mode
A portfolio containing circle projects (less tested)


Part 1: Create Your Asana Structure

Root Project: Create a project that serves as your master directory (e.g., Organization Roles).
Circle Projects: For each team, create a separate project that will hold its roles as tasks (e.g., Operations Team Roles).
Link Circles: In your root project, create a task for each circle. The description must include a link to the circle's roles project in this exact format:
[Roles: https://app.asana.com/0/PROJECT_ID/list]
This pattern is how Moral Fabric discovers which projects are circles. You can add a purpose above the link:
Purpose: Ensure smooth daily operations across the organization.

[Roles: https://app.asana.com/0/1234567890123456/list]
Add Roles: Inside each circle project, create tasks for roles. Assign them to the person filling the role. Use this description format:
Purpose: [What this role is responsible for]

Accountabilities:
- First accountability
- Second accountability

Domains:
- First domain


Part 2: Custom Fields (Recommended)

Custom fields add richer information but aren't required for basic setup.
Role type - Create an enum field with options: Lead Link, Facilitator, Secretary, Rep Link, Role. Apply to circle projects and set on each role task.
Assigned Roles - If tracking team projects, create a reference-type field that links project tasks to role tasks. Note the field's GID (found in the URL when editing the field) - you'll need it in Moral Fabric settings.


Part 3: Connect to Moral Fabric

Generate an access token in the  Asana Developer Console  by clicking "Create new token" and copying it immediately.
In Moral Fabric, go to Settings → Integrations → Asana, enter your token, select Project Mode, and paste your root project ID (the number in the URL: app.asana.com/0/PROJECT_ID/...). The initial sync starts automatically.
If using project tracking, add the Assigned Roles field GID in Settings → Workspace.


Part 4: Nested Circles

To create sub-teams, add a task with [Roles: link] inside a circle's roles project pointing to another project. Moral Fabric discovers the hierarchy automatically.
Root Project
├── Operations Team [Roles: /operations-roles]
│   └── Finance Sub-Team [Roles: /finance-roles] ← task inside operations-roles
└── Product Team [Roles: /product-roles]


Part 5: Ongoing Sync

Moral Fabric syncs every 5 minutes by default. Changes to roles, assignees, and circle structure update automatically. Trigger a manual sync anytime from Settings → Integrations → Asana.


Portfolio Mode (Alternative)

Instead of a root project, create an Asana Portfolio containing your circle projects directly. Each project in the portfolio becomes a circle; tasks inside become roles.
When connecting, select Portfolio Mode and enter the Portfolio ID. You can use Parent Circle and Portfolio reference fields on projects for hierarchy and work tracking.
Note: This mode has not been thoroughly tested.


Troubleshooting

Issue
Solution
Circles not appearing
Check that [Roles: link] pattern is exact, including brackets
Assignees not showing
Ensure the token has access to view user details
Projects not linking to roles
Verify the Assigned Roles field GID in workspace settings