<< Back to GForge REST API

Entity: Project

GET

getActivity

Get the activity metrics for this project.

Parameters (1)

Name Type Description
request \RequestParameters

Return: array

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

getActivitylog

Get recent activity log data for the specified Project

Parameters (1)

Name Type Description
request \RequestParameters

Return: \StdClass

An array of ActivityLogBasic structures

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
request \RequestParameters

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

Array of the most recent builds associated with the project.

Name Type Description
id int Unique database identifier for the build
description string description of this build
changelog string Changes made from the previous build
url string url to this build
job mixed the associated Job
wasSuccessful bool Whether this build was successful or not
buildDate \DateTime The date of the last message posting in this forum, across all threads (read-only)
buildNumber int Identifier for the build instance, provided by the build engine.

getChat

Get a reference to the project chat thread.

Parameters (1)

Name Type Description
request \RequestParameters

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 bool 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 \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
request \RequestParameters

Related Entities (6)

rel= Type Description
admins \gforge\core\models\api\UserBasic[] All users with project admin privileges on this project. Note that admin privileges may derive from parent project(s).
members \gforge\core\models\api\UserBasic[] All project members, including admins
activity_stats \gforge\core\models\api\StatsBasic[] Time-series data of an overall project activity metric. Defaults to the last 15 days - use the project/:unixName/activity endpoint for different dates.
activity_log \gforge\core\models\api\ActivityLogBasic[] Significant project-level actions for the past week, grouped by section/refid and ordered by the most recent date for each section & ref. Use the /activitylog API endpoint for more or different data.
chat \gforge\plugins\forum\models\api\ForumBasic The forum and thread that this project uses for Project Chat.
trackers \gforge\plugins\tracker\models\api\TrackerBasic[] The list of Trackers that the authenticated user can access for this project.

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
projectText1 string Returns special field 1
projectText2 string Returns special field 2
projectText3 string Returns special field 3
projectText4 string Returns special field 4
projectText5 string Returns special field 5
projectText6 string Returns special field 6
isWorkflowScriptEnabled bool 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 \DateTime 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 string 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.",
 "projectText1":null,
 "projectText2":null,
 "projectText3":null,
 "projectText4":null,
 "projectText5":null,
 "projectText6":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.",
     "projectText1":null,
     "projectText2":null,
     "projectText3":null,
     "projectText4":null,
     "projectText5":null,
     "projectText6":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
request \RequestParameters

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

Zero or more forums that are part of this project.

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 bool 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)

getGroup

Parameters (1)

Name Type Description
request \RequestParameters

Return: \gforge\core\models\api\GroupApi

Name Type Description
id int
unixName string
status int
name string
userText1 string Flex field for customer use
userText2 string Flex field for customer use
userText3 string Flex field for customer use
userText4 string Flex field for customer use
userText5 string Flex field for customer use
userText6 string Flex field for customer use
users \UserBasic[]
projects \ProjectBasic[]

getGroups

Parameters (1)

Name Type Description
request \RequestParameters

Return: \gforge\core\models\api\GroupApi[]

Name Type Description
id int
unixName string
status int
name string
userText1 string Flex field for customer use
userText2 string Flex field for customer use
userText3 string Flex field for customer use
userText4 string Flex field for customer use
userText5 string Flex field for customer use
userText6 string Flex field for customer use
users \UserBasic[]
projects \ProjectBasic[]

getInvite

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

Parameters (1)

Name Type Description
request \RequestParameters

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 (1)

Name Type Description
request \RequestParameters

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

Zero or more user records, 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 int 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 string
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 bool
api_url string Relative path to the user's basic data (API)

Example 1

Get the users who requested to join the project. 
  GET http://api.mygforge.tld/project/gforge5/joinRequests?page_size=2&page_num=1
  or
  GET http://api.mygforge.tld/project/138/joinRequests?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/joinRequests?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 (5)

Name Type Description
string|int project (in URL) The project within which to find members. This can be a database ID or unixName
bool group If true, include users who are are members via a group membership. Default is false (only direct members)
bool groups If true, include groups in the result. By default, only users are included.
int role Database ID for a role on which to filter. If specified, only users in this role are included.
string type The type of member search: 'standup' shows members with Assignee or higher privilege in any Tracker on the project. 'history' shows any user that has previous activity on the project. Default is to show users strictly based on current role assignments.
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 (2)

rel= Type Description
roles RoleBasic[] Include the list of roles for each user returned.
groups UserBasic[] Include the list of group memberships for each user returned. NOTE: This rel is not related to the groups parameter, and does not affect it.

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

The list of members for the specified project/group

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 int 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 string
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 bool
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"
   },
   {
       "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"
   }],
   "links": []
}

Example 2

Get the members for the project with firstname Michael. Include role and group memberships in the results 
  GET http://api.mygforge.tld/project/gforge5/members?firstname=Michael&rel=groups,roles


{
   "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",
       "rel" {
           "roles": [{
               "id": 9173,
               "name": "GForge Customer"
           }],
           "groups": [{
               "id": 9192,
               "unixName": "group1",
               "password": null,
               "firstname": "Group",
               "lastname": "One",
               "email": "",
               "timezone": "America\/Chicago",
               "status": 1,
               "isGroup": "Y"
           }]
       }
   }],
   "links": []
}

