<< Back to GForge REST API

Entity: Docman

GET

getBinary

Get raw file contents.

Parameters (3)

Name Type Description
id int Unique identifier for the file object. This is part of the URL route
version int (Optional) number of the version being requested. Defaults to the current version.
open mixed (Optional) If any non-"falsy" value is included, open the binary content in the browser. Otherwise, download as a file.

Return: mixed

The file contents

getBundle

Retrieves a folder with its contents (files and versions) in a zip file

Parameters (1)

Name Type Description
id int ID of the folder that is being requested

Return: mixed

file in zip format

Example 1

http://api.mygforge.tld/api/docman/115/bunde

getFile

Retrieves a file with its file versions and folders

Parameters (1)

Name Type Description
id int ID of the file to be retrieved

Return: \gforge\plugins\docman\models\api\DocmanFileDetail

Name Type Description
id int Unique database identifier for the Docman file
description string File description
isMonitored string 'Y' if monitored, 'N' otherwise
rel array A flexible set of related data

Example 1

Get file information 

GET /api/docman/6064/file?rel=versions,folders,monitoring,downloads

{
    "id": 6064,
    "description": "Screenshot at Jul 16 14-17-47.png",
    "isLocked": "N",
    "lockedBy": {
        "id": 8388,
        "unixName": "someuser",
        "password": null,
        "firstname": "John",
        "lastname": "Doe",
        "email": "someuser@gforgegroup.com",
        "timezone": "America/New_York",
        "status": 1,
        "externalId": null,
        "isGroup": "N",
        "ccode": "AR",
        "language": "en",
        "theme": 1,
        "img_url": "/api/user/someuser/avatar",
        "html_url": "/#/user/someuser",
        "details_url": "/api/user/someuser/details",
        "isSiteAdmin": true,
        "api_url": "/api/user/someuser"
    },
    "isMonitored": null,
    "rel": {
        "folders": [
            {
                "id": 69,
                "folderName": "incoming",
                "isPublic": "N",
                "parentFolderId": 0,
                "isMonitored": null,
                "docCount": -22,
                "project": {
                    "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 06:37:46 +0000",
                    "isPublic": "Y",
                    "status": 1,
                    "isTemplate": "N",
                    "templateProjectId": 0,
                    "parentProjectId": 2720,
                    "averageRating": 5
                }
            }
        ],
        "versions": [
            {
                "id": 3400,
                "createDate": "2020-07-31T20:17:23+0000",
                "changes": null,
                "versionNumber": 1,
                "isApproved": "Y",
                "docmanFile": null,
                "user": {
                    "id": 8388,
                    "unixName": "someuser",
                    "password": null,
                    "firstname": "John",
                    "lastname": "Doe",
                    "email": "someuser@gforgegroup.com",
                    "timezone": "America/New_York",
                    "status": 1,
                    "externalId": null,
                    "isGroup": "N",
                    "ccode": "AR",
                    "language": "en",
                    "theme": 1,
                    "img_url": "/api/user/someuser/avatar",
                    "html_url": "/#/user/someuser",
                    "details_url": "/api/user/someuser/details",
                    "isSiteAdmin": true,
                    "api_url": "/api/user/someuser"
                },
                "url": "/api/docman/6064/binary/Screenshot+at+Jul+16+14-17-47.png?version=1",
                "filesystem": {
                    "id": 38140,
                    "fileName": "Screenshot at Jul 16 14-17-47.png",
                    "section": "docmanfileversion",
                    "refId": 3400,
                    "fileNameSafe": "Screenshot at Jul 16 14-17-47.png",
                    "fileType": "image/png; charset=binary",
                    "fileSize": "20768",
                    "postedBy": {
                        "id": 8388,
                        "unixName": "someuser",
                        "password": null,
                        "firstname": "John",
                        "lastname": "Doe",
                        "email": "someuser@gforgegroup.com",
                        "timezone": "America/New_York",
                        "status": 1,
                        "externalId": null,
                        "isGroup": "N",
                        "ccode": "AR",
                        "language": "en",
                        "theme": 1,
                        "img_url": "/api/user/someuser/avatar",
                        "html_url": "/#/user/someuser",
                        "details_url": "/api/user/someuser/details",
                        "isSiteAdmin": true,
                        "api_url": "/api/user/someuser"
                    },
                    "downloadCount": 0,
                    "uploadedOn": "2020-07-31T20:17:23+0000",
                    "thumbnailUrl": "/core/img/filetypes/256/PNG.png",
                    "attachmentUrl": "/api/docman/3400/filesystem",
                    "md5Hash": "a1e08d10d26f0cdeae4b5aa1df417e00"
                }
            },
            {
                "id": 3401,
                "createDate": "2020-07-31T20:17:29+0000",
                "changes": null,
                "versionNumber": 2,
                "isApproved": "Y",
                "docmanFile": null,
                "user": {
                    "id": 8388,
                    "unixName": "someuser",
                    "password": null,
                    "firstname": "John",
                    "lastname": "Doe",
                    "email": "someuser@gforgegroup.com",
                    "timezone": "America/New_York",
                    "status": 1,
                    "externalId": null,
                    "isGroup": "N",
                    "ccode": "AR",
                    "language": "en",
                    "theme": 1,
                    "img_url": "/api/user/someuser/avatar",
                    "html_url": "/#/user/someuser",
                    "details_url": "/api/user/someuser/details",
                    "isSiteAdmin": true,
                    "api_url": "/api/user/someuser"
                },
                "url": "/api/docman/6064/binary/Screenshot+at+Jul+16+14-17-47.png?version=2",
                "filesystem": {
                    "id": 38141,
                    "fileName": "Screenshot at Jul 16 14-17-47.png",
                    "section": "docmanfileversion",
                    "refId": 3401,
                    "fileNameSafe": "Screenshot at Jul 16 14-17-47.png",
                    "fileType": "image/png; charset=binary",
                    "fileSize": "20768",
                    "postedBy": {
                        "id": 8388,
                        "unixName": "someuser",
                        "password": null,
                        "firstname": "John",
                        "lastname": "Doe",
                        "email": "someuser@gforgegroup.com",
                        "timezone": "America/New_York",
                        "status": 1,
                        "externalId": null,
                        "isGroup": "N",
                        "ccode": "AR",
                        "language": "en",
                        "theme": 1,
                        "img_url": "/api/user/someuser/avatar",
                        "html_url": "/#/user/someuser",
                        "details_url": "/api/user/someuser/details",
                        "isSiteAdmin": true,
                        "api_url": "/api/user/someuser"
                    },
                    "downloadCount": 0,
                    "uploadedOn": "2020-07-31T20:17:29+0000",
                    "thumbnailUrl": "/core/img/filetypes/256/PNG.png",
                    "attachmentUrl": "/api/docman/3401/filesystem",
                    "md5Hash": "a1e08d10d26f0cdeae4b5aa1df417e00"
                }
            }
        ],
        "monitoring": [],
        "downloads": []
    }
}

