Project Templates

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 ID
• title - the title of the project template
• shared - whether or not the project template is shared with other users on the account other than the creator
• is_budgeted - whether or not the project template has financial attributes including overall budget, story budgets, and story time estimates
• budget - the estimated overall budget of the project associated with the template
• item_count - the number of stories (tasks) inside the project template
• duration - the estimated number of days that the associated project will take
• currency - the currency of the project template
• description - the description of the project template which does not map over to the project description when applied
• user_id - the id of the user who created the project template
• raw_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 field

Fetching Project Templates

You 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.

Optional Fields

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

Associated Objects

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.

Filtering Project Templates

The Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain project templates.

You return only templates created by the requesting user as follows:

curl "https://api.mavenlink.com/api/v1/project_templates.json?mine=true"

Ordering Project Templates

Valid orders are:

• title
• updated_at
• duration
• budget
• description
• is_budgeted

The default order is updated_at:desc.

Getting a Single Project Template

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.

Creating a Single Project Template

You can create a project template with the follow parameters:

• title - (required) the title of the new project template
• description - the description of the project template
• raw_json - (optional) a json hash that contains all the project templates tasks
• shared - (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 template
• currency - (optional) the currency of the project template (default: 'USD')
• duration - (optional) the estimated number of days that the associated project will take

You 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.

Updating an Existing Project Template

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 template
• description - the description of the project template
• raw_json - a json hash that contains all the project templates tasks
• shared - 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 template
• currency - the currency of the project template (default: 'USD')
• duration - the estimated number of days that the associated project will take

Project Template Stories (Tasks) - raw_json

All 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 story
• billable - the title of the project template
• relative_start_date - an integer that represents the start day of the task relative to the start of the project
• relative_due_date - an integer that represents the end day of the task relative to the start of the project
• duration - the number of days the task will take
• temp_id - the unique reference id for the story (used for dependencies)
• description - the task description
• budget_estimate_in_cents - an integer (whole number) that represents the budget estimate in cents of the story
• time_estimate_in_minutes - an integer (whole number) that represents the time estimate in minutes of the story

• sub_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 dependency
• target_id - the temp id of the second story (target story) in the dependency
• type - there are four types of dependencies numbered zero through three
  • 0 - start of the source story to start of the target story
  • 1 - start of the source story to finish of the target story
  • 2 - finish of the source story to start of the target story
  • 3 - finish of the source story to finish of the target story
• lag - an integer that represents the number of unused days that occur between the two tasks in the dependency

raw_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}]