Mavenlink

Story Allocation Days

Story Allocation Days in Mavenlink allocate a planned amount of time to an Assignment for a given day.

Story Allocation Day objects have eight readable attributes. They are:

  • id the unique identifier for this story allocation day object
  • updated_at the date the story allocation day was last updated
  • date the date of the story allocation day
  • minutes the minutes allocated to the story allocation day
  • current a calculated attribute that indicates whether or not the story allocation day's assignment is active
  • assignment_id the id of the assignment that owns the story allocation day
  • story_id the id of the story who owns the story allocation day's assignment
  • workspace_id the id of the workspace who owns the story allocation day's assignment

Fetching Story Allocation Days

The story_allocation_days endpoint provides a list of every story allocation day that the user making the request is allowed to see, across all workspaces that the user belongs to.

The response will contain an array of story allocation day objects, sorted by the updated_at attribute in descending order, available under the key named story_allocation_days.

As with all API listing actions, you can provide per_page and page to paginate your response. You may also limit the response to one or more specific story allocation days using the only parameter.

To list all a user's story allocation days using curl, run:

curl "https://api.mavenlink.com/api/v1/story_allocation_days.json"

Associated Objects

You can include story allocation days' associations with the include param. For example, to include the assignment and story for all your story allocation days you would do the following:

curl "https://api.mavenlink.com/api/v1/story_allocation_days.json?include=assignment,story"

In this example, our API will ensure that the returned JSON contains top-level keys called assignments and stories, where you can find associated data by inspecting story allocation days' assignment_id and story_id fields. See Object Associations to learn more. The following associations can be requested through the API:

  • assignment - when included, the assignment_id will reference the assignment for which the story allocation day belongs
  • story - when included, the story_id will reference the story for which the story allocation day belongs
  • workspace - when included, the workspace_id will reference the workspace for which the story allocation day belongs

Filtering Story Allocation Days

The story allocation days list provides filters to allow you to limit the story allocation days that will be returned.

  • assignment_id limits the returned story allocation days to only the story allocation days that belong to the assignment whose ID was given
  • story_id limits the returned story allocation days to only the story allocation days that belong to the story whose ID was given
  • workspace_id limits the returned story allocation days to only the story allocation days that belong to the workspace whose ID was given
  • assignee_id limits the returned story allocation days to only the story allocation days that belong to the user whose ID was given
  • current limits the returned story allocation days to only the story allocation days that belong to active assignments
  • uncurrent limits the returned story allocation days to only the story allocation days that belong to inactive assignments
  • in_unarchived_workspaces - (default true) limits the returned story allocation days to only the story allocation days that belong to active workspaces
  • in_unarchived_stories - (default true) limits the returned story allocation days to only the story allocation days that belong to inactive stories (inactive stories can exist in active workspaces, and vice versa)
  • updated_at_between - Requires a colon separated pair of timestamps. Timestamps are in ISO8601 format with colons removed. Results are inclusive of the endpoints. If a timestamp is not passed in, it is interpreted as negative or positive infinity
  • date_between - Requires a colon separated pair of dates in YYYY-MM-DD format. Results are inclusive of the endpoints. If a date is not passed in, it is interpreted as negative or positive infinity

For example, to retrieve story allocation days filtered by workspace:

curl "https://api.mavenlink.com/api/v1/story_allocation_days.json?workspace_id=1"

To request story allocation days in active assignments on January 31st, 2014:

curl "https://api.mavenlink.com/api/v1/story_allocation_days.json?current=true&date_between=2014-01-31:2014-01-31"

Ordering Story Allocation Days

Valid orders are:

  • updated_at
  • date

The default order is updated_at:desc.

Getting a Single Story Allocation Day

As with all resources, you can request either GET /api/v1/story_allocation_days.json?only=5 or GET /api/v1/story_allocation_days/5.json.

Creating a new Story Allocation Day

The story_allocation_day parameter has three required attributes:

  • assignment_id the ID of the Assignment in which the story allocation day will be created
  • date the date of the story allocation day in ISO8601 format
  • minutes the number of minutes allocated to that day for that assignment

For example, to create a new story allocation day using curl for assignment#5 on February 19th, 2013, for 45 minutes run:

curl -H "Content-Type: application/json" --data-binary '{"story_allocation_day": {"assignment_id": 5, "date": "2013-02-19", "minutes": 45}}' "https://api.mavenlink.com/api/v1/story_allocation_days.json"

If a story allocation day already exists for that assignment on that day, the existing story allocation day will be updated and returned, instead of creating a new story allocation day.

Updating an existing Story Allocation Day

An existing story allocation day can be updated with an HTTP PUT request. Only the minutes attribute can be changed in an update.

For example, to update a story allocation day with ID 5 to 75 minutes using curl, run:

curl -X PUT -H "Content-Type: application/json" --data-binary '{"story_allocation_day": {"minutes": 75}}' "https://api.mavenlink.com/api/v1/story_allocation_days/5.json"

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

Destroying an existing Story Allocation Day

An existing story allocation day can be deleted via an HTTP DELETE request.

For example, to delete a story allocation day with ID 5 run:

curl -X DELETE "https://api.mavenlink.com/api/v1/story_allocation_days/5.json"

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