Asana Integration for Vantage

Overview

The Asana Integration within Vantage serves as a bridge between Vantage's powerful analytics platform and Asana's project management capabilities. By integrating with Asana, users can fetch, create, and manage tasks, projects, and workspaces, enhancing their data insights and project workflow efficiency. This integration uses the Asana REST API v1 to facilitate seamless communication and data handling.

Purpose

The primary purpose of the Asana Integration is to enable users to:

• Access users' information from Asana.
• Retrieve workspaces and projects.
• Create, update, search, and manage tasks effectively.
• Ensure automated token management for secure API calls.

How It Works

The integration operates based on OAuth 2.0 for user authentication. It manages access tokens to handle secure API requests:

1. Token Management: It retrieves and refreshes the access token when necessary to ensure valid authentication with the Asana API.
2. API Requests: It wraps around the fetch calls to handle common response errors like authentication issues and rate limiting.
3. Data Handling: It manages the creation, updating, and retrieval of various entities in Asana such as tasks and projects.

Settings

The Asana Integration has the following settings, which are crucial for its configuration and behavior:

1. serviceId

• Input Type: String
• Description: Identifies the service this integration interacts with, specifically targeting Asana.
• Default Value: None (must be provided during initialization)

2. clientId

• Input Type: String
• Description: The unique identifier for the Asana application, used for OAuth authentication.
• Default Value: None (must be provided during initialization)

3. credentialId

• Input Type: String
• Description: Serves as a unique identifier for the stored credentials in the database required for accessing Asana.
• Default Value: None (must be provided during initialization)

4. encryptedRecord

• Input Type: Object
• Description: Contains the encrypted credentials and data necessary for authentication, including access token information.
• Default Value: None (must be provided during initialization)

Data Expectations

The Asana Integration expects the following data from users:

• Workspace GID: Required for accessing tasks and projects within a specific workspace.
• Task Data: When creating a new task, the following fields are expected:
  • name: (String) The name of the task (mandatory).
  • notes: (String) Additional details about the task (optional).
  • assignee: (String) GID of the user assigned to the task (optional).
  • dueOn: (Date) The due date for the task (optional).
  • startOn: (Date) The start date for the task (optional).
  • projectGid: (String) The project GID to categorize the task (optional).

User Methods

The integration exposes several user-facing methods for interacting with Asana:

• getMe(): Fetches the authenticated user's information.
• getWorkspaces(): Lists all workspaces accessible by the user.
• getProjects(workspace): Retrieves projects within a specific workspace.
• searchTasks(workspaceGid, options): Searches for tasks based on specified criteria in a workspace.
• createTask(taskData): Creates a new task within Asana.
• updateTask(taskGid, updates): Updates an existing task's attributes.
• addComment(taskGid, text): Adds a comment to a specific task.

Use Cases & Examples

Use Case 1: Task Management Automation

A project management team requires constant updates on task progress from Asana. By leveraging the Asana Integration, they can automate the retrieval of tasks due today and their current status for analytics.

Use Case 2: Workspace Reporting Insights

A business analyst aims to consolidate reports from multiple workspaces to derive insights on project health and resource allocation. The Asana Integration supports fetching workspaces and projects, enabling bulk data analysis.

Concrete Example Configuration

Suppose a user wants to create a new task titled "Prepare Consolidated Report" in the "Marketing" project within the "Q3 Planning" workspace, assigned to a specific user. The configuration might resemble:

{
  "serviceId": "12345",
  "clientId": "client-xyz",
  "credentialId": "cred-abc",
  "encryptedRecord": {
    "accessToken": "encrypted-access-token",
    "refreshToken": "encrypted-refresh-token",
    "tokenExpiry": "2023-10-30T12:34:56.789Z"
  },
  "taskData": {
    "name": "Prepare Consolidated Report",
    "notes": "This task involves gathering data from different teams.",
    "projectGid": "project-67890",
    "workspace": "workspace-112233",
    "assignee": "user-4444",
    "dueOn": "2023-11-15",
    "startOn": "2023-11-01"
  }
}

This configuration incorporates essential data that fulfills both the task creation requirement and the necessary integrations with Asana API.

By effectively configuring the Asana Integration, users can leverage the combined functionality of Vantage and Asana for enhanced project management and analytics capabilities.