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:
-
A new endpoint for retrieving a specific project template.
-
A new endpoint for retrieving all project templates belonging to a workspace.
-
A new endpoint for retrieving all project templates belonging to a team.
-
A new endpoint for instantiating a project from a template.
-
A new field (
created_from_template) in Project objects indicating what template a project was instantiated from, if any. -
New webhook events for changes made to project template resources.
-
Support for project templates in the typeahead endpoint and the user’s favorites endpoint.
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
ProjectTemplateresource. 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
GETendpoints listed above will return both. -
August: The deprecation period will end and the
is_templatefield 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 theis_templatefield 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.
That should do the trick.