Asana Managed API

A comprehensive Managed API wrapper for Asana REST API v1.0, providing type-safe, hierarchical access to all Asana API endpoints.

Overview

This Managed API wrapper provides a clean, type-safe interface to interact with the Asana API. It follows the same hierarchical pattern as other ScriptRunner Connect Managed APIs, making it easy to use and consistent with the platform's conventions.

Features

• Type-Safe: Full TypeScript support with IntelliSense
• Hierarchical Structure: Organized by resource type (Workspace, Project, Task, etc.)
• Comprehensive Coverage: Supports all major Asana API endpoints
• Error Handling: Built-in error parsing and handling
• Pagination Support: Utilities for handling paginated responses
• Web App Compatible: Works seamlessly in ScriptRunner Connect web app

Installation

The Managed API is already set up in this workspace. To use it in your scripts:

import Asana from './asana';

Usage

Basic Examples

Get Current User

import Asana from './asana';

const me = await Asana.User.getMe({
  optFields: ['gid', 'name', 'email']
});
console.log(`Logged in as: ${me.name}`);

List Workspaces

const workspaces = await Asana.Workspace.listWorkspaces({
  optFields: ['gid', 'name', 'isOrganization']
});
workspaces.forEach(ws => {
  console.log(`${ws.name} (${ws.gid})`);
});

Create a Project

const project = await Asana.Project.createProject({
  data: {
    name: 'My New Project',
    workspace: '1234567890',
    notes: 'Project description'
  }
});
console.log(`Created project: ${project.gid}`);

Create a Task

const task = await Asana.Task.createTask({
  data: {
    name: 'Complete documentation',
    workspace: '1234567890',
    projects: ['1234567891'],
    notes: 'Write comprehensive documentation'
  }
});
console.log(`Created task: ${task.gid}`);

Update a Task

const updatedTask = await Asana.Task.updateTask('1234567892', {
  data: {
    completed: true,
    notes: 'Task completed!'
  }
});

Add a Comment (Story)

const story = await Asana.Story.createStory('1234567892', {
  data: {
    text: 'Great progress on this task!'
  }
});

API Groups

The Managed API is organized into the following groups:

Workspace

• getWorkspace(options) - Get a specific workspace
• listWorkspaces(options?) - List all workspaces

User

• getMe(options?) - Get current user
• getUser(options) - Get a specific user
• listUsers(options?) - List users

Project

• getProject(options) - Get a specific project
• listProjects(options?) - List projects
• createProject(request) - Create a new project
• updateProject(projectGid, request) - Update a project
• deleteProject(projectGid) - Delete a project
• addMembers(projectGid, request) - Add members to a project
• removeMembers(projectGid, request) - Remove members from a project

Task

• getTask(options) - Get a specific task
• listTasks(options?) - List tasks
• searchTasks(options) - Search for tasks
• createTask(request) - Create a new task
• updateTask(taskGid, request) - Update a task
• deleteTask(taskGid) - Delete a task
• addProject(taskGid, request) - Add a project to a task
• removeProject(taskGid, request) - Remove a project from a task
• addFollowers(taskGid, request) - Add followers to a task
• removeFollowers(taskGid, request) - Remove followers from a task
• addTag(taskGid, request) - Add a tag to a task
• removeTag(taskGid, request) - Remove a tag from a task

Story (Comments)

• getStory(options) - Get a specific story
• listStories(options) - List stories for a task or project
• createStory(taskGid, request) - Create a story (comment) on a task
• deleteStory(storyGid) - Delete a story

Tag

• getTag(options) - Get a specific tag
• listTags(options?) - List tags
• createTag(request) - Create a new tag
• updateTag(tagGid, request) - Update a tag
• deleteTag(tagGid) - Delete a tag

Section

• getSection(options) - Get a specific section
• listSections(options) - List sections for a project
• createSection(projectGid, request) - Create a new section
• updateSection(sectionGid, request) - Update a section
• deleteSection(sectionGid) - Delete a section
• addTask(sectionGid, request) - Add a task to a section

Attachment

• getAttachment(options) - Get a specific attachment
• listAttachments(options) - List attachments
• createAttachment(request) - Create an attachment
• deleteAttachment(attachmentGid) - Delete an attachment

Custom Field

• getCustomField(options) - Get a specific custom field
• listCustomFields(options?) - List custom fields
• createCustomField(request) - Create a new custom field
• updateCustomField(customFieldGid, request) - Update a custom field
• deleteCustomField(customFieldGid) - Delete a custom field
• createEnumOption(customFieldGid, request) - Create an enum option
• updateEnumOption(enumOptionGid, request) - Update an enum option
• deleteEnumOption(enumOptionGid) - Delete an enum option

Team

• getTeam(options) - Get a specific team
• listTeams(options?) - List teams

Webhook

• getWebhook(options) - Get a specific webhook
• listWebhooks(options?) - List webhooks
• createWebhook(request) - Create a new webhook
• updateWebhook(webhookGid, request) - Update a webhook
• deleteWebhook(webhookGid) - Delete a webhook

Event

• getEvents(options) - Get events from an event stream

Advanced Usage

Using optFields

The optFields parameter allows you to specify which fields to return in the response:

const task = await Asana.Task.getTask({
  taskGid: '1234567890',
  optFields: ['gid', 'name', 'completed', 'assignee', 'dueOn']
});

Pagination

For endpoints that support pagination, use the limit and offset parameters:

const tasks = await Asana.Task.listTasks({
  workspace: '1234567890',
  limit: 50,
  offset: 'eyJ0aW1lc3RhbXAiOjE2NDA5MjE2MDB9'
});

Error Handling

The Managed API automatically parses Asana error responses:

try {
  const task = await Asana.Task.getTask({ taskGid: 'invalid' });
} catch (error) {
  console.error('Error:', error.message);
  // Error messages are automatically extracted from Asana's error response
}

Direct API Access

For advanced use cases, you can access the underlying API connection:

// Use the fetch method for custom endpoints
const response = await Asana.fetch('/api/1.0/custom/endpoint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: { custom: 'value' } })
});

Type Definitions

All TypeScript types are exported from the main module:

import Asana, { Task, Project, CreateTaskRequest } from './asana';

function processTask(task: Task) {
  // Type-safe access to task properties
  console.log(task.name, task.completed);
}

Testing

See the tests/ directory for comprehensive test scripts:

• basic-test.ts - Quick verification of core functionality
• create-test-data.ts - Creates test data
• verify-test-data.ts - Verifies test data
• cleanup-test-data.ts - Cleans up test data
• comprehensive-test.ts - Full end-to-end test

API Connection Setup

This Managed API uses the API Connection configured at scripts/api/asana. Ensure:

1. API Connection is configured in ScriptRunner Connect web UI
2. Base URL is set to https://app.asana.com
3. Authentication is configured (Personal Access Token or OAuth)
4. Header includes Authorization: Bearer <token>

Limitations

• Only works with resources in the scripts/ folder (cannot use node/ or node_modules/)
• Requires API Connection to be configured in ScriptRunner Connect
• Some Asana API endpoints may have rate limits

Resources

• Asana API Documentation
• ScriptRunner Connect Documentation
• Test scripts in tests/ directory

Support

For issues or questions:

1. Check the test scripts for usage examples
2. Review the Asana API documentation
3. Check ScriptRunner Connect logs for error details