getFolder

Retrieves a folder with its contents (files and versions)

Parameters (4)

Name Type Description
id int ID or name of the requested folder
projectId int ID of the project, required in case you are searching by folder name (not for ID based search)
sort_field string Field to use for sorting the folder files
sort_dir string Direction to sort. It could be asc or desc. Default is 'asc'.

Related Entities (1)

rel= Type Description
currentfiles \gforge\plugins\docman\models\api\DocmanFileVersion The list of files that reside in the requested folder (current version of each file)

Return: \gforge\plugins\docman\models\api\DocmanFolderBasic

The requested folder API object

Name Type Description
id int Unique database identifier for the docman folder
folderName string Folder name
isPublic \char 'Y' when is approved
project int
parentFolderId int
isMonitored string 'Y' if monitored, 'N' otherwise
docCount int

Example 1

http://api.mygforge.tld/api/docman/115/folder?rel=currentfiles 

{
    "id": 115,
    "folderName": "Build Docs",
    "isPublic": "N",
    "parentFolderId": 0,
    "isMonitored": null,
    "docCount": 0,
    "project": {
        "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 06:37:46 +0000",
        "isPublic": "Y",
        "status": 1,
        "isTemplate": "N",
        "templateProjectId": 0,
        "parentProjectId": 2720,
        "averageRating": 5
    },
    "rel": {
        "currentfiles": [
            {
                "id": 2294,
                "createDate": "2013-04-12T19:47:02+0000",
                "changes": "",
                "versionNumber": 2,
                "isApproved": "Y",
                "docmanFile": {
                    "id": 3067,
                    "description": "AgileStats.odt File!",
                    "isLocked": "N",
                    "lockedBy": {
                        "id": 100,
                        "unixName": "None",
                        "password": null,
                        "firstname": "Nobody",
                        "lastname": " ",
                        "email": "noreply@gforge.org",
                        "timezone": "GMT",
                        "status": 1,
                        "externalId": null,
                        "isGroup": "N",
                        "ccode": "US",
                        "language": "en",
                        "theme": 1,
                        "img_url": "/api/user/None/avatar",
                        "html_url": "/#/user/None",
                        "details_url": "/api/user/None/details",
                        "isSiteAdmin": false,
                        "api_url": "/api/user/None"
                    },
                    "isMonitored": "N",
                    "rel": []
                },
                "user": {
                    "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"
                },
                "url": "/api/docman/3067/binary/AgileStats.odt?version=2",
                "filesystem": {
                    "id": 18182,
                    "fileName": "AgileStats.odt",
                    "section": "docmanfileversion",
                    "refId": 2294,
                    "fileNameSafe": "AgileStats.odt",
                    "fileType": "application/vnd.oasis.opendocument.text; charset=binary",
                    "fileSize": "16856",
                    "postedBy": {
                        "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"
                    },
                    "downloadCount": 1,
                    "uploadedOn": "",
                    "thumbnailUrl": "/core/img/filetypes/256/BLANK.png",
                    "attachmentUrl": "/api/docman/2294/filesystem",
                    "md5Hash": "1a844eca118c066292de1f7f4c17e815"
                }
            },
                      }
        ]
    }
}

