No more parsing story text! New fields on stories!

[Joe_Trollo]

Hey everyone, we have a new feature to announce! It’s less of a feature, though, and more of a plethora of new fields on stories. A while back, we added the resource_subtype fields in our API to objects like tasks and custom fields. Stories also got this treatment, which some of you may have noticed, but we decided to take it a step further. Instead of just providing the subtype of the story, we now also provide a bunch of extra relevant data as new, structured fields!

Here’s an example of a “due date changed” story in the API before:

{
  "id" : 1110484817449237,
  "gid" : "1110484817449237",
  "created_at" : "2019-02-19T21:59:21.704Z",
  "created_by" : { ... },
  "resource_type" : "story",
  "target" : { ... },
  "text" : "changed the due date to February 21",  // Ew, nobody wants this
  "type" : "system"  // Not helpful in the slightest
}

If you wanted to know that this story means that someone changed a due date, you’d have to parse the text field. If you wanted to know what the due date was set to, you’d also have to parse the text field and have to infer what year is supposed to be. If you wanted to know the old due date, well… you’d be out of luck.

With the new fields we’ve added, this story will now look like a lot better:

{
  "id" : 1110484817449237,
  "gid" : "1110484817449237",
  "created_at" : "2019-02-19T21:59:21.704Z",
  "created_by" : { ... },
  "resource_type" : "story",
  "resource_subtype" : "due_date_changed"  // Unambiguous!
  "target" : { ... },
  "text" : "changed the due date to February 21",  // You don't have to touch this!
  "new_dates" : {
    "due_on" : "2019-02-21",  // A standard format!
    "due_at" : null,
    "start_on" : null
  },
  "old_dates" : {
    "due_on" : "2019-02-15",  // Information you didn't have before!
    "due_at" : null,
    "start_on" : null
  }
}

There are over 30 different subtypes of stories, and below you’ll find a comprehensive list of what they are, what they mean (if it’s not immediately obvious), and what extra fields they have on them. The outer-most level of the list below is the subtype of story, and the bullets beneath that are the fields it has. Note that (with the exception of resource_subtype) these new fields are not included by default on stories, and you’ll need to use opt_fields to select them. Special thanks to @Sasha_S and @Kevin_Quicho for doing the heavy lifting on this project!

Basic changes

• name_changed
  • old_name and new_name
• notes_changed - the task description was changed
• due_date_changed
  • old_dates and new_dates - objects with the old/new values, containing:
    • start_on
    • due_on
    • due_at
• marked_today - the assignee marked this task for today
• marked_complete
• marked_incomplete
• resource_subtype_changed - used when a task is converted to a milestone or vice versa
  • old_resource_subtype and new_resource_subtype - the old and new subtypes

Comments and likes

• liked
• comment_added
• comment_liked
  • story - the comment story that was liked
• attachment_added
  • attachment - the attachment that was added
• attachment_liked
  • attachment - the attachment that was liked
• completion_liked
  • story - the completion story that was liked

People

• assigned
  • assignee - the new assignee
• unassigned
• collaborator_added
  • collaborator - the user that was added as a collaborator

Moving and reorganization

• section_changed
  • old_section and new_section - the section the task was moved into (either may be null)
• added_to_task and removed_from_task - this task was added/removed as a subtask of another task
  • task - the task that this one was added to/removed from
• added_to_project and removed_from_project
  • project - the project this task was added to/removed from
• added_to_tag and removed_from_tag
  • tag - the tag it was added to/removed from

Custom fields

• text_custom_field_changed
  • old_text_value and new_text_value - the old and new text values
• number_custom_field_changed
  • old_number_value and new_number_value - the old and new number values
• enum_custom_field_changed
  • old_enum_value and new_enum_value - the old and new enum options

Stories of these subtypes also include a custom_field field on them pointing to the relevant custom field.

Duplicates

• duplicate_merged - another task was merged into this task as a duplicate
  • duplicate_of - the task that was closed and merged into this one
• marked_duplicate - this task was merged into another task as a duplicate
  • duplicate_of - the task that this one was merged into
• duplicate_unmerged - a task that was previously merged into this one was unmerged
  • duplicate_of - the task that was unmerged
• unmarked_duplicate - this task was marked as not a duplicate
• duplicated - this task was duplicated from another task
  • duplicated_from - the source of this task

Dependencies

• dependency_added and dependency_removed
  • dependency - the task that this one depends on
• dependent_added and dependent_removed
  • dependent - the task that depends on this one
