An iteration is also called a sprint in SCRUM terminology. It is a time period in which itmes must get accomplished. An item can only exist in one iteration. It can however be moved from one to another.

In Planbox an iteration is given a timeframe. It is a label identifying the iteration's time position relative to today. Six timeframes exist:

  • before_last: A past iteration. Planbox automatically creates these by moving the current iteration to history.
  • last: The last iteration is part of the history but its timeframe is specifically set to last.
  • current: The iteration currently being executed.
  • next: The iteration to come next. When a move to history is performed, the next iteration becomes the current.
  • after_next: If you created future iterations (after next), those will be labeled after_next.
  • backlog: The backlog is a special iteration. It is like an icebox containing unplanned items.

A product always has one current, one next and one backlog. Click here for an overview on iterations.


POST Arguments

  • product_id: The product to retrieve.
  • timeframe[]: Optional. An array of timeframes or a single timeframe. If omitted (and so is iteration_id), returns current, next, backlog and last.
  • iteration_id[]: Optional. Array of iteration ids to fetch or a single iteration id. If omitted, timeframe is used instead. You cannot specify both timeframe and iteration_id.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is an array of iteration objects on success or an error message string upon failure.

An iteration object has these attributes:

  • id: Unique iteration id.
  • num: Iteration sequence number. You can order iterations in time using this number.
  • start: Start date of the iteration.
  • end: End date of the iteration. Note: If timeframe is backlog, this is 0000-00-00.
  • timeframe: Iteration timeframe. Can be one of: before_last, last, current, next, after_next or backlog.
  • product_id: Parent product id.
  • baseline_date: Date of last baseline. See Iteration Baseline - Tracking Unplanned Work for mode information.
  • burndown: Burndown data object.
  • velocity: Velocity data object.

A Velocity object contains these attributes:

  • iteration_id: The iteration id in question. The velocity is for that iteration.
  • iteration_ids: The iterations averaged to calculate the velocity. Consists of the 3 previous iterations. For iterations with timeframes current, next, after_next and backlog, these are always the past 3 iterations. In the case you haven't yet accomplished 3 iterations, it is an average of the past iteration(s).
  • data: An array of velocity records for the entire product (first element in array) and each project in the product. Each record has these attributes:
  •  - object: Either product or project.
  •  - object_id: Product or project id.
  •  - estimate: Sum of estimate hours for all stories - completed or not.
  •  - estimate_done: Sum of estimate hours for all completed stories.
  •  - estimate_task_done: Sum of estimate hours for all completed tasks (whether the story was completed or not).
  •  - points: Sum of points for all stories - completed or not.
  •  - points_done: Sum of points for all completed stories.
  •  - value: Sum of business value for all stories - completed or not.
  •  - value_done: Sum of business value for all completed stories.

Javascript Example

Uses jQuery's post function to fetch the current iteration object for product id 1234.

$.post('https://work.planbox.com/api/get_iterations',
	{product_id:1234, timeframe:"current"}, 'json');