Mavenlink

Story Tasks (Checklists)

Story Tasks are used in Mavenlink to track a list of checklist items within a Story. This model includes a completion boolean and a position integer.

StoryTask objects have the following readable attributes:

  • name - the name of the story task
  • completed - a boolean representing the completion of the story task
  • completed_at - the time the story task if it has been completed
  • position - the story task's position in the list of story tasks
  • completed_by_id - the user id of a user if the story task has been completed
  • story_id - the id of the story the story task belongs to

Fetching Stories

You can access all of the story tasks (the checklist) for a specific story through the API as follows:

curl "https://app.mavenlink.com/api/v1/stories/5?include=story_tasks"

The resulting JSON will be a hash of story tasks that are associated with the story that has an id of 5. The stories will be sorted by position on the checklist.

Getting a Single Story Task

You can access a single story task on a story through the API as follows:

curl "https://app.mavenlink.com/api/v1/story_tasks/1.json"

The resulting JSON will be the story task (Checklist item) with an ID of 1.

Creating a new Story Task (Checklist Item)

Mavenlink Story Tasks belong to a Story and take the following parameters:

  • name - (required) the name of the story task
  • story_id - (required) the id of the associated story
  • completed - is 'true' or 'false', indicating whether or not this item is completed
  • position - is an integer indicating the position of the task in the list

You can create story tasks as follows:

curl -d "story_task[story_id]=5" -d "story_task[completed]=true" -d "story_task[name]=My Story Name" -d "story_task[position]=2" "https://app.mavenlink.com/api/v1/story_tasks.json"

Updating an existing Story Task

You can edit Story Tasks as follows:

curl -X PUT -d "story_task[name]=My Edited Story Name" -d "https://api.mavenlink.com/api/v1/story_tasks/1.json"

curl -X PUT -d "story_task[completed]=true" -d "https://api.mavenlink.com/api/v1/story_tasks/14.json"

The response will contain the JSON representation of the updated StoryTask or an error message indicating which arguments are missing or erroneous.

Any of the required or optional create parameters (except story_id) can be edited by an update.

Destroying an existing Story Task

You can delete Story Tasks as follows:

curl -X DELETE "https://api.mavenlink.com/api/v1/story_tasks/1.json"

The response will have no content and HTTP 204 status code if the StoryTask has been successfully deleted, or a JSON error message indicating why the Story Task could not be deleted.