A new API for Project Templates

Hi everyone,

Today we launched a new set of API endpoints for apps that interact with project templates in Asana. With this launch, we are completely reworking how templates are represented within Asana, which will allow us to continue investing in making our users’ cross-functional workflows seamless.

In addition, this change starts a 6-month deprecation period for the opt-in is_template field included in the Project schema, which has been the primary programmatic method for apps to interact with project templates until now.

If your app relies on the is_template field, please read on carefully for changes that may impact you.

Background

Today’s API launch comes ahead of the GA rollout of Asana’s new Project Templates. Migrating an existing feature to a new representation creates a number of developer challenges.

Previously, Asana project templates were simply projects with the is_template flag set, and API consumers instantiated these templates using the standard Project duplication API. In the new system, project templates are a dedicated resource in our data model, and instantiation takes place through a template instantiation endpoint. Furthermore, we are allowing both template systems to coexist before we complete the deprecation of the legacy template backend and force a full migration to the new system in August.

To mitigate the complexity of these changes for our third party developer community, today we’ve launched a new, dedicated Project Templates API. This API seamlessly handles both existing project templates and the new Project Template objects that we are releasing in April. As the new API fully supports all project templates in Asana today, you can migrate your application to the new endpoints at any time. Once you complete your migration, your application will continue working correctly through all of the upcoming template releases, migrations, and deprecations.

API Changes

The following changes are included in today’s API launch:

Deprecation Timeline

As mentioned above, along with today’s API changes, we are deprecating certain API support for project-based templates, namely the is_template field. The deprecation period will last 6 months; we plan to remove the is_template flag from the API around August.

Here are the other important dates along the way:

  • April: New project templates will launch for all Asana users. After this date, any new project template created by a user on a team or workspace will be backed by a ProjectTemplate resource. At the same time, project-based templates that were previously created will continue to be accessible to these users until we begin migrating them to the new data model (see below).

  • Late May / Early July: We will begin migrating project-based templates to the new data model for all users. The migration process will take a few weeks to complete. During this time, any project-based template that is migrated will continue to exist and remain accessible as a regular project, with that project being automatically archived following migration. Note that between April and when we complete the migration process, the two types of projects templates will coexist (in both the API and the Asana UI), and the new GET endpoints listed above will return both.

  • August: The deprecation period will end and the is_template field will be removed from the API, both as a request parameter and an object field in responses. Beyond this date, attempting to read or write this field via the API will result in an error. Note that apps will still be able to read and write the is_template field post-migration until August, but reads will return a “snapshot” of the project-based template at the point of migration, and writes will be invisible to end users.

Migrating Apps

In April, Asana users will begin creating templates that can no longer be queried through the old is_template method. In August, all templates will be migrated to the new template backend. If your app queries, mutates, or creates projects from templates, you’ll need to modify your app logic to make use of the new endpoints launching.

Your migration path will depend on the use case(s) your app implements:

If your app needs to … And it used to … It should now instead …
List all project templates belonging to a workspace Call GET /projects with is_template query parameter set to true Call GET /project_templates
List all project templates belonging to a team Call GET /team/{team_gid}/projects with is_template query parameter set to true Call GET /team/{team_gid}/project_templates
Retrieve a specific project template by id Call GET /projects/{project_gid} with is_template query parameter set to true Call GET /project_templates/{project_template_gid}
Create a new project from a template Call POST /projects/{project_gid}/duplicate on a templatized project Call POST /project_templates/{project_template_gid}/instantiateProject
Create a new project template Call POST /projects with is_template property set to true in the request body Create the project as before (except for the is_template property) and then call POST /projects/{project_gid}/saveAsTemplate with the id of the newly created project. Note that this endpoint creates new template objects that won’t be visible in the Asana UI until April.

Any templates created past April will not be visible to apps using the old endpoints. You may want to perform this migration sooner if you expect a user of your app to start using new project templates functionality (given the timelines above), and you’d like to support this usage in your app.

Over the coming months, we’ll be adding new capabilities to project templates, so please watch this space for how you can take advantage of these new capabilities and unlock new use cases in your apps. And, as always, if you have any feedback or questions about the changes included in today’s launch, or how they might impact you, feel free to drop us a line below.

6 Likes

Hi @AndrewWong,

One other new endpoint you might want to add to the API Changes bullet list is the ability to create a project template from a project (Asana). It is mentioned in the migration section but not in the changes list, so some folks might miss it.

One question, @AndrewWong: during this period when both PT 1.0 and 2.0 templates will be returned intermingled in a GET list, how should we differentiate between them?

You shouldn’t need to differentiate between them, the template APIs work the same with both. We built it this way because users can convert their legacy project templates to the new system at any time, and we didn’t want our developers to have to react to these conversions.

1 Like

Hello!

So my application relies on getting all the tasks under a project which are templates.
With this change, is there any option to be able to get all tasks in a project template?

Hi @Tony_Anh_Nguyen,

No, not currently. Asana will likely be adding CRUD capability to the new Project Templates 2.0 but it’s not there now.

(cc: @Kem_Ozbek, here’s another vote for CRUD in PT 2.0)

Hi @Phil_Seeman,

Any chance we know when that might be added?

No, sorry, @Tony_Anh_Nguyen, I don’t have any info on timing.

Hi everyone! I began the work to migrate my application to the new endpoints, but quickly ran into a roadblock because the latest versions of the Asana Node.js SDK are not being published to npm. Could you all reach out to the maintainers of the Node.js SDK internally to get this fixed up?

The latest release on GitHub is v0.18.3 (released on March 4, 2022) which adds support for the project templates API, but the latest release pushed to npm is v0.18.6 (released on Feb 26, 2021).

I’m bringing it up here because there is a GitHub issue for this, but it hasn’t seen any activity from the maintainers.

I looked through the commit log and I think they deploys broke because Travis CI stopped running jobs on travis-ci.org. If that is indeed the reason, it should be a pretty easy fix to move the repository over to travis-ci.com and re-run the build. Happy to help with that process if needed :smiley:

It is probably too late but templates v2 do not seem ready for our clients and us. They are lacking some features like multi-select of tasks, define default sort or filter, define/edit dashboard… am I missing something or did all of this will disappear slowly with no fix in sight?

Has someone compiled a list of features that will disappear? Otherwise I will.

cc @Phil_Seeman

I don’t know of a comprehensive list in one post. There is a bunch of discussion about missing features here: Say Hello to Project Templates 2.0!

That thread is probably the best place for further discussion on PT 2.0, and for such a list.