<< Back to GForge REST API

Entity: Tracker

GET

getAssignees

Get a list of possible assignees for tracker items on the given tracker. Items are always sorted by first name and last name (ascending).

Parameters (1)

Name Type Description
request \RequestParameters expected properties.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \UserBasic[]

Zero or more UserBasic records.

Example 1

Retrieve Tracker assignees for ID :
  GET http://api.mygforge.tld/tracker/232/assignees
{
    "paging": {
    "page_size": 20,
    "page_num": 1,
    "sort_field": "id",
    "sort_dir": "asc"
    },
    "items": [
    {
    "id": 33129,
    "unixName": "hectorpizarro",
    "password": null,
    "firstname": "Hector",
    "lastname": "Pizarro",
    "email": "hpizarro@gforgegroup.com",
    "timezone": "America/Buenos_Aires",
    "status": 1,
    "externalId": null,
    "isGroup": "N",
    "ccode": "AR",
    "language": "en   ",
    "theme": 1,
    "img_url": "/images/custom_avatars/33129.jpg",
    "html_url": "/gf/user/hectorpizarro/",
    "details_url": "/api/user/hectorpizarro/details",
    "isSiteAdmin": true,
    "api_url": "/api/user/hectorpizarro"
    },
    {
    "id": 14030,
    "unixName": "adriandelatabla",
    "password": null,
    "firstname": "Javier Adrián",
    "lastname": "Ortiz de la Tabla",
    "email": "atabla@gforgegroup.com",
    "timezone": "America/Buenos_Aires",
    "status": 1,
    "externalId": null,
    "isGroup": "N",
    "ccode": "AR",
    "language": "en   ",
    "theme": 1,
    "img_url": "/images/custom_avatars/14030.jpg",
    "html_url": "/gf/user/adriandelatabla/",
    "details_url": "/api/user/adriandelatabla/details",
    "isSiteAdmin": true,
    "api_url": "/api/user/adriandelatabla"
    },
    {
    "id": 8388,
    "unixName": "mpapayannis",
    "password": null,
    "firstname": "Mario",
    "lastname": "Papayannis",
    "email": "mpapayannis@gforgegroup.com",
    "timezone": "America/Buenos_Aires",
    "status": 1,
    "externalId": null,
    "isGroup": "N",
    "ccode": "AR",
    "language": "en   ",
    "theme": 1,
    "img_url": "/images/stock_avatars/default.png",
    "html_url": "/gf/user/mpapayannis/",
    "details_url": "/api/user/mpapayannis/details",
    "isSiteAdmin": true,
    "api_url": "/api/user/mpapayannis"
    },
    {
    "id": 5945,
    "unixName": "mtutty",
    "password": null,
    "firstname": "Michael",
    "lastname": "Tutty",
    "email": "MTUTTY@gforgegroup.com",
    "timezone": "America/Chicago",
    "status": 1,
    "externalId": null,
    "isGroup": "N",
    "ccode": "US",
    "language": "en   ",
    "theme": 1,
    "img_url": "/images/custom_avatars/5945.jpg",
    "html_url": "/gf/user/mtutty/",
    "details_url": "/api/user/mtutty/details",
    "isSiteAdmin": true,
    "api_url": "/api/user/mtutty"
    },
    {
    "id": 25868,
    "unixName": "tbibbs",
    "password": null,
    "firstname": "Tony",
    "lastname": "Bibbs",
    "email": "tbibbs@gforgegroup.com",
    "timezone": "US/Central",
    "status": 1,
    "externalId": null,
    "isGroup": "N",
    "ccode": "US",
    "language": "en   ",
    "theme": 1,
    "img_url": "/images/custom_avatars/25868.jpg",
    "html_url": "/gf/user/tbibbs/",
    "details_url": "/api/user/tbibbs/details",
    "isSiteAdmin": true,
    "api_url": "/api/user/tbibbs"
    }
    ],
    "links": []
  }

getDetails

Get detailed data for a specific Tracker, by specifying the DB Id for the requested object

Parameters (1)

Name Type Description
request \RequestParameters See description for details about expected properties.

Return: \gforge\plugins\tracker\models\api\TrackerDetail

A TrackerDetail structure if the tracker exists. Otherwise, a NotFoundException (404 response).

