Potentially breaking API change: content deprecation for the `text` and `html_text` fields of stories

Hello there!

My name is Mary Xu, and I’m a software engineer working on the server-side of the Mobile area at Asana. I’m here to announce a deprecation update in our story texts.

What’s Changing

Specifically, this impacts the text and html_text fields of story objects, such as those that appear in tasks and messages. Previously, these story phrases didn’t include the primary subject’s name. This change adds the subject’s name to create full sentences in the response fields.

Here’s an example.

Before:

  • text: “created this task.”
  • html_text: “created this task.”

After:

  • text: “Asana created this task.”
  • html_text: “<b>Asana</b> created this task.”

Notably, this name will appear in plaintext for the text field, but surrounded with bold tags for the html_text field to align with the formatting in our UI. It will only impact stories with non user-generated text following this pattern (e.g. comments are not changing).

Motivation

Currently, if you are fetching these phrases for display, it’s almost always necessary to prepend the name of the story creator manually to show the full context. We are making this text change because several recently-introduced languages (namely Russian and Polish) are non-subject first, meaning that the story creator name does not begin the sentence. This posed issues when attempting to translate our story text phrases, so it made the most sense for them all to be converted into full sentences, allowing the subject to be freely re-positioned based on language. This also means that the API will have complete localized text support in these languages!

Deprecation Details

We are using our deprecations framework to roll out this change. The deprecation header is called subject_in_story_text.

  • Start date: available for opt-in today
  • Activation date: November 1st, 2021
  • End date: December 15th, 2021

This change may be breaking for those displaying the text and/or html_text fields to users, as it will introduce grammatical errors like having a repeated subject name if you are currently performing manual subject prepending (e.g. “Asana Asana created this task.”). Please plan any updates accordingly to ensure a smooth transition!

Thank you!

3 Likes

FYI, the API documentation still says the creator name will not be included in html_text:

The documentation for text is also inconsistent with html_text and seems to be referring to comment creation only.