getModules

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

Parameters (1)

Name Type Description
request \RequestParameters

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.

Parameters (1)

Name Type Description
request \RequestParameters

Return: \gforge\core\models\api\ProjectBasic[]

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 \DateTime 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 string Returns the parent project id for this project --- used as output, not allowed for input
averageRating int Returns the average rate for the project

getProject

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

Parameters (1)

Name Type Description
request \RequestParameters
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)

rel= Type Description
string) array(of modules The list of module/plugin names that are currently active for the project.

Return: \ProjectBasic[]

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

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}

getReport

Get a list of report results associated with the specified project.

Parameters (5)

Name Type Description
report_id int Unique identifier for a single rpeort result. If this parameter is non-empty and > 0, then other parameters are ignored.
type string Filter by the specified report type
since string Only include reports created *after* this date
before string Only include reports created *before* this date
range string If specified, this value replaces $since, and $before is cleared.
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: \gforge\core\models\api\ReportResultBasic[]

Zero or more matching report results

Name Type Description
id int Id
createDate string Date when the ReportResult was created
section string Section the ReportResult belongs to
refId int Id of object the ReportResult is bound to
type string type of ReportResult
name string User-friendly title for ReportResult
value string Summary or simple value for report output

getRole

Get information about a specific Role.

Parameters (2)

Name Type Description
id int|string The project ID or unix name, included in the route.
roleId int (optional) A specific role ID, included in the route.

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

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

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

getRoleSettings

Get the default role settings for the specified project.

Parameters (1)

Name Type Description
request \RequestParameters

Related Entities (1)

rel= Type Description
Include role_settings the list of permission areas and the current access level for this role.

Return: \gforge\core\models\api\RoleSetting[]

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
request \RequestParameters
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Related Entities (2)

rel= Type Description
Include user_count the number of groups/users that are directly added to each role returned.
Include role_settings the list of permission areas and the current access level for this role. * If $sections is not specified, then all role settings will be returned when rel=role_settings is included. If rel=role_settings is not included in the request, then $sections is not used.

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":[]
}

getRolesFromRequest

Parameters (2)

Name Type Description
request \RequestParameters
requireRoles bool

Return: array

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 (6)

Name Type Description
request \RequestParameters
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)

rel= Type Description
chart_data array Include a transformed version of the stats data for use in charting

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
request \RequestParameters

Return: array

Zero or more trackerSprint records

getTrackers

Get basic information about the Trackers associated with a specified project

Parameters (1)

Name Type Description
request \RequestParameters

Return: \StdClass

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 \RequestParameters Request object.

Return: int

1 on success

POST

postChildren

Adds all projects from the parameter "children" as child projects for project specified.

Parameters (1)

Name Type Description
request \RequestParameters

Return: (none)

postGroup

Parameters (1)

Name Type Description
request \RequestParameters

Return: \gforge\core\models\api\GroupApi

Name Type Description
id int
unixName string
status int
name string
userText1 string Flex field for customer use
userText2 string Flex field for customer use
userText3 string Flex field for customer use
userText4 string Flex field for customer use
userText5 string Flex field for customer use
userText6 string Flex field for customer use
users \UserBasic[]
projects \ProjectBasic[]

postInvite

Sends invite emails to a project

Parameters (1)

Name Type Description
request \RequestParameters

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
request \RequestParameters

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 (1)

Name Type Description
request \RequestParameters

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"

Parameters (1)

Name Type Description
request \RequestParameters

Return: (none)

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.

Parameters (1)

Name Type Description
request \RequestParameters

Return: \gforge\core\models\api\ProjectBasic

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

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 \DateTime 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 string Returns the parent project id for this project --- used as output, not allowed for input
averageRating int Returns the average rate for the project

postRole

Create or update a role and all of its settings.

Parameters (1)

Name Type Description
request \RequestParameters

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

The created or updated role, including role settings.

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

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 \RequestParameters Request object.

Return: void

1 on success

PUT

putGroup

Parameters (1)

Name Type Description
request \RequestParameters

Return: \gforge\core\models\api\GroupApi

Name Type Description
id int
unixName string
status int
name string
userText1 string Flex field for customer use
userText2 string Flex field for customer use
userText3 string Flex field for customer use
userText4 string Flex field for customer use
userText5 string Flex field for customer use
userText6 string Flex field for customer use
users \UserBasic[]
projects \ProjectBasic[]

putMember

Update roles for a project's member

Parameters (1)

Name Type Description
request \RequestParameters

Return: mixed

true if some was created.

putModules

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

Parameters (1)

Name Type Description
request \RequestParameters

Return: array

DELETE

deleteGroup

Parameters (1)

Name Type Description
request \RequestParameters

Return: (none)

deleteJoinRequest

Deletes a user's request to join a project. It's required that Request contains the following parameters: id, userId.

Parameters (1)

Name Type Description
request \RequestParameters Request object.

Return: int

1 on success

deleteMember

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

Parameters (1)

Name Type Description
request \RequestParameters

Return: int

1 on success

deleteProject

Deletes a project.

Parameters (1)

Name Type Description
id mixed The unixName or ID for the project to be deleted.

Return: int

1 on success

deleteRole

Delete a role and all of its settings.

Parameters (1)

Name Type Description
request \RequestParameters

Return: bool