getFolders

Retrieves all folders on a given project

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: \gforge\plugins\docman\models\api\DocmanFolderBasic[]

Zero or more DocmanFolderBasic objects

Name Type Description
id int Unique database identifier for the docman folder
folderName string Folder name
isPublic \char 'Y' when is approved
project int
parentFolderId int
isMonitored string 'Y' if monitored, 'N' otherwise
docCount int

Example 1

http://api.mygforge.tld/api/docman/138/folders 

{
    "paging": {
        "page_size": 20,
        "page_num": 1,
        "sort_field": "id",
        "sort_dir": "asc"
    },
    "items": [
        {
            "id": 115,
            "folderName": "Build Docs",
            "isPublic": "N",
            "parentFolderId": 0,
            "isMonitored": "N",
            "docCount": 0,
            "project": {
                "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 06:37:46 +0000",
                "isPublic": "Y",
                "status": 1,
                "isTemplate": "N",
                "templateProjectId": 0,
                "parentProjectId": 2720,
                "averageRating": 5
            }
        },
        {
            "id": 50,
            "folderName": "Developer documentation",
            "isPublic": "N",
            "parentFolderId": 0,
            "isMonitored": "N",
            "docCount": -1,
            "project": {
                "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 06:37:46 +0000",
                "isPublic": "Y",
                "status": 1,
                "isTemplate": "N",
                "templateProjectId": 0,
                "parentProjectId": 2720,
                "averageRating": 5
            }
        },
    ],
    "links": [],
    "meta": []
}

POST

postBinary

Processes a binary file upload to a given folder. If a file with the same name already exists, it creates a new version of the file

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: array

Array with API location to attachment

Example 1

Update an existing file, or create a new one, under the folder with ID = 70 

POST /api/docman/70/binary

postFile

Updates or creates a new file. This is used to lock/unlock a file, or update its description. To add/update a file use postBinary

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

Example 1

Locks a file 

POST /api/docman/2212/file

{
 "id":6064,
 "isLocked":"Y"
}

postFolder

Creates or a updates a folder.

Parameters (6)

Name Type Description
id int Unique ID for the folder, 0 for a new folder
folderName string Name of the folder
isPublic bool True if the folder has public access, false otherwise
parentFolderId int ID of the parent folder
parentFolderName string Name of the parent folder
project int ID of the project

Return: \gforge\plugins\docman\models\api\DocmanFolderBasic[]

Zero or more DocmanFolderBasic objects

Name Type Description
id int Unique database identifier for the docman folder
folderName string Folder name
isPublic \char 'Y' when is approved
project int
parentFolderId int
isMonitored string 'Y' if monitored, 'N' otherwise
docCount int

Example 1

Update or create a new folder under the "GForge AS" folder 

POST /api/docman/0/folder
{
 "id": 0,
 "folderName": "test",
 "isPublic": "Y",
 "parentFolderId": 0,
 "parentFolderName": "GForge AS",
 "project": 138
}

postRestore

Restores a file version (makes it current version)

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

Example 1

Restores a file version, where the file version id is 2212 

POST /api/docman/2212/restore

postUnzip

Unzips an existing file and recreates the directory/files structure in docman

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

Example 1

Request to unzip a given file 

POST /api/docman/70/unzip

postVersion

Updates a file version changes description

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

Example 1

Updates file version changes description, where the file version id is 2212 

POST /api/docman/2212/version

{
  "id":2212,
  "changes":"some changes",
  "docmanFile":241
}

PUT

DELETE

deleteFile

Deletes a file (including all its versions)

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

Example 1

Deletes a file, where the file id is 112 

POST /api/docman/112/file

deleteFolder

Deletes a folder, and subfolders and files in them

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

Example 1

Delete folder with ID 12345 

DELETE /api/docman/12345/folder

deleteVersion

Deletes a file version

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

Example 1

Deletes version of a file, where the file version id is 341 

POST /api/docman/341/version