Name Type Description
isPublic boolean
restrictBrowse \boolean;
emailAllUpdates \boolean;
emailAddress \string;
emailAlias \string;
duePeriod \int;
fields array Contains the intrinsic fields and extra fields
settings array Contains pairs of key > value for various tracker settings
rel array
submitInstructions \string;
browseInstructions \string;
autoresponseInstructions \string;
id int Unique database identifier
project int Project id for this tracker
trackerName string Tracker Name
description string Tracker description
numItems int Amount of items
numItemsOpen int Amoung of open items;
trackerType int Tracker type;
details_url string Relative path to the tracker's detail data (API)
api_url string Relative path to the tracker's basic data (API)

Example 1

Retrieve Tracker details for ID, will only retrieve extra fields when rel paramater contains the 'fields' string:
  GET http://api.mygforge.tld/tracker/232/details

 {
  "isPublic": true,
  "restrictBrowse": "N",
  "emailAllUpdates": null,
  "emailAddress": "",
  "duePeriod": 2592000,
  "fields": {
    "priority": {
      "alias": "priority",
      "fieldName": "Priority",
      "fieldType": "4",
      "isRequired": false,
      "fieldOrder": 0,
      "useInQuickBrowse": false,
      "showOnSubmit": false,
      "defaultValue": "",
      "fieldElements": null,
      "isExtraField": false
    },
    "details": {
      "alias": "details",
      "fieldName": "Details",
      "fieldType": "4",
      "isRequired": false,
      "fieldOrder": 0,
      "useInQuickBrowse": true,
      "showOnSubmit": true,
      "defaultValue": "",
      "fieldElements": null,
      "isExtraField": false
    },
    "waiting_for": {
      "alias": "waiting_for",
      "fieldName": "Waiting For",
      "fieldType": "4",
      "isRequired": false,
      "fieldOrder": 0,
      "useInQuickBrowse": true,
      "showOnSubmit": true,
      "defaultValue": "",
      "fieldElements": null,
      "isExtraField": false
    },
    "open_date": {
      "alias": "open_date",
      "fieldName": "Open Date",
      "fieldType": "9",
      "isRequired": false,
      "fieldOrder": 0,
      "useInQuickBrowse": false,
      "showOnSubmit": false,
      "defaultValue": "",
      "fieldElements": null,
      "isExtraField": false
    },
    "close_date": {
      "alias": "close_date",
      "fieldName": "Close Date",
      "fieldType": "9",
      "isRequired": false,
      "fieldOrder": 0,
      "useInQuickBrowse": false,
      "showOnSubmit": false,
      "defaultValue": "",
      "fieldElements": null,
      "isExtraField": false
    },
    "foundinrelease": {
      "alias": "foundinrelease",
      "fieldName": "Found In Release",
      "fieldType": 8,
      "isRequired": true,
      "fieldOrder": 1,
      "useInQuickBrowse": false,
      "showOnSubmit": true,
      "defaultValue": null,
      "fieldElements": null,
      "isExtraField": true
    },
    "fixedinrelease": {
      "alias": "fixedinrelease",
      "fieldName": "Fixed In Release",
      "fieldType": 8,
      "isRequired": false,
      "fieldOrder": 2,
      "useInQuickBrowse": false,
      "showOnSubmit": false,
      "defaultValue": null,
      "fieldElements": null,
      "isExtraField": true
    },
    "resolution": {
      "alias": "resolution",
      "fieldName": "Resolution",
      "fieldType": 1,
      "isRequired": false,
      "fieldOrder": 3,
      "useInQuickBrowse": false,
      "showOnSubmit": false,
      "defaultValue": null,
      "fieldElements": [
       {
         "id": 469,
         "alias": null,
         "trackerExtraFieldId": null,
         "elementName": "Accepted",
         "statusId": 0,
         "defaultSelected": false,
         "sortOrder": 0,
         "autoAssignTo": 100,
         "canCommit": false
       },
       {
         "id": 470,
         "alias": null,
         "trackerExtraFieldId": null,
         "elementName": "Rejected",
         "statusId": 0,
         "defaultSelected": false,
         "sortOrder": 0,
         "autoAssignTo": 100,
         "canCommit": false
       },
       {
         "id": 471,
         "alias": null,
         "trackerExtraFieldId": null,
         "elementName": "Works For Me",
         "statusId": 0,
         "defaultSelected": false,
         "sortOrder": 0,
         "autoAssignTo": 100,
         "canCommit": false
       },
       {
         "id": 472,
         "alias": null,
         "trackerExtraFieldId": null,
         "elementName": "Postponed",
         "statusId": 0,
         "defaultSelected": false,
         "sortOrder": 0,
         "autoAssignTo": 100,
         "canCommit": false
       },
       {
         "id": 473,
         "alias": null,
         "trackerExtraFieldId": null,
         "elementName": "Out of date",
         "statusId": 0,
         "defaultSelected": false,
         "sortOrder": 0,
         "autoAssignTo": 100,
         "canCommit": false
       }],
   "isExtraField": true
   },
   "status": {
     "alias": "status",
     "fieldName": "Status",
     "fieldType": 7,
     "isRequired": true,
     "fieldOrder": 4,
     "useInQuickBrowse": true,
     "showOnSubmit": true,
     "defaultValue": null,
     "fieldElements": [
       {
         "id": 3053,
         "alias": null,
         "trackerExtraFieldId": null,
         "elementName": "Closed",
         "statusId": 0,
         "defaultSelected": false,
         "sortOrder": 0,
         "autoAssignTo": 100,
         "canCommit": false
       },
       {
         "id": 3052,
         "alias": null,
         "trackerExtraFieldId": null,
         "elementName": "Open",
         "statusId": 1,
         "defaultSelected": true,
         "sortOrder": 0,
         "autoAssignTo": 100,
         "canCommit": false
       }],
     "isExtraField": true
   }
   },
   "settings": {
     "emailAllUpdates": "N",
     "showAssociationsTab": "Y",
     "showDependenciesTab": "Y",
     "showDuplicatesTab": "Y",
     "showTagsTab": "Y",
     "showTimeTrackingTab": "Y",
     "sendAbbreviatedEmail": "N"
     },
   "id": 232,
   "project": {
     "id": 134,
     "name": null,
     "unixName": "msproject",
     "homepageUrl": "/gf/project/msproject/",
     "createDate": "2005-07-11 15:37:01 -0300",
     "isPublic": "N",
     "status": 1,
     "isTemplate": "N"
   },
   "trackerName": "Bugs",
   "description": "Bug Tracking System",
   "submitInstructions": "",
   "browseInstructions": "",
   "numItems": 20,
   "numItemsOpen": 1,
   "trackerType": 1,
   "details_url": "/api/tracker/232/detail",
   "api_url": "/api/tracker/232/detail",
   "parent": null
 }

