Welcome to kotlin-asana!

This repository is home to a library for Asana written in Kotlin, which implements task ⇔️ object serialization, a DSL for working with resources, auto pagination handling, and more!

kotlin-asana is aimed at extending the client's functionality with simple, declarative, and fun to use calls! Essentially, this library saves you from spending lots of time crafting API calls, so you can focus on your business logic. Read on to learn more and find examples.

Documentation

📚 For library documentation, please click here.

Jump to a section

1. Overview of features
2. Installation (with Maven)
   1. Add this project as a dependency
   2. Add JitPack as a repository
3. Quick setup
   • Supply your access token via environment variables
   • Alternative authentication methods
4. Quick examples
5. Detailed documentation and usage examples
   • Default behavior
   • Providing your own configuration
   • Getting started with this library
     • Using the asanaContext entrypoint
     • Working with resources
   • Serializing user-defined objects into tasks and back
     • Why, motivations, and use cases
     • Working with Asana data: an idiomatic approach with kotlin-asana

Overview of features

This library implements / supports:

1. Support for serializing and deserializing Tasks and their CustomFields into data objects.
2. Declaratively working with custom fields, tasks, projects, and workspaces.
3. Automagically handles pagination, passing query parameters, and other intricate setup work for you!
4. Searching for tasks within a workspace or project, with support for filters.
5. Enforces best practices for handling your access token.

Installation (with Maven)

Deployment of this project to Maven central coming soon™️️. For now, use JitPack.

Add this project as a dependency

Include this git repository into your project's pom.xml with the following dependency:

<dependency>
   <groupId>com.github.OliverAbdulrahim</groupId>
   <artifactId>kotlin-asana</artifactId>
</dependency>

Add JitPack as a repository

You'll also want to make sure that you have the JitPack repository:

<repository>
   <id>jitpack.io</id>
   <url>https://jitpack.io</url>
</repository>

Quick setup

Supply your access token via environment variables

Recommended: for easy, autowired setup, supply the asana_access_token environment variable wherever you use kotlin-asana.

java -jar <your app name>.jar asana_access_token=<your access token>

Alternative authentication methods

If you prefer to authenticate another way, or if you already have a java-asana Client object, follow these steps to provide kotlin-asana your own configuration (links to another document on this repository).

Quick examples

Working with resources

This library makes use of Kotlin function literals with receiver and extension functions; these allow you to cleanly and declaratively work with Asana resources like tasks, projects, and workspaces within any asanaContext (the entry point for this library).

asanaContext {
    // Tasks
    val person: Person = task("123").convertTo(Person::class)

    // Projects
    val taskAgain: Task = project("456") { person.convertToTask(this).update() }

    // Workspaces
    val search: List<Task> = workspace("789").search("ice cream sundae", "456")
}

Learn more about asanaContext at this link. More information on this library's serialization at this link.