Screendragon API Integration Use Cases - Timesheets

Modified on Tue, 30 Sep at 10:49 AM

Fetch Timesheet Status
Fetch Timesheet Status for List of Users
Fetch Detailed Timesheet Records
Fetch Timesheet Summary
Update Weekly Timesheet Records
Retrieve Overdue Timesheets
Retrieve Daily Timesheets

Timesheet Status

Endpoint

GET /api/timesheet/status/{id}

Description

This endpoint retrieves the timesheet status of a specific user for a given week. It returns user details along with the status of their timesheet (e.g., submitted, approved, or not created).

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	ID of the user whose timesheet status is queried.

Query Parameters

Name	Type	Required	Description
`weekEnding`	`DateTime`	✅	The week-ending date for the timesheet (ISO format).

Error Handling

Status Code	Message
400	"No such user in the system."
400	"No data."
400	"Internal server error."

Notes

The endpoint uses internal user credentials extracted from the request context.
The status field may return values like "submitted", "approved", or "notimesheet" if no timesheet exists for the given week.
Ensure the weekEnding date is correctly formatted and corresponds to a valid week-ending period.

Sample Request

GET /api/timesheet/status/42
&weekEnding=2025-07-18
Authorization: Bearer <token>

Sample Response (Success)

{
  "userID": 42,
  "userName": "jdoe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "weekEnding": "2025-07-18",
  "status": "submitted"
}

Sample Response (Error)

{
  "error": "No such user in the system."
}

Timesheet Status for List of Users

Endpoint

GET /api/timesheet/status

Description

This endpoint retrieves a list of users and their timesheet submission status for a specified date range. It supports filtering by submission status, group membership, and custom profile filters. Only active users within the specified range are considered.

Query Parameters

Name	Type	Required	Description
`from`	`DateTime`	✅	Start date of the range.
`to`	`DateTime`	✅	End date of the range.
`status`	`String`	❌	Filter by timesheet status: "submitted" or "notsubmitted". Defaults to "submitted".
`group`	`String`	❌	Comma-separated group IDs to filter users by group membership.
`profileFilter`	`String`	❌	JSON string representing custom profile filters.

Error Handling

Status Code	Message
400	"Invalid parameters, 'to' date is before 'from' date."
400	"Invalid parameters, 'status' must be Submitted or NotSubmitted."
400	"No Data."
400	"Internal Server Error."

Notes

The endpoint uses internal user credentials extracted from the request context.
The status field may return values like "submitted", "approved", or "notimesheet" if no timesheet exists for the given week.
Ensure the weekEnding date is correctly formatted and corresponds to a valid week-ending period.

Sample Request

GET /api/timesheet/status?from=2025-07-18&to=2025-07-25'
Authorization: Bearer <token>

Sample Response (Success)

{
  "userID": 42,
  "userName": "jdoe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "weekEnding": "2025-07-18",
  "status": "submitted"
}

Sample Response (Error)

{
  "error": "No such user in the system."
}

Fetch Detailed Timesheet Records

Endpoint

GET /api/timesheet

Description

This endpoint retrieves a detailed list of timesheet records for a specified user, project, and/or week. The response includes daily hours logged by users against projects.

Query Parameters

Name	Type	Required	Description
`week`	`Datetime`	❌	The week-ending date to filter timesheets (format: YYYY-MM-DD).
`user`	`Int32`	❌	ID of the user whose timesheet is to be retrieved. Defaults to 0 (all).
`project`	`Int32`	❌	ID of the project to filter timesheets. Defaults to 0 (all).

Error Handling

Status Code	Message
400	"No data."

Notes

If no filters are provided, it returns all non-deleted timesheet records with non-zero hours.
The endpoint requires user authentication and extracts credentials from the request context.
Dates are calculated based on the weekEnding field and adjusted per weekday.

Sample Request

GET /api/timesheet?week=2025-07-25
&user=102&project=305
Authorization: Bearer <token>

Sample Response (Success)

[
  {
    "username": "jdoe",
    "date": "2025-07-21",
    "project": 305,
    "hours": 8.0
  },
  {
    "username": "jdoe",
    "date": "2025-07-22",
    "project": 305,
    "hours": 7.5
  }
]

Sample Response (Error)

{
  "error": "No data"
}

Fetch Timesheet Summary

Endpoint

GET /api/timesheet/summary

Description

This endpoint returns a summarized view of timesheet data grouped by user and project for a given week. The summary includes total hours logged per project per user.

Query Parameters

Name	Type	Required	Description
`week`	`Datetime`	❌	Week-ending date in the format yyyy-MM-dd. Validated against system format.
`user`	`Int32`	❌	ID of the user to filter timesheets. Defaults to 0 (all users).
`project`	`Int32`	❌	ID of the project to filter timesheets. Defaults to 0 (all).

Error Handling

Status Code	Message
400	"Week input 2025-07-99 is invalid; please use format: yyyy-MM-dd."
400	"No data."

Notes

The endpoint requires authentication and extracts user credentials from the request context.
The endpoint validates the week parameter against a strict date format

Sample Request

GET /api/timesheet/summary?week=2025-07-25
&user=102&project=305
Authorization: Bearer <token>