• dependency_marked_complete and dependency_marked_incomplete
  • dependency - the dependency that was marked complete/incomplete
• dependency_due_date_changed
  • dependency - the dependency that had its due date changed
  • new_dates - the new dates on the dependency
• all_dependencies_marked_complete

Notifications

• starting_today - this task is starting today
• due_today - this task is due today

Let us know what you think about these new fields! And as always, let us know if you have any questions. We’ll update this post to reflect any clarifications we need to make as developers respond to this thread.

[lpb]

Nice! Impressive!

Maybe both the assigned and unassigned sub-types should include the old assignee though?

Thanks,

Larry

[Joe_Trollo]

@lpb We definitely wanted to include that! Unfortunately, Asana doesn’t save the previous assignee in our data model—only the new one. It’s still possible to infer the previous assignee by looking at the previous assigned story, but at the cost of a little extra work for the client code.

[Diakoptis]

Omg! This is a really cool-great-fantastic-amazing-and-a-long-awaited addition.

Thank you Asana Team <3

Ps. @Joe_Trollo at the Asana blog when you announce a new feature you have a nice Thank you legend with the names of the team behind the implementation. I’d love to see the same legend in API’s implementations too

[Phil_Seeman]

Hey @Joe_Trollo and team, good work!

I do have to ask, though, about the story-reporting gaps we’ve discussed before. That limitation still applies here, at least currently, right?

[Sami_Linnanvuo1]

This is a significant improvement!

The key question indeed is are there still gaps in data or do we get the full history? In our case we’re interested seeing which sections the card has been moved at any given time, also within a day.

[Tuomas]

Excellent update! Really happy to get the data in a standard format. But getting rid of the gaps would be even more important because there is no work around for that.

[Joe_Trollo]

@Phil_Seeman, yes, this change doesn’t affect story consolidation. We don’t currently have the means to change how our data model works at that level.

[Sheila_Rooney]

Hi Joe - would it be possible to get some of your time to understand stories and how this may help our team? We were just talking today about how to use Asana to mimic current Google Sheet/Powerpoint reports for leadership and dependencies was one of the asks. I currently work w/ Amie Tran if that helps, thanks!

sheila.m.rooney@pwc.com

[Joe_Trollo]

Hi @Sheila_Rooney, if you reach out to your existing contact, Amie will be able to answer your questions or coordinate a consultation with the appropriate team at Asana.

[Frederic_Malenfant]

I am currently implementing all of these for bridge24. I found a small issue: attachment_added also contains the “attachment” attribute, like attachment_liked.

[Frederic_Malenfant]

@lpb About the “unassigned” event, we don’t have the previous “assignee” value, but we still can see it in the “text” value, the name of the previously assigned is still there. I think we can use this one without searching for the previous “assigned” story.

[lpb]

That’s great to know! Thanks for following up, @Frederic_Malenfant.

[Joe_Trollo]

Be careful parsing that text! Our data model does currently save the user the task was unassigned from, but that wasn’t always the case so the text might be incorrect! That’s why we couldn’t expose the assignee field in the API.

Regarding the attachment stories—both of those should have a reference to the attachment that was added or liked. It’s a mistake that my original post didn’t specify this, and I’m updating it now.

[Andreas_Butz]

@Joe_Trollo
@Ipb
@Frederic_Malenfant
@Phil_Seeman

do we know which attachment belongs to what comment?

on webpage we can see that, but can we get that via API?

[Phil_Seeman]

FYI Joe Trollo is no longer with Asana.

Including @Andrew-asana

[skai_yeung]

Could I ask when will we get the new feature?

[Frederic_Malenfant]

I think you should now change this:

• old_dates and new_dates - objects with the old/new values, containing:
  • start_on
    *** start_at** (new)
  • due_on
  • due_at

It’s missing from the old_dates and new_dates, but we see the complete information in the stories.text.

[Frederic_Malenfant]

I tried to get the old / new values of the new multi-option custom field, and I can’t find which opt_field to use.

I have the story with resource_subtype “multi_enum_custom_field_changed”, but I can’t find the values. The text is good, something like
“userxxx changed new-multi-field from moulti-pass-3 to moulti-pass-1, moulti-pass-3”

Because the name of the value in the task is in the field “multi_enum_values”, I tried:
old_multi_enum_values, new_multi_enum_values,
but I have no results.

What is the name of the field to use in opt_fields, for that new custom field type?
Thank you.