Migrate from AGILITY to Asana

Agility Projects are the top-level container with a stable OID, Owner, Team, and description. They map directly to an Asana Project. We preserve the project description and map the Owner to an Asana team member with Project Editor permission. Projects with multiple Teams on the source side are noted as requiring multiple Asana Project shares post-migration.

Agility Iterations are first-class OID-bearing objects with start_date, end_date, status (Active/Closed/Planning), and velocity metrics. Asana has no native sprint object. We model iterations as a custom start_date__c and end_date__c pair on Tasks, and group tasks by iteration using a custom iteration_name__c text field. For teams using Asana Timeline (Gantt) view, we create a Timeline group per iteration. Velocity and cadence settings do not map; we note them in the handoff inventory for manual tracking in Asana Dashboards.

Agility Stories are primary work items with a title, description (rich text), status, story_points, owner, parent iteration, and a full set of custom fields. We map Stories to Asana Tasks with the name, notes (rich text), assignee (single assignee; multiple assignee cases handled via a reconciliation step), and custom fields. Story points migrate to a custom number field story_points__c. Custom field mapping uses the System Name as the Asana custom field API name, not the display label.

Agility Defects share the primary work item schema with Stories but include severity, detected_in_iteration, and resolution fields. We map Defects to Asana Tasks with severity stored in a custom dropdown field defect_severity__c (Critical, High, Medium, Low) and resolution stored as a custom text field defect_resolution__c. The detected_in_iteration relationship maps to the same iteration_name__c custom field used for Stories.

Agility Tasks are child work items belonging to Stories or Defects. They carry assignee, estimated_hours, and status. We map them to Asana Subtasks under the parent Task record. Parent-child linkage is resolved during import using Asana's parent_task_gid field, which we populate by matching the Agility parent OID to the migrated Asana task gid via the cross-reference table generated during the import pass.

Agility Test Sets aggregate Test Cases and carry environment, test type, and status fields. Asana has no native test set object. We model each Test Set as an Asana Task with custom fields test_set_environment__c, test_set_type__c, and test_set_status__c, and attach Test Cases as Subtasks of that Task. Test Set member ordering from Agility is preserved in Subtask position order. Edition-gated schema on Starter/Pro Agility may limit available Test Set fields; we map only the intersection available in the source edition.

Agility Test Cases carry step-level instructions, expected results, and custom fields in the Fact.Test Data Mart. We export the full step structure as Asana Subtasks under the parent Test Set Task, with each step as a separate Subtask containing the expected result in the notes field. If the destination Asana workspace has a third-party test management integration (e.g., TestRail, Qase), we map Test Cases to that tool instead and store a link reference in a custom field test_case_reference__c on the Task.

Agility Issues are tracked in Fact.Issue with a schema distinct from primary work items, including issue_type, priority, and a separate custom field set. They have no parent-child relationship with Stories or Defects. We map Issues to Asana Tasks with issue_type stored in a custom dropdown field issue_type__c and priority mapped to Asana's built-in Task priority field (High, Medium, Low, or None).

Agility custom fields exist on most asset types and support checkbox, date, text, number, and drop-down types. The Data Mart column name derives from the System Name (internal identifier), not the user-facing display label. We extract both during discovery, generate a dual-key mapping table, and create Asana custom fields using the System Name as the API name. A custom field named 'Customer Priority' with System Name 'Custom_CustomerPriority' in Agility creates an Asana custom field with API name custom_c_customer_priority__c and display label 'Customer Priority'. Drop-down values migrate as option sets in Asana's custom field enum.

Agility stores binary attachments with a separate OID registry from the work item JSON payload, requiring a two-pass migration. We export attachments first, upload them to Asana via the attachments endpoint, capture the returned Asana gid, then re-associate them with the corresponding Tasks using a cross-reference table. This prevents orphaned attachment references. Maximum file size follows Asana's 100 MB per attachment limit; files exceeding this are flagged for manual chunking or alternative storage.

Agility Comments are child objects of work items with author, timestamp, and body (rich text). We migrate comments as Asana Stories on the Task record, preserving the author display name and the original timestamp. Comment attachments (if any) are handled in the attachment pass. Rich text formatting in Agility comments maps to Asana's HTML story format.

Agility user records include display name, email, role, and team membership. Active Directory integration in Agility can source users externally. We detect whether the destination Asana workspace uses local user management or SSO (Google, SAML). For SSO-configured Asana workspaces, we match users by email domain and flag any Agility users without matching Asana accounts for the customer's admin to provision before record import. Role mapping (Agility roles to Asana permissions) is noted in the handoff document for manual configuration.