Table of Contents

Class AdminVolunteerController

Namespace
Builvero.Api.Controllers
Assembly
Builvero.Api.dll

Provides administrative API endpoints for managing volunteer roles and applications.

[ApiController]
[Route("api/admin/volunteer")]
[Authorize(Policy = "AdminRead")]
public class AdminVolunteerController : ControllerBase
Inheritance
AdminVolunteerController
Inherited Members

Remarks

This controller requires authorization via the "AdminRead" policy for read operations and "AdminWrite" policy for write operations. All endpoints are prefixed with /api/admin/volunteer. The controller handles:

  • Retrieving all volunteer roles (including inactive)
  • Opening and closing volunteer roles (activating/deactivating)
  • Retrieving volunteer applications with pagination and filtering
  • Retrieving application details and resume download URLs
  • Updating application status (New, Reviewed, Accepted)
  • Deleting applications (GDPR compliance - right to be forgotten)

Resume files are stored in S3 and accessed via presigned URLs. Application deletion permanently removes the application from the database and the resume from S3 storage.

Constructors

AdminVolunteerController(IVolunteerRoleService, IVolunteerApplicationService, ILogger<AdminVolunteerController>)

Initializes a new instance of the AdminVolunteerController class.

public AdminVolunteerController(IVolunteerRoleService roleService, IVolunteerApplicationService applicationService, ILogger<AdminVolunteerController> logger)

Parameters

roleService IVolunteerRoleService

Service for volunteer role operations.

applicationService IVolunteerApplicationService

Service for volunteer application operations.

logger ILogger<AdminVolunteerController>

Logger for recording operations and errors.

Methods

CloseRole(Guid, CancellationToken)

Closes a volunteer role by setting IsActive to false.

[HttpPost("roles/{id}/close")]
[Authorize(Policy = "AdminWrite")]
public Task<ActionResult<VolunteerRoleDto>> CloseRole(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the volunteer role to close.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<VolunteerRoleDto>>

200 OK: Returns updated VolunteerRoleDto with IsActive set to false

400 Bad Request: Role not found or error closing role

Remarks

Requires AdminWrite policy. Closes the volunteer role, making it inactive and preventing new applications. Existing applications remain accessible. The role can be reopened using the OpenRole endpoint.

DiscardApplication(Guid, CancellationToken)

Permanently deletes a volunteer application and its associated resume file (GDPR compliance - right to be forgotten).

[HttpDelete("applications/{id}")]
[Authorize(Policy = "AdminWrite")]
public Task<ActionResult> DiscardApplication(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the application to delete.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult>

204 No Content: Application and resume successfully deleted

404 Not Found: Application not found

500 Internal Server Error: Error deleting application or resume

Remarks

Requires AdminWrite policy. Permanently removes the application from the database and the resume file from S3 storage. This operation cannot be undone. Used for GDPR compliance when a user requests their data to be deleted.

GetApplication(Guid, CancellationToken)

Retrieves detailed information for a specific volunteer application.

[HttpGet("applications/{id}")]
public Task<ActionResult<VolunteerApplicationDto>> GetApplication(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the application to retrieve.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<VolunteerApplicationDto>>

200 OK: Returns VolunteerApplicationDto with complete application information

404 Not Found: Application not found

500 Internal Server Error: Error retrieving application

Remarks

Requires AdminRead policy. Returns complete application details including personal information, resume information, and application status. Used by admin interfaces to review applications.

GetApplications(int, int, Guid?, string?, CancellationToken)

Retrieves volunteer applications with pagination and optional filtering by role and status.

[HttpGet("applications")]
public Task<ActionResult<object>> GetApplications(int page = 1, int pageSize = 20, Guid? roleId = null, string? status = null, CancellationToken cancellationToken = default)

Parameters

page int

The page number (1-based). Defaults to 1.

pageSize int

The number of applications per page. Defaults to 20.

roleId Guid?

Optional filter by volunteer role ID.

status string

Optional filter by application status (New, Reviewed, Accepted). Case-insensitive.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<object>>

200 OK: Returns { "applications": [...], "totalCount": int, "page": int, "pageSize": int }

500 Internal Server Error: Error retrieving applications

Remarks

Requires AdminRead policy. Returns paginated list of volunteer applications. Supports filtering by role ID and status. Applications are ordered by creation date (newest first).

GetResumeDownloadUrl(Guid, CancellationToken)

Generates a presigned URL for downloading a volunteer application's resume file.

[HttpGet("applications/{id}/resume-download")]
public Task<ActionResult<object>> GetResumeDownloadUrl(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the application whose resume to download.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<object>>

200 OK: Returns { "downloadUrl": "presigned-url" } with a presigned S3 URL (15-minute expiration)

400 Bad Request: Application not found, resume not available, or error generating URL

Remarks

Requires AdminRead policy. Generates a presigned S3 URL that allows secure, temporary access to the resume file. The URL expires after 15 minutes. Resume files are stored in S3 under the resumes/ prefix.

GetRoles(CancellationToken)

Retrieves all volunteer roles in the system, including inactive roles.

[HttpGet("roles")]
public Task<ActionResult<List<VolunteerRoleDto>>> GetRoles(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<List<VolunteerRoleDto>>>

200 OK: Returns list of VolunteerRoleDto objects

500 Internal Server Error: Error retrieving roles

Remarks

Requires AdminRead policy. Returns all volunteer roles regardless of their active status. Used by admin interfaces to manage available volunteer positions.

OpenRole(Guid, CancellationToken)

Opens a volunteer role by setting IsActive to true.

[HttpPost("roles/{id}/open")]
[Authorize(Policy = "AdminWrite")]
public Task<ActionResult<VolunteerRoleDto>> OpenRole(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the volunteer role to open.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<VolunteerRoleDto>>

200 OK: Returns updated VolunteerRoleDto with IsActive set to true

400 Bad Request: Role not found or error opening role

Remarks

Requires AdminWrite policy. Opens the volunteer role, making it active and allowing new applications. The role becomes visible in public volunteer role listings.

UpdateApplicationStatus(Guid, UpdateApplicationStatusRequest, CancellationToken)

Updates the status of a volunteer application.

[HttpPatch("applications/{id}/status")]
[Authorize(Policy = "AdminWrite")]
public Task<ActionResult<VolunteerApplicationDto>> UpdateApplicationStatus(Guid id, UpdateApplicationStatusRequest request, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the application to update.

request UpdateApplicationStatusRequest

The update request containing the new status (New, Reviewed, Accepted).

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<VolunteerApplicationDto>>

200 OK: Returns updated VolunteerApplicationDto with new status

400 Bad Request: Invalid status value, application not found, or error updating status

Remarks

Requires AdminWrite policy. Updates the application status to one of: New, Reviewed, or Accepted. Status values are case-insensitive. Used by admins to track application review progress.

Edit this page