REMINDER: New Rich Text format kicks in on Oct 15th

Hi everyone, we have a new big feature to announce! Some of you might know that several objects in Asana have HTML text in addition to plain text, such as for task descriptions and comments. Reading these fields will provide the styling users see in the web product using XML tags such as <STRONG> and <EM>, and writing to these fields allows you to create styled text through the API. However, these fields have had a number of shortcomings… until today! :tada:

We’ve revamped how HTML text works in the API, and now:

  • the fields use proper HTML tags like <strong> instead of <STRONG>
  • the content is wrapped in a root <body> tag to make it valid XML
  • links to other objects in Asana (@-mentions) contain extra attributes that help you understand what that object is, such as <a href="" data-asana-id="1234" data-asana-type="user">Joe Trollo</a>

Additionally, we’ve made it significantly easier to @-mention other objects. If you want to generate a link to an object with ID 1234, you only have to write <a data-asana-id="1234"/> and the API will generate the link and extra attributes for you!

This new feature is available for you to use starting today. We’re using our deprecations framework to migrate all the existing HTML text fields (many of which were not officially launched) so to get this new behavior you can send an Asana-Enable: new_rich_text header in your requests. We’ve also published comprehensive documentation about HTML text to our developers site, including examples of what the new text will look like and code fragments demonstrating how you might parse the metadata.

Let us know what you think in the comments! Happy coding!


Small update here: because our logging shows that no apps are currently using this feature, we will preemptively migrate the new rich text to use only string IDs. Because XML attributes are always strings anyway, the only impact is that the data-asana-id attribute is being renamed to data-asana-gid. The docs, blog post, and API will be updated to reflect this before the end of the week.


A reminder that the new Rich Text format will start taking affect on the API from Oct 15 next week! The html_text and html_notes fields will be affected. Whilst you can still access the old behavior through our Deprecations process, the change will be enabled by default from Oct 15 onwards.

Many of you are already adopting this change, but for those of you that have not, please take some time to do the following:

  1. Check if the changes will affect your code, if so:
  2. Make necessary changes to adopt our new Rich Text format
    OR pass in request header options to maintain the existing behavior during our deprecation period.

For a full list of our Active Deprecations, refer back to our Deprecations documentation.

1 Like