Name | sizeMetrics |
URI | /api/sizeMetrics |
URL Example | http://localhost:2468/api/sizeMetrics |
Description | This API makes it possible to store new actual size measurements into the Size Inventory Form for a team project. |
Context | Personal dashboard only, within the context of a Team Project |
HTTP Methods |
|
Adds a new row of actual size data to the Size Inventory Form.
This API can be called multiple times in succession to add multiple new rows to the Size Inventory Form. (Note: when multiple rows like these are present for a particular WBS item, they will be summed when the data is rolled up to the team level.)
At the moment, this API only supports size metrics recorded by an individual onto the Size Inventory Form of a team project. Other size metric types, such as the Size Estimating Template of a PSP task, are not currently supported. In addition, starting with dashboard version 2.5.3, team projects store size data in the WBS rather than the Size Inventory Form; such projects are not supported by this API either.
By default, invocations of this POST method will be rejected unless they originate from the same computer where the Process Dashboard is running. This policy can be disabled by setting an advanced preference with the name api.sizeMetrics.allowRemote and the value true.
Field | Type | Description |
---|---|---|
hierarchyPath (optional) | String | The full dashboard hierarchy path to the project and component/task where
the size metric should be stored. (Example:
/Project/My Team Project/Component A/Code).
The path must name a component or task within a team project. The root node of the team project is not allowed. If the personal project plan contains "PSP Task" objects, paths to/within those PSP task objects are also not allowed. Any other WBS item path is an acceptable target. (If in doubt, you can view a complete list of valid paths for a given team project by opening the Size Inventory Form and scrolling to the bottom of the page.) This parameter is optional. If omitted, the default is to use the path of the WBS task which is currently selected in the Process Dashboard toolbar. (But note: that currently selected task must also meet the criteria described above for the size measurement to be stored successfully.) |
description (optional) | String | A short, human readable description of this size measurement, which will be written into the Description field of the new Size Inventory Form row. (Example: "Perforce Changelist #1234") |
sizeUnits (optional) | String | The size units for this size measurement. The value must be a valid size
metric as defined in the metrics collection framework used by this Team
Project. (For a list of valid values, look at the drop-down list on the "Size
Units" field of the Size Inventory Form, and discard the "Inspected *"
variants.)
This value is optional; if omitted, the API will assume "New & Changed LOC." (The abbreviation "LOC" can also be used as an alias for this size metric.) |
actSize (required) | Number | The numeric size value which should be stored into the "Actual" column of the Size Inventory Form. |
notify (optional) | Boolean | If true, the Process Dashboard window will display a notification to the
user, letting them know that size measurements were added to their Size
Inventory Form. They will be able to click on the notification to see an
abbreviated version of the Size Inventory Form with the new rows highlighted.
If this API is called several times in rapid succession to add multiple size measures to a particular team project, the user will only see one notification summarizing all of the rows that were added. |
Error Code | Description |
---|---|
unsupported-target-path | The hierarchyPath parameter (or the current task path, if that parameter is missing) does not point to a legal node in a team project. See the requirements described in the "Request Parameters" table above. |
parameter-missing | The required actSize parameter was not supplied |
parameter-invalid | One of the parameters does not have a valid value:
|
application/json - successful completion
{ "stat" : "ok" } |
application/json - error example
{ "stat" : "fail" "err" : { "code" : "parameter-invalid", "msg" : "The 'actSize' parameter value 'one' is not a valid number", "param" : "actSize" } } |