getMembers

Get list of users with access to the tracker

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Wrapper class for the web request. It must contain a field called "id" in the route args or the request parameters.

Return: \User[]

List of users

getQueries

Get list of saved queries for a specific Tracker, by specifying the DB Id for the tracker. Tracker node contains the Tracker object data. 'queryFields' node contains an array with (type, id, field, value) for each query field. If no tracker id is defined method expects a projectId, it returns an array with all saved queries for the defined project.

Parameters (1)

Name Type Description
request \RequestParameters See description for details about expected properties.
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \models\api\TrackerQuery[]

Zero or more TrackerQuery records for a search. Zero or one TrackerQuery record for an id retrieval.

Example 1

Retrieve Queries for Tracker ID :
  GET http://api.mygforge.tld/tracker/232/queries

{
  "paging": {
  "page_size": 20,
  "page_num": 0,
  "sort_field": "id",
  "sort_dir": "asc"
  },
"items": [
 {
 "id": 493,
 "tracker": {...},
 "user": "tbibbs",
 "queryName": "Open Items",
 "isShared": true,
 "queryFields": {...}
 },
 {
 "id": 10219,
 "tracker": {...},
 "user": "tbibbs",
 "queryName": "6.2.1 Changelog",
 "isShared": true,
 "queryFields": {...}
 },
 {
 "id": 10444,
 "tracker": {...},
 "user": "tbibbs",
 "queryName": "6.3.0 Changelog",
 "isShared": true,
 "queryFields": {...}
 }
 ],
"links": []
 }
                                                            

getQuery

Get a single TrackerQuery (with all related objects) by its unique identifier. Related objects include the owner (user), tracker, project, trackerQueryFields and trackerQueryDisplayColumns

Parameters (2)

Name Type Description
subid int Unique identifier for the query. Note that the normal id parameter is reserved in this route for the tracker ID, but is ignored for this sub-entity.
query int Instead of "subid" in the route, above, the API will accept "query" in the querystring.

Return: \models\api\TrackerQuery

No return type is defined

getStats

Get summarized stats values for items within the specified Tracker.

Parameters (4)

Name Type Description
id int The unique identifier for the Tracker being summarized. Submitted as part of the route, e.g., /api/tracker/:id/stats
type string The type of summarization to be done. Only "count" and "burndown" is supported.
group_by string The alias (short name) of the intrinsic field or extra field on which to group the calculation. Supported values are "assignee", "priority", "statusId", "submittedBy".
other mixed Other filter parameters can be submitted in the typical query string format name=value, e.g., &statusId=1. Only single-value filters can be submitted, and fields and values must have aliases or text values (i.e., no IDs)

