<< Back to GForge REST API

Entity: Project

GET

getActivity

Get the activity metrics for this project.

Parameters (3)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/activity).
start string The start date/time for activity data to be returned. If empty or false, defaults to two weeks ago.
end string The end date/time for activity data. If empty or false, defaults to tomorrow.

Return: \gforge\core\models\api\StatsBasic

Zero or more records, containing the time-series data between the specified start and end dates.

Name Type Description
statDate \datetimetz Time stamp for the measure
title string Human-readable name of the measure
measure float The actual numeric measurement
section string Type of the associated object, if any
refId int Id of associated object, if any
url string Url associated with the stat, if any

getActivitylog

Get recent activity log data for the specified Project

Parameters (1)

Name Type Description
id mixed The database ID or unix name for the project to be retrieved. This is specified in the route, e.g., /api/project/:id-or-unix-name/details

Return: \gforge\core\models\api\ActivityLogBasic

An array of ActivityLogBasic structures

Name Type Description
id int Unique database field for the activity log
date \datetimetz Date and time of the log
section string Type of the associated object
refId int Id of object associated with this activity log
description string Description of the action that was logged
activityType string Type of activity
url string Url associated with the log
userApiUrl string Api url of user
projectApiUrl String Api url of project
userId int Unique identifier for the user
project \models\Project
projectId int
extendedData object Additional information about the target of this activity record (e.g., tracker item, document, wiki page, user, etc.). Fields and format depend on the target object.

Example 1

Basic request
  GET http://api.mygforge.tld/project/gforge5/activitylog
  or
  GET http://api.mygforge.tld/project/138/activitylog

    {
     "activity_log":[
        {
           "id":388241,
           "date":"2014-11-18 10:37:52 -0600",
           "section":"project",
           "refId":138,
           "description":"joined chat",
           "activityType":"join",
           "url":null,
           "userApiUrl":"\/api\/user\/25868",
           "projectApiUrl":"\/api\/project\/138",
           "userId":25868,
           "projectId":138,
           "user":{
              "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"
           },
           "subItems":[
              {
                 "id":388236,
                 "date":"2014-11-18 10:11:15 -0600",
                 "section":"project",
                 "refId":138,
                 "description":"joined chat",
                 "activityType":"join",
                 "url":null,
                 "userApiUrl":"\/api\/user\/33887",
                 "projectApiUrl":"\/api\/project\/138",
                 "userId":33887,
                 "projectId":138,
                 "user":{
                    "id":33887,
                    "unixName":"cvizcaya",
                    "password":null,
                    "firstname":"Celina",
                    "lastname":"Vizcaya",
                    "email":"cvizcaya@gforgegroup.com",
                    "timezone":"America\/Buenos_Aires",
                    "status":1,
                    "externalId":null,
                    "isGroup":"N",
                    "ccode":"AR",
                    "language":"en",
                    "theme":1,
                    "img_url":"\/images\/custom_avatars\/33887.jpg",
                    "html_url":"\/gf\/user\/cvizcaya\/",
                    "details_url":"\/api\/user\/cvizcaya\/details",
                    "isSiteAdmin":false,
                    "api_url":"\/api\/user\/cvizcaya"
                 }
              },
              ...
              {
                 "id":388186,
                 "date":"2014-11-18 05:59:42 -0600",
                 "section":"project",
                 "refId":138,
                 "description":"joined chat",
                 "activityType":"join",
                 "url":null,
                 "userApiUrl":"\/api\/user\/14030",
                 "projectApiUrl":"\/api\/project\/138",
                 "userId":14030,
                 "projectId":138,
                 "user":{
                    "id":14030,
                    "unixName":"adriandelatabla",
                    "password":null,
                    "firstname":"Javier Adri\u00e1n",
                    "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"
                 }
              }
           ]
        }
     ]
  }

getBuilds

Gets the most recent build from each job associated with the project.

Parameters (1)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/chat).

Return: \gforge\plugins\build\models\api\BuildBasic[]

Array of the most recent builds associated with the project.

getChat

Get a reference to the project chat thread.

Parameters (1)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/chat).

Return: \gforge\plugins\forum\models\api\ForumBasic

The forum and thread for this project's chat room.

Name Type Description
id int Unique database identifier for the forum
section string section the forum belongs to
refId int ID of the referenced object
forumName string Name of the forum
description string Description of the forum
isPublic boolean Determines if the forum is for public access or private
sendAllPostsTo string The comma separated list of emails to send posts to
threadCount int The number of child threads in this forum (read-only)
messageCount int The total number of messages in this forum, across all threads (read-only)
mostRecentDate \DateTime The date of the last message posting in this forum, across all threads (read-only)
moderationLevel int The level of moderation for this forum, across all threads. (read-only) 0 = no postings are held for moderation, 1 = postings from non-project members are moderated, 3 = postings from non-forum-admins are moderated.
forumThreads \gforge\plugins\forum\models\api\ForumThreadBasic Zero or more threads that belong to this forum (optional data)

