New rich text and @-mentions



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!


Cannot create a webhook for "My Tasks"

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.