
The Beta release of our documentation is available at:
http://developer.mavenlink.com/beta/
Project Templates are reusable sets of stories and project attributes that can be applied to new or existing projects.
Project Template objects have the following readable attributes:
id
- the internal project template IDtitle
- the title of the project templateshared
- whether or not the project template is shared with other users on the account other than the creatoris_budgeted
- whether or not the project template has financial attributes including overall budget, story budgets, and story time estimatesbudget
- the estimated overall budget of the project associated with the templateitem_count
- the number of stories (tasks) inside the project templateduration
- the estimated number of days that the associated project will takecurrency
- the currency of the project templatedescription
- the description of the project template which does not map over to the project description when applieduser_id
- the id of the user who created the project templateraw_json
- (Optional Field) a json hash that contains all the project templates tasks - See below for explanation on optional fields and go to the bottom for and explanation on the raw_json fieldYou can access all of the project templates that are visible to you through the API as follows:
curl "https://api.mavenlink.com/api/v1/project_templates.json"
The resulting JSON will be an array of objects. The entries will be sorted by the updated_at
field in descending order by default.
You cannot add optional fields to this request. In order to access the raw_json on a project template you must request a single template or use an only filter.
You can include project templates' optional fields with the optional_fields
param. Some fields are large and/or not necessary to be included in the index request.
curl "https://api.mavenlink.com/api/v1/project_templates/5.json?optional_fields=raw_json" - This will include the raw_json on a single project template
You can include project templates' associations with the include
param. A project template is associated with its own project template assignments (resources) and can be retrieved
curl "https://api.mavenlink.com/api/v1/project_templates.json?include=project_template_assignments" - This will include the project templates' associated resource assignments
See Object Associations to learn more. The following associations can be requested through the API:
user
- the user who created this project template, referenced by user_id
.project_template_assignments
- an array of project template assigment IDs associated with the project template.The Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain project templates.
Name | Type | Filters for project templates… |
---|---|---|
mine |
boolean | Restricts results to only project templates created by requesting user |
by_title |
string | With a title that matches a search string |
You return only templates created by the requesting user as follows:
curl "https://api.mavenlink.com/api/v1/project_templates.json?mine=true"
Valid orders are:
title
updated_at
duration
budget
description
is_budgeted
The default order is updated_at:desc
.
As with all resources, you can request either GET /api/v1/project_templates.json?only=5
or GET /api/v1/project_templates/5.json
.
curl "https://api.mavenlink.com/api/v1/project_templates.json&optional_fields=raw_json" - You can include optional fields by adding them into the params.
curl "https://api.mavenlink.com/api/v1/project_templates.json?only=18,17&optional_fields=raw_json" - Optional fields work with only queries.
You can create a project template with the follow parameters:
title
- (required) the title of the new project templatedescription
- the description of the project templateraw_json
- (optional) a json hash that contains all the project templates tasksshared
- (optional) whether or not the project template is shared with other users on the account other than the creator (default: false)is_budgeted
- (optional) whether or not the project template has financial attributes including overall budget, story budgets, and story time estimates (default: false)budget
- (optional) the estimated overall budget of the project associated with the templatecurrency
- (optional) the currency of the project template (default: 'USD')duration
- (optional) the estimated number of days that the associated project will takeYou can create project templates through the API as follows:
curl -d "project_template[title]=New Template" -d "project_template[description]=things we do in templates" "https://api.mavenlink.com/api/v1/project_templates.json"
The response will contain a JSON representation of the newly created project template or an error message indicating which arguments are missing or erroneous.
You can edit a Project Template as follows
curl -X PUT -d "project_template[title]=new title" "https://api.mavenlink.com/api/v1/project_templates/2.json"
When updating a project template you can modify the following attributes:
title
- (cannot be made blank) the title of the new project templatedescription
- the description of the project templateraw_json
- a json hash that contains all the project templates tasksshared
- whether or not the project template is shared with other users on the account other than the creator (default: false)is_budgeted
- whether or not the project template has financial attributes including overall budget, story budgets, and story time estimates (default: false)budget
- the estimated overall budget of the project associated with the templatecurrency
- the currency of the project template (default: 'USD')duration
- the estimated number of days that the associated project will takeAll of a project template's tasks are stored in an attribute located on the project template object called raw_json It is a JSON hash of all the stories that has been turned into a string and stored on the object
Stories within the JSON have the following attributes:
title
- the title of the storybillable
- the title of the project templaterelative_start_date
- an integer that represents the start day of the task relative to the start of the projectrelative_due_date
- an integer that represents the end day of the task relative to the start of the projectduration
- the number of days the task will taketemp_id
- the unique reference id for the story (used for dependencies)description
- the task descriptionbudget_estimate_in_cents
- an integer (whole number) that represents the budget estimate in cents of the storytime_estimate_in_minutes
- an integer (whole number) that represents the time estimate in minutes of the storysub_stories
- An nested array of sub stories that have the same structure as stories.
checklist
- an array of strings, each string being a checklist item on the story
EX: "checklist":["item one", "item two"]
tag_list
- a string with tags that are comma separated.
EX: "design, engineering, this has spaces"
This would give three tags. "design", "engineering", and "this has spaces"
assignments
- an array of objects with kay value pairs "assignee_id":id
EX: [{"assignee_id":100},{"assignee_id":101}]
This story would have two resources assigned to it. These are the IDs of two associated project template assignments. Project template assignments are associated objects.
dependencies
- an array of objects that represent a stories dependencies.
A dependency is an object that connects two stories and is used in our gantt charting. A dependency object lives in the dependencies array on its source story, not its target.Dependencies have the following attributes:
source_id
- the temp id of the first story (source story) in the dependencytarget_id
- the temp id of the second story (target story) in the dependencytype
- there are four types of dependencies numbered zero through three
lag
- an integer that represents the number of unused days that occur between the two tasks in the dependencyraw_json example:
[{"story_type":"task",
"billable":true,
"relative_start_date":1,
"relative_due_date":2,
"title":"Task One",
"temp_id":1,
"dependencies":[{"source_id":1, "target_id":2, "type":2, "lag":0}],
"description":"this is a task",
"assignments":[{"assignee_id":"26"}],
"tag_list":"difficult,easy",
"budget_estimate_in_cents":40000,
"time_estimate_in_minutes":1200,
"sub_stories":
[{"story_type":"task",
"billable":true,
"due_date":nil,
"start_date":nil,
"relative_start_date":1,
"relative_due_date":3,
"title":"Sub Task One",
"description":"this is a sub task",
"assignments":[{"assignee_id":"27"}],
"budget_estimate_in_cents":20000,
"time_estimate_in_minutes":300,
"temp_id":3}]},
{"story_type":"deliverable",
"billable":true,
"endDay":4,
"relative_start_date":1,
"relative_due_date":4,
"title":"Deliverable One",
"temp_id":2,
"description":"this is a deliverable",
"sub_stories":[]},
{"story_type":"milestone",
"billable":true,
"title":"Milestone One",
"description":"this is a milestone",
"weight":100,
"duration":0,
"relative_start_date":5,
"sub_stories":[],
"checklist":["item one", "item two"],
"temp_id":4}]