getCustomsplash

Gets the useCustomSplash setting for a given project or false if none

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object.

Return: mixed

value of useCustomSplash project setting

getDetails

Get the detailed data for a specific project. Callers may specify the unixName or the database id in the id parameter.

Parameters (1)

Name Type Description
id mixed The database ID or unix name for the project to be retrieved. This is specified in the route, e.g., /api/project/:id-or-unix-name/details

Related Entities (6)

Return: \gforge\core\models\api\ProjectDetail

A ProjectDetail structure if the project exists. Otherwise, a NotFoundException.

Name Type Description
registerPurpose string Returns the purpose for this project
udf1 string Returns special field 1
udf2 string Returns special field 2
udf3 string Returns special field 3
udf4 string Returns special field 4
udf5 string Returns special field 5
udf6 string Returns special field 6
isWorkflowScriptEnabled boolean Returns 'Y' if enabled, 'N' otherwise
id int Unique database identifier for the project
name string Name of the project
unixName string Short, unix-friendly identifier for the project. This is usually also the project's shell logon.
description string Public description for the project
homepageUrl string GFAS url for the project
createDate \date Date of project creation
isPublic string Returns "Y" if the project is public, "N" otherwise
status string Returns the status code for the project
isTemplate string Returns "Y" if the project is a template
templateProjectId int Returns the project used as template for this project
parentProjectId int Returns the parent project id for this project --- used as output, not allowed for input
averageRating int Returns the average rate for the project

Example 1

Get the project details. The unix name or ID can be used.
  GET http://api.mygforge.tld/project/gforge5/details
  or
  GET http://api.mygforge.tld/project/138/details
{
 "registerPurpose":"This is a testing ground for technologies and demo code for the complete from-scratch rewrite of GForge using PHP5 technology.",
 "udf1":null,
 "udf2":null,
 "udf3":null,
 "udf4":null,
 "udf5":null,
 "udf6":null,
 "isWorkflowScriptEnabled":null,
 "plugins":[
    "tracker",
    "docman",
    "frs",
    "mailman",
    "build",
    "wiki",
    "scmgit",
    "forum",
    "news"
 ],
 "id":138,
 "name":"GForge AS",
 "unixName":"gforge5",
 "description":"We Believe in Great Software.  For over two decades GForge has helped software organizations deliver their ideas to market faster using their own process.  The project is the core GForge project and it has two active efforts.  The first is maintenance on the existing GForge product and the second is delivering the next generation of GForge.  ",
 "homepageUrl":"\/gf\/project\/gforge5\/",
 "createDate":"2005-10-10 01:37:46 -0500",
 "isPublic":"Y",
 "status":1,
 "isTemplate":"N",
 "templateProjectId":0,
 "rel":[
 ]
}

Example 2

