Size Metrics API

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
  • POST - adds a new row of actual size data to the Size Inventory Form

HTTP POST

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.

Request Parameters

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

Errors

Error CodeDescription
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:
  • The actSize parameter is not a valid number
  • The sizeUnits parameter does not name a valid size metric in the metrics collection framework for this team project

Results

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"
    }
}