Rich Text feature deprecation bug

We just found out that since last Monday we were creating automated tasks anymore. After some initial debugging with Postman we could exclude that our integration or API key was the problem.

This brought us to the deprecations documentation, and that brought us to Oct 15 as activation date for Rich Text feature.

Our implementation already using the field html_notes, as that already was there for several years. It seems that the newly activated Rich Text feature does reuse that field.

This technically is a bug, as the end date of December 17 is not reached yet. I am affraid that many API integrations now don’t create tasks anymore, as our implementation does not throw exceptions based on the cURL result.

While looking for a fix, we found out that headers can be sent to disable the feature. We added the following fix (valid until December 17) to make our integration work again:

array_push($headerData, 'Asana-Disable: new_rich_text');

Are you wrapping the html_notes content inside a <body> tag? This was my mistake. After doing that, it works fine. You don’t have a clear error message from the server?

Bastien - Asana Certified Pro
Delegate tasks to a virtual assistant :computer:

1 Like

No we don’t, and we are working on properly supporting the new Rich Text in the meanwhile. This will be live before December 17 :+1:

The problem is not in coming up with a fix though, the hotfix using the header is working. The point is that adding <body> wasn’t needed before the Rich Text deprecation / feature release process was started, which makes this a BC break and bug.

I can imagine that other API users will have the same problem, and aren’t aware of it yet as the API did not throw an exception.

If I understood well the deprecation process, for a few months we were suppose to add the proper flag to activate the new format and comply to it. Then yesterday they activated the new format by default and you need a flag to rollback to the old format.
I personally made the mistake of not testing my app with the flag to activate the new format and waited for it to break. Did you activate the new format before and did not need the body tag?

1 Like

We did not change our codebase for months.

We wrapped the html_body in body tags and it fixed it for us.

I don’t think @Richard_van_Laak is needing any help with getting his code to work. His point is that he’s asserting that he considers it a bug that it stopped working prior to the “End Date” of 12-17.

I would respectfully disagree, though: the Deprecations documentation clearly states that there is a middle milestone, the “Activation Date”, on which the new feature becomes the default. So the API team correctly followed the documented timeline here.

I guess the only other question that Richard raised is why submitting the old-format input without including the Asana-Disable header failed silently rather than throwing an exception. Perhaps @Joe_Trollo could provide an explanation as to that decision; I think he discussed it at one point but I can’t recall that discussion.


@Phil_Seeman is correct, the end date is when we completely shut off access to the old behavior. We change the default behavior on the activation date, in the middle of the migration period, so that developers who are caught off-guard have time to react and fix their apps.

If we waited until the end of the migration period to change the default, developers that are caught off-guard cannot apply the Asana-Disable header patch while they adapt to the change—their app would be broken until they could fully understand and implement the new requirements, which for some upcoming changes could take several weeks.

The API does throw an exception in this case. It will throw the following 400 Bad Request error:

$ curl -X POST -i \
> \
>   -H 'Content-Type: application/json' \
>   -H 'Authorization: Bearer [redacted]' \
>   -d '{
>   "data": {
>     "html_notes": "text",
>     "assignee": "me",
>     "workspace": <workspace_id>
>   }
> }'

HTTP/1.1 400 Bad Request
  "errors": [
      "error": "html_lacks_body",
      "message": "Rich text should be wrapped in <body> tag.",
      "help": "For more information on API status codes and how to handle them, read the docs on errors:"

@Joe_Trollo do you guys only announce deprecations in the Community? How could @Richard_van_Laak know if he doesn’t come here?
@Phil_Seeman thanks for pointing this out. I indeed assumed Richard saw the announcements and tried to help with the fix itself.

Thanks for referring to REMINDER: New Rich Text format kicks in on Oct 15th Diakoptis :+1: We did not catch that.

“many of which were not officially launched”

Probably we were using a feature that was never officialy supported :wink: So, no problem with the deprecation process here.

@Joe_Trollo thank you for the API example. Maybe having some specific “this is deprecated, see here” help message would be a great improvement as well. Did look for a http 20x HTTP response code for something like “conditionally OK”, but that doesn’t exist.

We will improve our API error handling to cope with the Asana deprecation process, which in turn would actively warn us via Sentry → Slack.


@Bastien_Siebman: we also post about deprecations and features in our blog, mention it in our developer newsletter, and last week we sent out an email blast to anyone who, according to our data, would hit an error when we enabled the feature. Reaching everyone is difficult, though, so if you have more suggestions we’d love to hear them!

@Richard_van_Laak: we have a mechanism similar to that—if there’s an upcoming change in the API, there will be an Asana-Change header in our responses with relevant information. And, if your app is actually affected by the change (i.e., it hits the code path that the change alters) that header will have affected=true in it to let you know. You can look at these headers to systematically learn about upcoming changes and whether they affect your app.


Looks like you cover all the bases!