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_changedold_nameandnew_name
notes_changed- the task description was changeddue_date_changedold_datesandnew_dates- objects with the old/new values, containing:start_ondue_ondue_at
marked_today- the assignee marked this task for todaymarked_completemarked_incompleteresource_subtype_changed- used when a task is converted to a milestone or vice versaold_resource_subtypeandnew_resource_subtype- the old and new subtypes
Comments and likes
likedcomment_addedcomment_likedstory- the comment story that was liked
attachment_addedattachment- the attachment that was added
attachment_likedattachment- the attachment that was liked
completion_likedstory- the completion story that was liked
People
assignedassignee- the new assignee
unassignedcollaborator_addedcollaborator- the user that was added as a collaborator
Moving and reorganization
section_changedold_sectionandnew_section- the section the task was moved into (either may benull)
added_to_taskandremoved_from_task- this task was added/removed as a subtask of another tasktask- the task that this one was added to/removed from
added_to_projectandremoved_from_projectproject- the project this task was added to/removed from
added_to_tagandremoved_from_tagtag- the tag it was added to/removed from
Custom fields
text_custom_field_changedold_text_valueandnew_text_value- the old and new text values
number_custom_field_changedold_number_valueandnew_number_value- the old and new number values
enum_custom_field_changedold_enum_valueandnew_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 duplicateduplicate_of- the task that was closed and merged into this one
marked_duplicate- this task was merged into another task as a duplicateduplicate_of- the task that this one was merged into
duplicate_unmerged- a task that was previously merged into this one was unmergedduplicate_of- the task that was unmerged
unmarked_duplicate- this task was marked as not a duplicateduplicated- this task was duplicated from another taskduplicated_from- the source of this task
Dependencies
dependency_addedanddependency_removeddependency- the task that this one depends on
dependent_addedanddependent_removeddependent- the task that depends on this one
dependency_marked_completeanddependency_marked_incompletedependency- the dependency that was marked complete/incomplete
dependency_due_date_changeddependency- the dependency that had its due date changednew_dates- the new dates on the dependency
all_dependencies_marked_complete
Notifications
starting_today- this task is starting todaydue_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.