Get the project details, with all associated related data.
  GET http://api.mygforge.tld/project/gforge5/details?rel=admins,members,activity_stats,activity_log,trackers
  or
  GET http://api.mygforge.tld/project/138/details?rel=admins,members,activity_stats,activity_log,trackers
{
    "registerPurpose":"This is a testing ground for technologies and demo code for the complete from-scratch rewrite of GForge using PHP5 technology.",
     "udf1":null,
     "udf2":null,
     "udf3":null,
     "udf4":null,
     "udf5":null,
     "udf6":null,
     "isWorkflowScriptEnabled":null,
     "plugins":[
        "tracker",
        "docman",
        "frs",
        "mailman",
        "build",
        "wiki",
        "scmgit",
        "forum",
        "news"
     ],
     "id":138,
     "name":"GForge AS",
     "unixName":"gforge5",
     "description":"We Believe in Great Software.  For over two decades GForge has helped software organizations deliver their ideas to market faster using their own process.  The project is the core GForge project and it has two active efforts.  The first is maintenance on the existing GForge product and the second is delivering the next generation of GForge.  ",
     "homepageUrl":"\/gf\/project\/gforge5\/",
     "createDate":"2005-10-10 01:37:46 -0500",
     "isPublic":"Y",
     "status":1,
     "isTemplate":"N",
     "templateProjectId":0,
     "rel":{
        "admins":[
           {
              "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"
           }
        ],
        "members":[
           {
              "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",
              "roles":[
                 {
                    "id":9173,
                    "name":"GForge Customer"
                 }
              ]
           },
           {
              "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",
              "roles":[
                 {
                    "id":9173,
                    "name":"GForge Customer"
                 }
              ]
           },
           {
              "id":33229,
              "unixName":"kbibbs",
              "password":null,
              "firstname":"Kate",
              "lastname":"Bibbs",
              "email":"kate@gforgegroup.com",
              "timezone":"US\/Central",
              "status":1,
              "externalId":null,
              "isGroup":"N",
              "ccode":"US",
              "language":"en",
              "theme":1,
              "img_url":"\/images\/stock_avatars\/default.png",
              "html_url":"\/gf\/user\/kbibbs\/",
              "details_url":"\/api\/user\/kbibbs\/details",
              "isSiteAdmin":false,
              "api_url":"\/api\/user\/kbibbs",
              "roles":[
                 {
                    "id":9173,
                    "name":"GForge Customer"
                 }
              ]
           }
        ],
        "chat":{
           "id":8595,
           "section":"project",
           "refId":138,
           "forumName":"GForge AS",
           "isPublic":false,
           "threadCount":1,
           "messageCount":89745,
           "mostRecentDate":"2014-12-02 20:08:08 -0600",
           "moderationLevel":0,
           "forumThreads":[
              {
                 "id":5367,
                 "threadName":"Discussion",
                 "messageCount":89745,
                 "mostRecentDate":"2014-12-02 17:16:32 -0600",
                 "isLocked":"N"
              }
           ]
        },
         "activity_stats":[
           {
              "statDate":"2014-11-04",
              "title":"Activity",
              "measure":0,
              "section":"project",
              "refId":"gforge5",
              "url":""
           },
           {
              "statDate":"2014-11-05",
              "title":"Activity",
              "measure":0,
              "section":"project",
              "refId":"gforge5",
              "url":""
           },
           ...         {
              "statDate":"2014-11-18",
              "title":"Activity",
              "measure":0,
              "section":"project",
              "refId":"gforge5",
              "url":""
           },
           {
              "statDate":"2014-11-19",
              "title":"Activity",
              "measure":0,
              "section":"project",
              "refId":"gforge5",
              "url":""
           }
        ],
        "activity_log":[
           {
              "id":388241,
              "date":"2014-11-18 10:37:52 -0600",
              "section":"project",
              "refId":138,
              "description":"joined chat",
              "activityType":"join",
              "url":null,
              "userApiUrl":"\/api\/user\/25868",
              "projectApiUrl":"\/api\/project\/138",
              "userId":25868,
              "projectId":138,
              "user":{
                 "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"
              },
              "subItems":[
                 {
                    "id":388236,
                    "date":"2014-11-18 10:11:15 -0600",
                    "section":"project",
                    "refId":138,
                    "description":"joined chat",
                    "activityType":"join",
                    "url":null,
                    "userApiUrl":"\/api\/user\/33887",
                    "projectApiUrl":"\/api\/project\/138",
                    "userId":33887,
                    "projectId":138,
                    "user":{
                       "id":33887,
                       "unixName":"cvizcaya",
                       "password":null,
                       "firstname":"Celina",
                       "lastname":"Vizcaya",
                       "email":"cvizcaya@gforgegroup.com",
                       "timezone":"America\/Buenos_Aires",
                       "status":1,
                       "externalId":null,
                       "isGroup":"N",
                       "ccode":"AR",
                       "language":"en",
                       "theme":1,
                       "img_url":"\/images\/custom_avatars\/33887.jpg",
                       "html_url":"\/gf\/user\/cvizcaya\/",
                       "details_url":"\/api\/user\/cvizcaya\/details",
                       "isSiteAdmin":false,
                       "api_url":"\/api\/user\/cvizcaya"
                    }
                 },
                 ...               {
                    "id":388186,
                    "date":"2014-11-18 05:59:42 -0600",
                    "section":"project",
                    "refId":138,
                    "description":"joined chat",
                    "activityType":"join",
                    "url":null,
                    "userApiUrl":"\/api\/user\/14030",
                    "projectApiUrl":"\/api\/project\/138",
                    "userId":14030,
                    "projectId":138,
                    "user":{
                       "id":14030,
                       "unixName":"adriandelatabla",
                       "password":null,
                       "firstname":"Javier Adri\u00e1n",
                       "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"
                    }
                 }
              ]
           }
        ],
        "trackers":[
           {
              "tracker_id":10109,
              "tracker_name":"Licenses",
              "is_public":false,
              "restrict_browse":false,
              "total_count":244,
              "open_count":172,
              "closed_count":72,
              "assigned_to_me":0,
              "access_level":10
           },
           {
              "tracker_id":355,
              "tracker_name":"GForge",
              "is_public":false,
              "restrict_browse":false,
              "total_count":5249,
              "open_count":656,
              "closed_count":4593,
              "assigned_to_me":3,
              "access_level":0
           },
           {
              "tracker_id":10237,
              "tracker_name":"GForge Support",
              "is_public":false,
              "restrict_browse":false,
              "total_count":3435,
              "open_count":39,
              "closed_count":3396,
              "assigned_to_me":1,
              "access_level":10
           },
           {
              "tracker_id":10345,
              "tracker_name":"Free Support",
              "is_public":true,
              "restrict_browse":false,
              "total_count":6,
              "open_count":6,
              "closed_count":0,
              "assigned_to_me":1,
              "access_level":10
           },
           {
              "tracker_id":10311,
              "tracker_name":"Managed Servers",
              "is_public":false,
              "restrict_browse":false,
              "total_count":13,
              "open_count":12,
              "closed_count":1,
              "assigned_to_me":0,
              "access_level":10
           },
           {
              "tracker_id":10292,
              "tracker_name":"User Stories",
              "is_public":false,
              "restrict_browse":false,
              "total_count":69,
              "open_count":28,
              "closed_count":41,
              "assigned_to_me":0,
              "access_level":10
           },
           {
              "tracker_id":9662,
              "tracker_name":"Build Failures",
              "is_public":false,
              "restrict_browse":false,
              "total_count":0,
              "open_count":0,
              "closed_count":0,
              "assigned_to_me":0,
              "access_level":10
           },
           {
              "tracker_id":10661,
              "tracker_name":"Business Development",
              "is_public":false,
              "restrict_browse":false,
              "total_count":3589,
              "open_count":3523,
              "closed_count":66,
              "assigned_to_me":0,
              "access_level":99
           }
        ],
        "disk":[
           {
              "checkDate":{
                 "date":"2018-04-08 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":3394
           },
           {
              "checkDate":{
                 "date":"2018-04-07 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":3394
           },
           {
              "checkDate":{
                 "date":"2009-05-17 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":68593
           },
           {
              "checkDate":{
                 "date":"2009-01-12 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":68593
           },
           {
              "checkDate":{
                 "date":"2008-12-19 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":68593
           },
           {
              "checkDate":{
                 "date":"2008-10-24 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":68593
           },
           {
              "checkDate":{
                 "date":"2008-09-24 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":68593
           },
           {
              "checkDate":{
                 "date":"2008-09-23 00:00:00.000000",
                 "timezone_type":3,
                 "timezone":"UTC"
              },
              "bytes":68593
           }
        ]
     }
  }

getForums

Get the forums that belong to the project.

Parameters (1)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/forums).

Return: \gforge\plugins\forum\models\api\ForumBasic[]

Zero or more forums that are part of this project.

getInvite

Searches for users matching criteria who have been invited to the project, or retrieves all of them.

Parameters (8)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/invites).
start int The (zero-based) row index of the first record to include in the result set.
firstname string The user name.
lastname string The user lastname.
email string The email of the user.
unixName string The email of the user.
search string string we want to search for. Search as firstname, lastname, email and unixName
max int Maximum number of records to return in the result.

Return: array

Zero or more items with limited data (userEmail, roleId), paged by the $start and $max parameters, sorted by unix name

Example 1

Get the users who requested to join the project.
  GET http://api.mygforge.tld/project/gforge5/invites?page_size=2&page_num=1
  or
  GET http://api.mygforge.tld/project/138/invites?page_size=2&page_num=1

{
"paging": {
        "page_size": 2,
        "page_num": 1,
        "sort_field": "id",
        "sort_dir": "asc"
},
"items": [{
	"userEmail": "cvizcaya2@rbmwebsolutions.com",
	"roleId": "9661"
},
{
	"userEmail": "cvizcaya@rbmwebsolutions.com",
	"roleId": "167"
}],
"links": []
}

Example 2

Get the users invited with firstname 'Celina'.
  GET http://api.mygforge.tld/project/gforge5/invites?firstname=Celina

{
"paging": {
        "page_size": 20,
        "page_num": 1,
        "sort_field": "id",
        "sort_dir": "asc"
},
"items": [{
	"userEmail": "cvizcaya2@rbmwebsolutions.com",
	"roleId": "9661"
}],
"links": []
}

Example 3

Get the users invited that matched with 'Celina'.
  GET http://api.mygforge.tld/project/gforge5/invites?search=Celina

{
"paging": {
        "page_size": 20,
        "page_num": 1,
        "sort_field": "id",
        "sort_dir": "asc"
},
"items": [{
	"userEmail": "cvizcaya2@rbmwebsolutions.com",
	"roleId": "9661"
},
{
	"userEmail": "celina.vizcaya@gmail.com",
	"roleId": "9752"
}],
"links": []
}

getJoinRequests

Get the users who requested to join the project.

Parameters (8)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/members).
start int The (zero-based) row index of the first record to include in the result set.
max int Maximum number of records to return in the result.
firstname string The user name.
lastname string The user lastname.
email string The email of the user.
unixName string The email of the user.
search string string we want to search for. Search as firstname, lastname, email and unixName

Return: \gforge\core\models\User

Zero or more user records, paged by the $start and $max parameters, sorted by unix name

Example 1

Get the users who requested to join the project.
  GET http://api.mygforge.tld/project/gforge5/joinRequestUsers?page_size=2&page_num=1
  or
  GET http://api.mygforge.tld/project/138/joinRequestUsers?page_size=2&page_num=1

{
"paging": {
        "page_size": 2,
        "page_num": 1,
        "sort_field": "id",
        "sort_dir": "asc"
},
"items": [{
        "id": 33296,
        "unixName": "clsfrance",
        "password": null,
        "firstname": "CLS - Pirotta Group",
        "lastname": "   ",
        "email": "aef94baf84110a548528e6a00570c656@gforge.com",
        "timezone": "US\/Central",
        "status": 1,
        "externalId": null,
        "isGroup": "Y",
        "ccode": "US",
        "language": "en   ",
        "theme": 1,
        "img_url": "\/images\/stock_avatars\/default.png",
        "html_url": "\/gf\/user\/clsfrance\/",
        "details_url": "\/api\/user\/clsfrance\/details",
        "isSiteAdmin": false,
        "api_url": "\/api\/user\/clsfrance"
},
{
        "id": 34056,
                "unixName": "lolta45",
        "password": null,
                "firstname": "lolta",
        "lastname": "lolta",
                "email": "mcvmendoza@hotmail.com",
        "timezone": "UTC",
        "status": 1,
        "externalId": null,
        "isGroup": "N",
        "ccode": "US",
        "language": "en   ",
        "theme": 1,
        "img_url": "\/images\/stock_avatars\/default.png",
        "html_url": "\/gf\/user\/lolta\/",
        "details_url": "\/api\/user\/lolta\/details",
        "isSiteAdmin": false,
        "api_url": "\/api\/user\/lolita"
}],
"links": []
}

Example 2

Get the users who requested to join the project and matched with Michael.
  GET http://api.mygforge.tld/project/gforge5/joinRequestUsers?search=Michael

{
"paging": {
	"page_size": 20,
	"page_num": 1,
	"sort_field": "id",
	"sort_dir": "asc"
},
"items": [{
	"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": "\/api\/user\/mtutty\/avatar",
	"html_url": "\/#\/user\/mtutty\/",
	"details_url": "\/api\/user\/mtutty\/details",
	"isSiteAdmin": true,
	"api_url": "\/api\/user\/mtutty"
}],
"links": []
}

getMembers

Get the members that belong to the project.

Parameters (9)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/members).
start int The (zero-based) row index of the first record to include in the result set.
max int Maximum number of records to return in the result.
type string The type of member list to generate. Default is all members,or 'standup' for standup-eligible users.
firstname string The user name.
lastname string The user lastname.
email string The email of the user.
unixName string The email of the user.
search string string we want to search for. Search as firstname, lastname, email and unixName

Related Entities (1)

Return: \gforge\core\models\api\UserBasic

Zero or more user records and roles data into the project, paged by the $start and $max parameters, sorted by unix name

Name Type Description
id int Unique database identifier for the user
unixName string Short, unix-friendly identifier for the user. This is usually also the user's shell logon.
password string Shared secret for authenticating the user. This value is only set for requests, not for responses.
firstname string First name for the user
lastname string Last name for the user
email string Email address for the user
timezone string Name of the user's time zone (from PHP std list)
status \Account status, 0 = Pending, 1 = Active, 2 = Deleted
externalId string Custom external identifier for use in sync to other systems
isGroup string Y if the specified record is a group, N if it is a single user
ccode string
language \type
theme mixed
img_url string Relative path to the user's icon, if any
html_url string Relative path to the user's details page (display)
details_url string Relative path to the user's detail data (API)
isSiteAdmin boolean
api_url string Relative path to the user's basic data (API)

Example 1

Get the members for the project.
  GET http://api.mygforge.tld/project/gforge5/members?page_size=2&page_num=1
  or
  GET http://api.mygforge.tld/project/138/members?page_size=2&page_num=1

{
"paging": {
	"page_size": 2,
	"page_num": 1,
	"sort_field": "id",
	"sort_dir": "asc"
},
"items": [{
	"id": 33229,
	"unixName": "kbibbs",
	"password": null,
	"firstname": "Kate",
	"lastname": "Bibbs",
	"email": "kate@gforgegroup.com",
	"timezone": "US\/Central",
	"status": 1,
	"externalId": null,
	"isGroup": "N",
	"ccode": "US",
		"language": "en   ",
	"theme": 1,
		"img_url": "\/images\/stock_avatars\/default.png",
	"html_url": "\/gf\/user\/kbibbs\/",
		"details_url": "\/api\/user\/kbibbs\/details",
	"isSiteAdmin": false,
	"api_url": "\/api\/user\/kbibbs"
         "roles": [{
             "id": 9173,
             "name": "GForge Customer"
	}]
},
{
	"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"
         "roles": [{
             "id": 9173,
             "name": "GForge Customer"
	}]
}],
"links": []
}
* @example Get the members for the project with firstname Michael.
  GET http://api.mygforge.tld/project/gforge5/members?firstname=Michael

{
"paging": {
	"page_size": 20,
	"page_num": 1,
	"sort_field": "id",
	"sort_dir": "asc"
},
"items": [{
	"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": "\/api\/user\/mtutty\/avatar",
	"html_url": "\/#\/user\/mtutty\/",
	"details_url": "\/api\/user\/mtutty\/details",
	"isSiteAdmin": true,
	"api_url": "\/api\/user\/mtutty",
         "roles": [{
             "id": 9173,
             "name": "GForge Customer"
	}]
}],
"links": []
}

getModules

Get the list of modules that are enabled for the specified project.

Parameters (1)

Name Type Description
id mixed The unix name or database ID for the project

Return: string[]

A list of the shortnames that are active for the project.

getParents

Gets a list of all parent projects, including the specified project. The first project will be the specified project and the last will be the root parent. /api/project/:childId/parent

Parameters (0)

Name Type Description
No parameters

Return: (none)

No return type is defined

getProject

Searches for projects matching criteria, or retrieves a specific project by unixname or database ID.

Parameters (6)

Name Type Description
id mixed The database ID or unix name of a specific project to be retrieved. If specified, then any other filter values will be ignored and the call will return zero or one record.
name string The user-friendly name of the project.
unixName string The short name of the project.
isPublic boolean If set, then only include projects whose isPublic flag matches the specified value.
status int Status of the project, 0 = pending, 1 = active, 3 = archived/deleted.
templateProjectId int Unique identifier for the template on which search results must be based. Will not return the template itself.
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: \gforge\core\models\api\ProjectBasic

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

Name Type Description
id int Unique database identifier for the project
name string Name of the project
unixName string Short, unix-friendly identifier for the project. This is usually also the project's shell logon.
description string Public description for the project
homepageUrl string GFAS url for the project
createDate \date Date of project creation
isPublic string Returns "Y" if the project is public, "N" otherwise
status string Returns the status code for the project
isTemplate string Returns "Y" if the project is a template
templateProjectId int Returns the project used as template for this project
parentProjectId int Returns the parent project id for this project --- used as output, not allowed for input
averageRating int Returns the average rate for the project

Example 1

Find a project by matching the unix name. The unix name or ID parameters can be included in the path, instead of using a query string parameter.
  GET http://mygforge.tld/api/project?unixName=gforge5
  or
  GET http://mygforge.tld/api/project?id=138
  or
  GET http://mygforge.tld/api/project/gforge5
  or
  GET http://mygforge.tld/api/project/138
{"id":138,"name":"GForge AS","unixName":"gforge5",
"description":"We Believe in Great Software.  For over two decades GForge has helped software organizations deliver their ideas to market faster using their own process.  The project is the core GForge project and it has two active efforts.  The first is maintenance on the existing GForge product and the second is delivering the next generation of GForge.  ",
"homepageUrl":"\/gf\/project\/gforge5\/","createDate":"2005-10-10 01:37:46 -0500",
"isPublic":"Y","status":1,"isTemplate":"N","templateProjectId":0}

getRole

Get information about a specific Role.

Parameters (2)

Name Type Description
id int|string The project's ID or unixName. Part of the request route.
roleId int|string The role's ID or string name. Part of the request route.

Related Entities (1)

Return: \Role

The requested role, optionally with a rel.role_settings field containing the role settings.

getRoleSettings

Get the default role settings for the specified project.

Parameters (1)

Name Type Description
id int|string The project's ID or unixName. Part of the request route.

Related Entities (1)

Return: \RoleSettingBasic[]

Zero or more objects with default role settings for the project.

getRoles

Get the roles that belong to the project.

Parameters (1)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/roles).
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\core\models\api\RoleBasic

Zero or more roles that exist for this project.

Name Type Description
id int Unique database identifier for the role
roleName string name of the role

Example 1

Get the roles defined for the project.
  GET http://api.mygforge.tld/project/gforge5/roles
  or
  GET http://api.mygforge.tld/project/138/roles
{
  "paging":{"page_size":20,"page_num":1,"sort_field":"id","sort_dir":"asc"},
  "items":[
    {"id":166,"roleName":"Admin"},
    {"id":167,"roleName":"Senior Developer"},
    {"id":224,"roleName":"SCM only"},
    {"id":9554,"roleName":"Marketing\/Communications"},
    {"id":9028,"roleName":"Hosting"},
    {"id":9134,"roleName":"Technical Writer"},
    {"id":9228,"roleName":"GForge Contractor"},
    {"id":9173,"roleName":"GForge Customer"},
    {"id":9704,"roleName":"License Requestor"}],
  "links":[]
}

getScmActivity

A wrapper for the \gforge\plugins\scm\services\ScmService getSummary endpoint

Get a summary of activity data for the specified project's SCM, over the specified (or default) date range

NOTE: The date range will be filled in by day, even if no data is found for that day, so that the array is continuous across the specified range.

Parameters (5)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/scm/unixname/summary).
start string The start date/time for activity data to be returned. If empty or false, defaults to two weeks ago.
end string The end date/time for activity data. If empty or false, defaults to tomorrow.
by_user string If set to any value (e.g., 1, true, Y, whatever you've got), then return a record for each user for each day.
chart string If set to any value (e.g., 1, true, Y, whatever you've got), then return activity data, formatted for chart presentation.

Related Entities (1)

Return: \gforge\plugins\scm\models\api\ScmSummary

The summary data, including a stats array with date, checkouts, commits and adds. Not all values are valid for all SCM types, may be empty or zero.

Name Type Description
stats \gforge\core\models\api\StatsBasic[] Commit stats for the repository. NOTE: If the summary was requested with the chart parameter, then this will be an array of StdClass objects, with data optimized for chart display.
totalCommits int
startDate string The date, in Y-m-d format
endDate string The date, in Y-m-d format
unixName string
scmType string
defaultBranchName string
hostName string
options \StdClass for settings on the scm repo Fields:
  • useSsh: If true, then ssh access is enabled for this repository.
  • anonymousRead: If true, then anonymous users can read the repository.
  • requireTrackerItem: If true, then all commits must reference a Tracker Item ID.
  • validateEmail: If true, then all committer emails must belong to an authorized GForge user.
  • mailCommits: If true, then project members will receive email notifications about commits.
  • accessText: Optional custom text to be shown in the SCM access UI section.
  • browseText: Optional custom text to be shown in the SCM browse UI section.

getSprints

Get the sprints related to the project.

Parameters (1)

Name Type Description
id mixed The int ID or unix name for the desired project, by default from the request path (i.e., /api/project/unixname/sprints).

Return: \gforge\plugins\tracker\models\TrackerSprint

Zero or more trackerSprint records

getTrackers

Get basic information about the Trackers associated with a specified project

Parameters (1)

Name Type Description
id mixed The database ID or unix name for the project to be retrieved. This is specified in the route, e.g., /api/project/:id-or-unix-name/details

Return: array

An array of summary information about each Tracker for the project that the authenticated user can view, inclusing permissions on each Tracker.

Example 1

Basic request
  GET http://api.mygforge.tld/project/gforge5/trackers
  or
  GET http://api.mygforge.tld/project/138/trackers

    {
     "trackers":[
        {
           "tracker_id":10109,
           "tracker_name":"Licenses",
           "is_public":false,
           "restrict_browse":false,
           "total_count":244,
           "open_count":172,
           "closed_count":72,
           "assigned_to_me":0,
           "access_level":10
        },
        {
           "tracker_id":355,
           "tracker_name":"GForge",
           "is_public":false,
           "restrict_browse":false,
           "total_count":5249,
           "open_count":656,
           "closed_count":4593,
           "assigned_to_me":3,
           "access_level":0
        },
        {
           "tracker_id":10237,
           "tracker_name":"GForge Support",
           "is_public":false,
           "restrict_browse":false,
           "total_count":3435,
           "open_count":39,
           "closed_count":3396,
           "assigned_to_me":1,
           "access_level":10
        },
        {
           "tracker_id":10345,
           "tracker_name":"Free Support",
           "is_public":true,
           "restrict_browse":false,
           "total_count":6,
           "open_count":6,
           "closed_count":0,
           "assigned_to_me":1,
           "access_level":10
        },
        {
           "tracker_id":10311,
           "tracker_name":"Managed Servers",
           "is_public":false,
           "restrict_browse":false,
           "total_count":13,
           "open_count":12,
           "closed_count":1,
           "assigned_to_me":0,
           "access_level":10
        },
        {
           "tracker_id":10292,
           "tracker_name":"User Stories",
           "is_public":false,
           "restrict_browse":false,
           "total_count":69,
           "open_count":28,
           "closed_count":41,
           "assigned_to_me":0,
           "access_level":10
        },
        {
           "tracker_id":9662,
           "tracker_name":"Build Failures",
           "is_public":false,
           "restrict_browse":false,
           "total_count":0,
           "open_count":0,
           "closed_count":0,
           "assigned_to_me":0,
           "access_level":10
        },
        {
           "tracker_id":10661,
           "tracker_name":"Business Development",
           "is_public":false,
           "restrict_browse":false,
           "total_count":3589,
           "open_count":3523,
           "closed_count":66,
           "assigned_to_me":0,
           "access_level":99
        }
     ]
  }

getTrove

Gets all trove categories a project is tagged with. It's required that Request contains the following parameters: id.

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object.

Return: int

1 on success

POST

postChildren

Adds all projects from the parameter "children" as child projects for project specified. Note that this does NOT set as a definitive list - any child projects previously associated will still be children. /api/project/:unixName/children { children:":child1,:child2" }

Parameters (0)

Name Type Description
No parameters

Return: (none)

No return type is defined

postInvite

Sends invite emails to a project

Parameters (3)

Name Type Description
id mixed The unix name or database ID for the project to which the user will be invited.
invites string The email address(es) to invite, separated by commas.
role int The role ID the user(s) will receive when the invite is redeemed.

Return: array

A result StdClass for each email submitted, each with a boolean success var and an optional user object (if an existing user was found for an email).

postJoinRequest

Request to join a project

Parameters (1)

Name Type Description
id mixed The int ID or unix name for the desired project.

Return: mixed

True one was created. If the request is not valid, a list of the validation errors

postMember

Add a user to the project

Parameters (3)

Name Type Description
id mixed The int ID or unix name for the desired project.
userId mixed The int ID or unix name for the desired user.
roles array Array of roles for the member

Return: mixed

True one was created. If the request is not valid, a list of the validation errors

postParent

Set a project as the child of another project. The id of the parent project should be in the id parameter within the url for the post. The child project id should be sent in the post data as "parentId" /api/project/:childId/parent { parentId:":parentId" }

Parameters (0)

Name Type Description
No parameters

Return: (none)

No return type is defined

postProject

Create a new or update an existing Project. All fields of the ProjectBasic structure (except the URL fields) may be set using this method. Other project configuration options can also be set: Additional parameters for NEW PROJECTS ONLY: - modules: Module/plugin names to be enabled for the project. - trackers: Template tracker IDs from which to clone fields and workflow. - invites: Emails to which project invitations will be sent. For EXISTING PROJECTS: - To enable/disable modules/plugins, use the putModules method. - Project-level admin for trackers (add/remove) is not implemented yet. - To invite users, use the postInvite method.

Parameters (1)

Name Type Description
\gforge\core\models\api\ProjectBasic All of the fields may be set as individual parameters.

Return: mixed

A ProjectBasic structure if one was created. If the request is not valid, a list of the validation errors.

postRole

Create or update a role and all of its settings. NOTE: This method replaces ALL role settings if ANY are specified. For compatibility, role settings must be submitted in the same rel.role_settings structure as produced by getRole.

Parameters (2)

Name Type Description
id int|string Identifier for the project. Part of the URL route.
roleId int Identifier for the role. NOTE: Only the numeric ID can be used to create/update a role.

Return: \RoleBasic

The created or updated role, including role settings.

postTrove

Gets all trove categories a project is tagged with. It's required that Request contains the following parameters: id.

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object.

Return: int

1 on success

PUT

putMember

Update roles for a project's member

Parameters (3)

Name Type Description
id int|string The int ID or unix name for the desired project.
userId int|string The int ID or unix name for the desired user.
roles array Array of roles for the member

Return: mixed

true if some was created.

putModules

Set the list of modules that are enabled for the specified project. The PUT verb replaces the current set of data with the submitted list, so callers must provide the ENTIRE list. Any entries not submitted will be turned off. Modules that are "off" will still respond to API calls, but will not be shown in the UI. Turning a module off will not delete existing data. Turning a module back on will show the data as it last existed. This method requires Project Admin privilege, since it will result in visible changes to the UI. In order to turn off all modules, you must submit the special module name "core" as the only module. This is to prevent an accidental empty request from turning off all project modules.

Parameters (2)

Name Type Description
id mixed The unix name or database ID for the project
modules string A comma-separated list of the shortnames to be made active for the project.

Return: (none)

No return type is defined

DELETE

deleteJoinRequest

Deletes a user's request to join a project. It's required that Request contains the following parameters: id, userId. If the record is not found a 404 exception is thrown.

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object.

Return: int

1 on success

deleteMember

Deletes a user from a project. The requesting user must be a project admin.

Parameters (2)

Name Type Description
id int|string Part of the request route, the database ID or unix name for the project being changed.
userId int|string Part of the request route, the database ID or unix name for the user being removed.

Return: int

1 on success

deleteProject

Deletes a project. It's required that Request contains the following parameters: id.

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object.

Return: int

1 on success

deleteRole

Delete a role and all of its settings.

Parameters (2)

Name Type Description
id int|string Identifier for the project. Part of the URL route.
roleId int Identifier for the role. NOTE: Only the numeric ID can be used to create/update a role.

Return: void

No return type is defined