Screendragon API Integration Use Cases - Resources

Modified on Tue, 30 Sep at 10:41 AM

Fetch list of Resources
Add a new Resource Booking
Amend a Resource Booking
Delete a Resource Booking
Retrieve daily Resourcing

Fetch list of Resources

Endpoint

GET /api/resource

Description

This endpoint returns a list of resource bookings for users and projects. You can filter the results by date range, project ID, or user ID. Only logged-in users can access this information.

Query Parameters

Name	Type	Required	Description
`startDate`	DateTime	❌	Show bookings starting from this date (YYYY-MM-DD).
`endDate`	DateTime	❌	Show bookings ending by this date (YYYY-MM-DD).
`project`	Int32	❌	Filter by project ID. Use 0 to include all projects.Defaults to 0
`user`	Int32	❌	Filter by user ID. Use 0 to include all users.Defaults to 0

Error Handling

Status Code	Message
400	"No data"

Notes

You can use either a project ID or a user ID to filter the results; if both are set to 0, all projects and users are included.
If you provide a date range, only bookings within that range are shown.
You must be logged in to access this information.
If no matching bookings are found, the response will indicate "No data".

Sample Request

GET /api/resource?startDate=2025-09-01&endDate=2025-09-30&project=123&user=456 HTTP/1.1
Authorization: Bearer {token}

Sample Response (Success)

[
  {
    "project": 123,
    "title": "Project Title",
    "item": "Task Name",
    "user": {
      "userID": 456,
      "UserName": "jdoe",
      "FirstName": "John",
      "LastName": "Doe",
      "email": "jdoe@example.com"
    },
    "start": "2025-09-01T00:00:00Z",
    "end": "2025-09-05T00:00:00Z",
    "hrs": 40,
    "bookingID": 789,
    "taskID": 321
  }
]

Sample Response (Error)

{
  "error": "No data."
}

Add a new Resource Booking

Endpoint

POST /api/resource/booking

Description

This endpoint creates a new booking for a user against a specified resource event. The booking includes details such as time range, hours per day, and optional comments.

Query Parameters

Name	Type	Required	Description
`retrospectiveBooking`	Boolean	❌	Allows booking in the past if set to true.

Body Parameters

Name	Type	Required	Description
`user`	String	✅	Identifier for the user (can be user ID, username, or email).
`resourceEvent`	String	✅	Identifier for the resource event.
`startTime`	String	✅	Start time of the booking in ISO 8601 format.
`endTime`	String	✅	End time of the booking in ISO 8601 format.
`hoursPerDay`	Float	❌	Number of hours booked per day.
`comment`	String	❌	Optional comment for the booking.
`taskID`	Int32	❌	Task ID if updating an existing booking. Must be 0 for new bookings.
`identifierType`	String	❌	Type of user identifier (userid, username, email). Defaults to userid.
`eventIdentifierType`	String	❌	Type of event identifier (i_node, name). Defaults to i_node.
`timesheet`	Boolean	❌	Indicates if the booking is for a timesheet.

Error Handling

Status Code	Message
400	"Unable to parse booking details."
400	"Cannot add duplicate booking."
400	"Invalid client configuration."
400	"No such user exists."
400	"Specified user has no current role."
400	"No such event exists."
400	"Invalid date range."
400	"Cannot create bookings in the past."
400	"No Data."

Notes

The user identifier can be a user ID, username, or email; the system resolves it internally.
The event identifier can be either the internal node (i_node) or the event name (item).
If taskID is greater than 0, the request is rejected to prevent duplicate bookings.
If retrospectiveBooking = false, bookings cannot be created for past dates.
If hoursPerDay is provided, it is capped by the user's available hours and FTE.
If timesheet = true, the booking is marked accordingly.
Permission checks are performed based on the user's role and active status.

Sample Request

POST /api/resource/booking?retrospectiveBooking=false HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "user": "jdoe@example.com",
  "resourceEvent": "Project Alpha",
  "startTime": "2025-09-25T09:00:00.000000+00:00",
  "endTime": "2025-09-25T17:00:00.000000+00:00",
  "hoursPerDay": 8,
  "comment": "Booking for project kickoff",
  "taskID": 0,
  "identifierType": "email",
  "eventIdentifierType": "name",
  "timesheet": true
}

Sample Response (Success)

{
  "taskID": 321,
  "bookingID": 789
}

Sample Response (Error)

{
  "error": "Unable to parse booking details"
}

Amend a Resource Booking

Endpoint

POST /api/resource/booking/{taskId}

Description

This endpoint amends an existing booking for a specified task. It validates user credentials, booking details, and event associations before updating the booking in the system. It supports retrospective bookings and handles time zone conversions.

Path Parameters

