No more parsing story text! New fields on stories!

api
stories
#1

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_liked
    • attachment - the attachment that was liked
  • completion_liked
    • story - the completion story that was liked

People

  • assigned
    • assignee - the new assignee
  • unassigned
  • follower_added
    • follower - the user that was added as a follower

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.

7 Likes
Rest API: Task with no associated stories
pinned #2
#3

Nice! Impressive!

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

Thanks,

Larry

1 Like
#4

@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.

1 Like
#5

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 :slight_smile:

2 Likes
#6

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?

1 Like
#7

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.

#8

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.

#9

@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.

#10

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

#11

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.