Mavenlink

Assignments

Assignments in Mavenlink connect Users with Stories (Tasks). They also own Story Allocation Days.

Assignment objects have nine readable attributes. They are:

  • id the unique identifier for this assignment object
  • created_at the date the assignment was recorded in Mavenlink
  • updated_at the date the assignment was last updated
  • current whether or not the assignment is active
  • estimated_minutes a user defined number of minutes that the user is expected to work on this story (task)
  • allocated_minutes the calculated sum of the assignment's Story Allocation Day minutes
  • story_id the id of the Story (Task) that owns the assignment
  • assignee_id the id of the user who owns the assignment
  • story_allocation_day_ids the ids of Story Allocation Days belonging to the assignment

Fetching Assignments

The assignments endpoint provides a list of every assignment 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 assignment objects, sorted by the created_at attribute in descending order, available under the key named assignments.

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 assignments using the only parameter.

To list all a user's assignments using curl, run:

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

Associated Objects

You can include assignments' associations with the include param. For example, to include the story and assignee for Assignment#5 you would do the following:

curl "https://api.mavenlink.com/api/v1/assignments/5.json?include=story,assignee"

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

  • story - when included, the story_id will reference the story for which the assignment belongs
  • assignee - when included, the assignee_id will reference the user for which the assignment belongs
  • story_allocation_days - when included, the story_allocation_day_ids array will reference all of the Story Allocation Days that belong to the assignment. Including story allocation days requires the request to be filtered with the plannable filter

Filtering Assignments

The assignments list provides filters to allow you to limit the assignments that will be returned.

  • assignee_id limits the returned assignments to only the assignments that belong to the user whose ID was given
  • story_id limits the returned assignments to only the assignments that belong to the story whose ID was given
  • workspace_id limits the returned assignments to only the assignments that belong to the workspace whose ID was given
  • current limits the returned assignments to only active assignments
  • uncurrent limits the returned assignments to only inactive assignments
  • plannable limits the returned assignments to only assignments for which the user can view and create Story Allocation Days. This filter is required if including story_allocation_days
  • in_unarchived_workspaces - (default true) limits the returned assignments to only the assignments that belong to active workspaces
  • in_unarchived_stories - (default true) limits the returned assignments to only the assignments that belong to inactive stories (inactive stories can exist in active workspaces, and vice versa)
  • created_before - include assignments created before the given timestamp (in ISO 8601 format)
  • created_after - include assignments created after the given timestamp (in ISO 8601 format)
  • updated_before - include assignments updated before the given timestamp (in ISO 8601 format)
  • updated_after - include assignments updated after the given timestamp (in ISO 8601 format)

For example, to retrieve assignments filtered by workspace:

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

To request only active assignments:

curl "https://api.mavenlink.com/api/v1/assignments.json?current=true"

Ordering Assignments

Valid orders are:

  • created_at
  • updated_at

The default order is created_at:desc.

Getting a Single Assignment

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

Creating a new Assignment

The assignment parameter has two required attributes:

  • story_id the ID of the Story for which the assignment will be created
  • assignee_id the ID of the User for which the assignment will be created

There are two optional attributes:

  • current whether the assignment is active or not
  • estimated_minutes the number of minutes that the user is expected to work on this story

For example, to create a new assignment using curl for story ID 3 and user ID 5, who is expected to work for two hours on this story, run:

curl -H "Content-Type: application/json" --data-binary '{"assignment": {"story_id": 3, "assignee_id": 5, "current": true, "estimated_minutes": 120}}' "https://api.mavenlink.com/api/v1/assignments.json"

Updating an existing Assignment

An assignment that has already been created can be updated with an HTTP PUT request. Only optional attributes can be changed in an update.

For example, to update the assignment with ID 5 to be inactive using curl, run:

curl -X PUT -H "Content-Type: application/json" --data-binary '{"assignment": {"current": false}}' "https://api.mavenlink.com/api/v1/assignment/5.json"

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

Destroying an existing Assignment

Currently, assignments cannot be deleted via our API. Instead, mark assignments as inactive by updating the current attribute to false.