Name	Type	Required	Description
`taskId`	Int32	✅	ID of the task to amend.

Query Parameters

Name	Type	Required	Description
`retrospectiveBooking`	Boolean	❌	Allows booking in the past if set to true.

Body Parameters

Name	Type	Required	Description
`user`	String	✅	Identifier of the user (userID, username, or email).
`resourceEvent`	String	✅	Event identifier.
`startTime`	String	✅	Start time in ISO 8601 format.
`endTime`	String	✅	End time in ISO 8601 format.
`identifierType`	String	❌	Type of user identifier (default: userid).
`eventIdentifierType`	String	❌	Type of event identifier (default: i_node).
`comment`	String	❌	Optional comment.
`hoursPerDay`	Float	❌	Number of hours per day.
`timesheet`	Boolean	❌	Indicates if timesheet is required.

Error Handling

Status Code	Message
400	"Unable to parse booking details."
400	"Invalid task id supplied."
400	"No such user exists."
400	"Specified user has no current role."
400	"No such event exists."
400	"Invalid date range."
400	"Cannot create bookings in the past ."
400	"No data."

Notes

The endpoint requires authorization.
Time zone differences are handled automatically if the time strings include offsets.
The system checks for user roles and event associations before proceeding.
If hoursPerDay is not specified, it defaults to available hours per day.
The booking is only created if the user, role, and event validations pass.

Sample Request

PUT /ai/resource/booking/123?retrospectiveBooking=false
Content-Type: application/json
{
  "user": "john.doe",
  "resourceEvent": "event123",
  "startTime": "2025-09-24T09:00:00.000000+01:00",
  "endTime": "2025-09-24T17:00:00.000000+01:00",
  "identifierType": "username",
  "eventIdentifierType": "name",
  "comment": "Updated booking",
  "hoursPerDay": 8,
  "timesheet": true
}

Sample Response (Success)

{
  "taskID": 123,
  "bookingID": 456
}

Sample Response (Error)

{
  "error": "Unable to parse booking details."
}

Delete a Resource Booking

Endpoint

DELETE /api/resource/booking

Description

This endpoint deletes a booking, project, or task resource item based on the provided identifier, Requires user authorization and validates user credentials before performing deletion, Supports optional cutoff date filtering for project-based deletions.

Query Parameters

Name	Type	Required	Description
`id`	Int32	✅	The unique identifier for the booking, project, or task to be deleted.
`identifierType`	String	❌	Type of identifier: "booking", "project", or "task".
`hasCutOff`	Boolean	❌	Indicates whether to apply a cutoff date filter (used only for projects)..
`cutOffDate`	String	❌	Cutoff date in string format (used only when hasCutOff is true).

Error Handling

Status Code	Message
404	"No such booking exists"
400	"No data"

Notes

Only authorized users are allowed to access this endpoint.
Deletion Logic:If identifierType = "booking" → delete by i_node.
If identifierType = "project" → delete by projectID, optionally filtered by cutOffDate.
If identifierType = "task" → delete by taskID.
Cutoff Filtering: Applied only when identifierType = "project" and hasCutOff = true with a valid cutOffDate.

Sample Request

DELETE /api/resource/booking?id=12345&identifierType=project
&hasCutOff=true&cutOffDate=2025-09-01
Authorization: Bearer <token>

Sample Response (Error)

{
  "error": "No such booking exists."
}

Retrieve daily Resourcing

Endpoint

GET /api/resource/DailyResourcing

Description

This endpoint retrieves daily resourcing data including user metadata, project associations, task details, and resource allocations..

Query Parameters

Name	Type	Required	Description
`includeGuestUsers`	String	❌	Filters user data to include guest users if specified.
`customFields`	String	❌	JSON string representing custom metadata fields to include in the response.

Error Handling

Status Code	Message
400	"No data"

Notes

Requires authorization.
Custom fields are dynamically joined and returned if provided.
The endpoint limits the result set to 1,048,500 records.

Sample Request

GET /api/resource/DailyResourcing?includeGuestUsers=true
&customFields=[{"label":"Department","guid":"abc-123"},{"label":"Location","guid":"def-456"}]
Authorization: Bearer <token>

Sample Response (Success)

{
  "dataInfo": {
    "Tables": [
      {
        "project id#": 101,
        "USER id#": 2001,
        "FULL NAME": "Jane Doe",
        "resourced role": "Developer",
        "task id#": 301,
        "task NAME": "Build API",
        "hours resourced": 8.00,
        "cost resourced": 640.00,
        "date resourced": "2025-09-24",
        "resourceitemid": 501,
        "deleted": 0,
        "datetimestamp": "2025-09-24T10:00:00"
      }
    ]
  }
}

Sample Response (Error)

{
  "error": "No data."
}