Sample Response (Success)

[
  {
    "user": {
      "userID": 102,
      "userName": "jdoe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "jdoe@example.com",
      "createDate": "2020-01-15T00:00:00Z",
      "groups": "1,2,3"
    },
    "summary": [
      {
        "weekEnding": "2025-07-25",
        "id": 305,
        "project": "Project Alpha",
        "hrs": 40.0
      }
    ]
  }
]

Sample Response (Error)

{
  "error": "Week input 2025-07-99 is invalid, 
please use format: yyyy-MM-dd"
}

Update Timesheet Records

Endpoint

PUT /api/timesheet

Description

This endpoint updates or creates timesheet records for users. It processes a list of daily timesheet entries, grouped by user, project, and week. If a record exists, it is updated; if not, a new one is created. Records not included in the request but existing in the database for the same user and week are deleted.

Body Parameters

Name	Type	Required	Description
`username`	`String`	✅	Username of the person submitting the timesheet.
`project`	`Int32`	✅	Project ID associated with the timesheet entry.
`date`	`Date`	✅	Date of the timesheet entry.
`hours`	`Decimal`	✅	Number of hours worked on the given date.
`rmIngestTime`	`Boolean`	❌	Optional flag to indicate if the record is from a remote ingestion process.

Error Handling

Status Code	Message
400	"Invalid username jdoe"
400	"Invalid project ID."
400	"No data."

Notes

The endpoint determines the week-ending date based on the provided date (Sunday is considered the weekend).
If rmIngestTime is true, the system may bypass certain validations.
The system checks for valid project IDs and user permissions.
If the site is configured to queue updates (queueTimesheetAPIUpdates), the data is inserted into a staging table for later processing.
The endpoint supports both schema versions (v1 and v2) and adapts logic accordingly.

Sample Request

PUT /api/timesheet
Content-Type: application/json
Authorization: Bearer <token>

[
  {
    "username": "jdoe",
    "project": 101,
    "date": "2025-08-11",
    "hours": 8,
    "rmIngestTime": false
  },
  {
    "username": "jdoe",
    "project": 101,
    "date": "2025-08-12",
    "hours": 7.5
  }
]

Sample Response (Success)

{
  "status": "Success",
  "message": "Timesheet records updated successfully."
}

Sample Response (Error)

{
  "error": "Invalid username jdoe"
}

Retrieve Overdue Timesheets

Endpoint

GET /api/timesheet/GetUserOverdueTimesheets

Description

This endpoint retrieves all overdue timesheets for a specific user. A timesheet is considered overdue if its weekEnding date is on or before the specified date and its status is neither Approved nor Submitted.

Query Parameters

Name	Type	Required	Description
`userID`	`Int32`	✅	The ID of the user whose overdue timesheets are being queried.
`weekEnding`	`String`	✅	The cutoff date (inclusive) for overdue timesheets in yyyy-MM-dd format.

Error Handling

Status Code	Message
400	"No data."

Notes

The endpoint filters out timesheets that are already Approved or Submitted.
The weekEnding parameter must be in a valid date format (yyyy-MM-dd).
The user credentials are extracted from the request context to ensure proper authorization and logging.
Results are ordered by weekEnding date in ascending order.

Sample Request

GET /api/timesheet/GetUserOverdueTimesheets?usrID=123
&weekEnding=2025-08-10
Authorization: Bearer <token>

Sample Response (Success)

{
  "dataInfo": {
    "Tables": [
      {
        "Columns": ["timeSheetId", "UserID", 
                          "weekEnding", "status", ...],
        "Rows": [
          [456, 123, "2025-08-03", "Saved", ...],
          [457, 123, "2025-08-10", "In Progress", ...]
        ]
      }
    ]
  }
}

Sample Response (Error)

{
  "error": "No data"
}

Retrieve Daily Timesheets

Endpoint

GET /api/resource/DailyTimesheets

Description

This endpoint retrieves daily timesheet data for users, including hours worked, cost calculations, project and task associations, and optional metadata. Supports filtering by form types and inclusion of custom fields.

Query Parameters

Name	Type	Required	Description
`customFields`	`String`	❌	JSON string representing a list of custom field objects with label and guid.
`formTypes`	`String`	❌	Comma-separated list of form GUIDs to filter projects by specific form types.

Error Handling

Status Code	Message
400	"No data."

Notes

The endpoint is protected and requires a valid user token.
Used extensively for data aggregation, transformation, and filtering.
If provided, custom fields are dynamically joined and returned in the response.
Projects can be filtered by specific form GUIDs.

Sample Request

GET /api/resource/DailyTimesheets?formTypes=abc-123,def-456
&customFields=[{"label":"Department","guid":"xyz-789"}]
Authorization: Bearer <token>

Sample Response (Success)

{
  "dataInfo": {
    "Tables": [
      {
        "USER id#": 2001,
        "full name": "John Smith",
        "Project": "Website Redesign",
        "resourced ROLE": "Designer",
        "hours actual": 7.50,
        "cost actual": 562.50,
        "DATE actual": "2025-09-24",
        "dayofweekname actual": "Wednesday"
      }
    ]
  }
}

Sample Response (Error)

{
  "error": "No data"
}