Return: \StdClass

Zero or more StatsBasic records with the requested calculations.

getTracker

Searches for trackers matching criteria, or retrieves a specific tracker by ID

Returns 0 or more TrackerBasic models in an array, if a search is being made. If a specific Tracker is requested by passing the db ID, it will return either null or the Tracker object. Parameters the service accepts for performing a search:


Parameters (9)

Name Type Description
request \RequestParameters See description for details
sort_field string List of fields to sort by (In search requests). Defined in apimodels\TrackerBasic. Default is 'trackerName'. It could be id, trackerName.
sort_dir string Direction to sort. It could be asc or desc. Default is 'asc'.
page_num int Requested page. By default page=0 is requested.
page_size int Number of entries to show per request. Default is 20.
id int Unique database identifier. If id is specified, the rest of the filters will be ignored.
trackerName string Tracker Name.
description string Tracker description.
project int Project id for this tracker.
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Related Entities (1)

Return: \models\api\TrackerBasic

| models\api\TrackerBasic[] Zero or more TrackerBasic records for a search. Zero or one TrackerBasic record for an id retrieval.

Example 1

Find a tracker by matching name:
  GET http://api.mygforge.tld/tracker/?trackerName=gforge

[
 {
  "id": 10237,
  "project": 138,
  "trackerName": "GForge Support",
  "description": "GForge Support Tracker",
  "submitInstructions": "

The GForge Group works hard to ensure we provide the best possible support to customers. You can add new tickets using the form below or you can simply send an email to support@gforgegroup.com.  Please note that email with attachments will be automatically attached to your support ticket. Also, be sure to check out our Knowledge Base for answers to the most common questions.

\n", "browseInstructions": "", "numItems": 3027, "numItemsOpen": 51, "trackerType": 3, "details_url": "/api/tracker/10237/detail", "api_url": "/api/tracker/10237" } ]

Example 2

Find a tracker by database ID:
  GET http://api.mygforge.tld/tracker/355

{
 "id": 355,
 "project": 138,
 "trackerName": "GForge",
 "description": "All tasks for future versions of GForge",
 "submitInstructions": "",
 "browseInstructions": "",
 "numItems": 4438,
 "numItemsOpen": 571,
 "trackerType": 2,
 "details_url": "/api/tracker/355/detail",
 "api_url": "/api/tracker/355"
}

Example 3

List all trackers in a project:
  GET http://api.mygforge.tld/tracker/?project=1

[
 {"id":232,"project":134,"trackerName":"Bugs","description":"Bug Tracking System","submitInstructions":"",
 "browseInstructions":"","numItems":20,"numItemsOpen":1,"trackerType":1,
 "details_url":"\/api\/tracker\/232\/detail","api_url":"\/api\/tracker\/232"},
 {"id":235,"project":134,"trackerName":"Feature Requests","description":"Feature Request Tracking System",
 "submitInstructions":"","browseInstructions":"","numItems":0,"numItemsOpen":0,"trackerType":1,
 "details_url":"\/api\/tracker\/235\/detail","api_url":"\/api\/tracker\/235"},
 {"id":337,"project":134,"trackerName":"Next Release","description":"Items For Our Next Release",
 "submitInstructions":"","browseInstructions":"","numItems":0,"numItemsOpen":0,"trackerType":2,
 "details_url":"\/api\/tracker\/337\/detail","api_url":"\/api\/tracker\/337"},
 {"id":234,"project":134,"trackerName":"Patches","description":"Patch Tracking System","submitInstructions":"",
 "browseInstructions":"","numItems":0,"numItemsOpen":0,"trackerType":1,
 "details_url":"\/api\/tracker\/234\/detail","api_url":"\/api\/tracker\/234"},
 {"id":233,"project":134,"trackerName":"Support Requests","description":"Tech Support Tracking System",
 "submitInstructions":"","browseInstructions":"","numItems":1,"numItemsOpen":1,"trackerType":1,
 "details_url":"\/api\/tracker\/233\/detail","api_url":"\/api\/tracker\/233"},
 {"id":336,"project":134,"trackerName":"To Do","description":"Things We Have To Do","submitInstructions":"",
 "browseInstructions":"","numItems":3,"numItemsOpen":2,"trackerType":2,
 "details_url":"\/api\/tracker\/336\/detail","api_url":"\/api\/tracker\/336"},
 {"id":9237,"project":134,"trackerName":"unittest","description":"Test Create Subproject",
 "submitInstructions":"","browseInstructions":"","numItems":0,"numItemsOpen":0,"trackerType":2,
 "details_url":"\/api\/tracker\/9237\/detail","api_url":"\/api\/tracker\/9237"}
]

getWorkflow

Returns an array with all the extra fields with enabled workflow transitions (useWorfklow=true) and a collection of the allowed elements for each tracker extra field state.

Parameters (1)

Name Type Description
request \RequestParameters

Return: array

of TrackerExtraField with TrackerExtraFieldElements

Example 1

  GET http://api.mygforge.tld/api/tracker/355/workflow
 
{
"paging": {
"page_size": 20,
"page_num": 1,
"sort_field": "id",
"sort_dir": "asc"
},
"items": [
{
"alias": "status",
"fieldName": "Status",
"fieldType": 7,
"isRequired": true,
"fieldOrder": 0,
"useInQuickBrowse": true,
"showOnSubmit": true,
"defaultValue": null,
"fieldElements": [
{
 "id": 3244,
 "alias": "",
 "label": "Awaiting Assignment",
 "statusId": 1,
 "defaultSelected": true,
 "sortOrder": 0,
 "toElements": [
    {
     "id": 238970,
     "alias": "",
     "label": "Accepted",
     "statusId": 1,
     "defaultSelected": false,
     "sortOrder": 1
    },
   {
     "id": 238967,
     "alias": "",
     "label": "Blocked\/Waiting For",
     "statusId": 1,
     "defaultSelected": false,
     "sortOrder": 2
   },
   {
     "id": 238969,
     "alias": "",
     "label": "Won't Fix",
     "statusId": 0,
     "defaultSelected": false,
     "sortOrder": 7
   }
}
...
"links": []
}

POST

postDetails

Parameters (0)

Name Type Description
No parameters

Return: (none)

No return type is defined

postFields

Saves/updates one or more tracker extra fields

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters See description for details about expected properties.

Return: (none)

No return type is defined

postProjectquery

Stores as a user preference the defined project saved query for this user. Expected parameters are: - projectId - queryId User preference stores the queryId named: 'query_project_' . $projectId

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: \gforge\core\models\api\UserPreferenceBasic

Contains userPreference id

Name Type Description
preferenceName string
setDate string
preferenceValue string Date when the account was created
user \gforge\core\models\api\UserBasic

postQuery

Create or update a single TrackerQuery

Parameters (1)

Name Type Description
\models\api\TrackerQuery The fields and relations of the TrackerQuery entity. For existing queries, the tracker, project and user relations are ignored.

Return: \models\api\TrackerQuery

The updated query, same output as getQuery(subId) above.

postWorkflow

Takes workflow settings for a collection of fields and persists it

Parameters (1)

Name Type Description
request \RequestParameters

Return: null

No return type is defined

Example 1

  GET http://api.mygforge.tld/api/tracker/355/workflow
 
"workflow": {
  "fields: [
     {
     "alias": "status",
     "fieldName": "Status",
     "fieldType": 7,
     "isRequired": true,
     "fieldOrder": 0,
     "useInQuickBrowse": true,
     "showOnSubmit": true,
     "defaultValue": null,
     "fieldElements": [
     {
      "id": 3244,
      "alias": "",
      "label": "Awaiting Assignment",
      "statusId": 1,
      "defaultSelected": true,
      "sortOrder": 0,
      "toElements": [
      {
         "id": 238970,
         "alias": "",
         "label": "Accepted",
         "statusId": 1,
         "defaultSelected": false,
         "sortOrder": 1
       },
       {
         "id": 238967,
         "alias": "",
         "label": "Blocked\/Waiting For",
         "statusId": 1,
         "defaultSelected": false,
         "sortOrder": 2
     }]
     }
   ]
}

PUT

PUT is not available

DELETE

deleteFields

Deletes one tracker extra field

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters See description for details about expected properties.

Return: (none)

No return type is defined

deleteQuery

Deletes a tracker query

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters See description for details about expected properties.

Return: (none)

No return type is defined

deleteTracker

Deletes a tracker

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters See description for details about expected properties.

Return: (none)

No return type is defined

deleteWorkflow

Deletes the associated workflow for a given field

Parameters (1)

Name Type Description
request \RequestParameters

Return: null

No return type is defined