Screendragon API Integration Use Cases - Projects

Modified on Fri, 21 Nov at 12:23 PM

Fetch Project List
Retrieve Project Details
Retrieve Project Resources
Retrieve Project Budget
Update Project Status

Fetch Project List

Endpoint

GET /api/projects

Description

This endpoint retrieves a list of projects based on the filtering and pagination options provided in the query. It returns project metadata such as name, status, and associated details. If no data is found or an error occurs, a generic error message is returned.

Query Parameters

Name	Type	Required	Description
`status`	`String`	❌	Filter projects by status (e.g., "active", "archived").
`owner`	`String`	❌	Username of the project owner.
`startDate`	`DateTime`	❌	Filter projects starting from this date.
`endDateode>`	`DateTime`	❌	Filter projects ending before this date.
`page`	`Int32`	❌	Page number for pagination. Defaults to 1.
`pageSize`	`Int32`	❌	Number of projects per page. Defaults to 20.

Error Handling

Status Code	Message
400	"No data."
500	"Internal server error."

Notes

Ensure the bearer token is valid and has permission to view project data.
Pagination is optional but recommended for large datasets.
If no filters are provided, all projects may be returned (subject to default limits).

Sample Request

GET /api/projects?status=active&owner=jdoe
&page=1&pageSize=10
Authorization: Bearer <token>

Sample Response (Success)

[
  {
    "projectCode": 101,
    "milestone": 1,
    "accessLevel": 0,
    "replaceLabels": false,
    "startDate": "2025-06-01T00:00:00Z",
    "endDate": "2025-12-31T00:00:00Z",
    "layout": null,
    "i_node": 133,
    "f_node": 2,
    "item": "203349",
    "description": "",
     "creator": {
            "userID": 146,
            "userName": "sdadmin",
            "firstName": "Screendragon",
            "lastName": "Admin",
            "email": "sd@screendragon.com",
            "status": "Project Live",
            "createDate": "2014-10-01T11:49:32"
        }
  },
 ...
]

Sample Response (Error)

{
  "error": "No data"
}

Retrieve Project Details

Endpoint

GET /api/projects/{id}

Description

This endpoint retrieves detailed information about a specific project, including access levels, sub-projects, and layout metadata. It is useful for clients who need a comprehensive view of a project and its structure.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the project.

Error Handling

Status Code	Message
404	"Project not found."
400	"No Data."
500	"Internal Server Error."

Notes

The endpoint automatically includes access level, sub-projects, and layout information without requiring additional query parameters.
Ensure the bearer token is valid and has permission to view the specified project.

Sample Request

GET /api/projects/101
Authorization: Bearer <token>

Sample Response (Success)

[
    {
        "projectCode": "",
        "startDate": "2025-09-12T00:00:00",
        "endDate": "2026-01-31T00:00:00",
        "createDate": "2025-11-12T08:51:23",
        "milestone": 1,
        "accessLevel": 3,
        "subProjects": [],
        "customFields": [],
        "layout": {
            "formGUID": "b884d673-7562-4668-e95e-9d95c898b222",
            "id": 347,
            "title": "Project - All",
            "phases": [
            ]
        },
        "i_node": 1334148,
        "f_node": 2,
        "item": "203349",
        "description": "",
        "creator": {
            "userID": 146,
            "userName": "sdadmin",
            "firstName": "Screendragon",
            "lastName": "Admin",
            "email": "liam@screendragon.com",
            "status": "Project Live",
            "createDate": "2014-10-01T11:49:32"
        },
        "status": "Project Live"
    }
]

Sample Response (Error)

{
  "error": "No data"
}

Retrieve Project Resources

Endpoint

GET /api/projects/{id}/resources

Description

This endpoint retrieves a list of users assigned as resources to a specific project. The response includes user metadata such as name, email, and status. Access is filtered based on the requesting user's credentials and group permissions unless the user is an admin.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the project.

Error Handling

Status Code	Message
400	"No data."
403	"Access denied."
500	"Internal server error."

Notes

Admin users retrieve all resources for the project.
Non-admin users must have inherited permissions either via group membership or direct assignment, to view project resources.

Sample Request

GET /api/projects/101/resources
Authorization: Bearer <token>

Sample Response (Success)

[
  {
    "UserID": 501,
    "Status": "Active",
    "UserName": "jdoe",
    "Email": "jdoe@example.com",
    "FirstName": "John",
    "LastName": "Doe",
    "CreateDate": "2024-11-15T09:30:00Z"
  },
  {
    "UserID": 502,
    "Status": "Inactive",
    "UserName": "asmith",
    "Email": "asmith@example.com",
    "FirstName": "Alice",
    "LastName": "Smith",
    "CreateDate": "2023-06-20T14:45:00Z"
  }
]

Sample Response (Error)

{
  "error": "No data"
}

Retrieve Project Budget

Endpoint

GET /api/resource/GetProjectBudget

Description

This endpoint retrieves the budget details for a specified project using its unique identifier (inode).

Query Parameters

Name	Type	Required	Description
`inode`	`Int32`	✅	Unique identifier of the project.

Error Handling

Status Code	Message
500	"No data."

Notes

The endpoint uses user credentials to log errors and track access.
The response is wrapped in a DataRowResponse object containing the dataset.

Sample Request

GET /api/resource/GetProjectBudget?inode=1024
Authorization: Bearer <token>

Sample Response (Success)

{
  "dataInfo": {
    "Table": [
      {
        "TableName": "ProjectBudget",
        "Columns": [...],
        "Rows": [...]
      }
    ]
  }
}

Sample Response (Error)

{
  "error": "No data"
}

Update Project Status

Endpoint

PUT /api/projects/status

Description

This endpoint updates the status of a specific project. It validates the provided status against the allowed values defined in the project layout's global settings. If the status is valid, the project is updated and optionally synced with MongoDB if configured.

Query Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the project.
`projectStatus`	`String`	✅	New status to assign to the project. Must match one of the allowed statuses for the layout.

Error Handling

Status Code	Message
400	"No project status was specified."
400	"No project id was provided to update."
404	"Project with ID {id} not found."
400	"Failed to update project id: {id}. The status: {status} is invalid."
500	"Internal server error."

Notes

Valid statuses include default values (Active, Cancelled, On-Hold, Complete) and any additional statuses defined in the project layout's global settings.
The endpoint uses internal user credentials to determine access and configuration.

Sample Request

PUT /api/projects/status?id=101&projectStatus=Complete
Authorization: Bearer <token>

Sample Response (Success)

{

  "status": "Active",
  "id": 1067,
  "message": "Successfully updated project id: 101.
    Its new status is Active"
}

Sample Response (Error)

{
  "error": "Failed to update project id: 101. 
The status: Archived is invalid for this project layout"
}