Skip to main content

​
Overview

The USR Service (Usuarios) manages organizational units (Unidades) within the HERCULES SGI system. It provides APIs for managing the organizational structure that is used across all modules for access control and reporting.
Base URL: http://localhost:4285 (development)
Service Path: /unidades

​
Authentication

All endpoints require a valid OAuth2 access token with appropriate module-specific permissions. 
Authorization: Bearer <access_token>

​
Unidades (Organizational Units)

Organizational units represent the administrative structure of the institution (departments, research groups, administrative offices, etc.).

​
List Organizational Units

Retrieve a paginated and filtered list of organizational units. 
GET /unidades
​
q
string
RSQL filter query for searching units (e.g., nombre=like='Departamento*')
​
s
string
Sorting criteria (e.g., nombre,asc)
​
page
number
Page number (0-indexed)
​
size
number
Page size
Required Permissions: Any of the following authorities:
  • CSP-SOL-E - Edit grant applications
  • CSP-SOL-V - View grant applications
  • CSP-PRO-V - View projects
  • CSP-PRO-C - Create projects
  • CSP-PRO-E - Edit projects
  • CSP-PRO-B - Delete projects
  • CSP-PRO-R - Reactivate projects
  • CSP-ME-C - Create economic models
  • CSP-ME-E - Edit economic models
  • ADM-CNF-E - Edit administration configuration
Example Request: 
curl -X GET "http://localhost:4285/unidades?q=nombre=like='Departamento*'&s=nombre,asc&page=0&size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "content": [
    {
      "id": 1,
      "nombre": "Departamento de Informática",
      "acronimo": "DI",
      "descripcion": "Department of Computer Science",
      "activo": true,
      "unidadPadreId": null
    },
    {
      "id": 2,
      "nombre": "Departamento de Matemáticas",
      "acronimo": "DM",
      "descripcion": "Department of Mathematics",
      "activo": true,
      "unidadPadreId": null
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "size": 10
}

​
Get Organizational Unit by ID

Retrieve a specific organizational unit by its identifier. 
GET /unidades/{id}
​
id
number
required
Organizational unit identifier
Example Request: 
curl -X GET "http://localhost:4285/unidades/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "id": 1,
  "nombre": "Departamento de Informática",
  "acronimo": "DI",
  "descripcion": "Department of Computer Science",
  "activo": true,
  "unidadPadreId": null,
  "responsableRef": "user-ref-123"
}

​
Unidad Model

​
id
number
Unique identifier for the organizational unit
​
nombre
string
Full name of the unit
​
acronimo
string
Short acronym for the unit
​
descripcion
string
Detailed description of the unit
​
activo
boolean
Whether the unit is currently active
​
unidadPadreId
number
Parent unit ID (null for top-level units)
​
responsableRef
string
Reference to the person responsible for this unit

​
Public Endpoints

The USR service exposes public endpoints (no authentication required) for organizational units.

​
Get Public Organizational Units

Retrieve organizational units without authentication. 
GET /public/unidades
Public endpoints return only active organizational units with basic information.
Example Request: 
curl -X GET "http://localhost:4285/public/unidades"

​
RSQL Filter Examples

The USR service supports RSQL queries for flexible filtering: 
# Find units by name containing text
q=nombre=like='Departamento*'

# Find active units
q=activo==true

# Find units under a parent
q=unidadPadreId==5

# Combine multiple criteria
q=activo==true;nombre=like='*Investigación*'

​
Integration with Other Services

The USR service provides organizational unit information that is used by:
  • CSP Service - Assigns projects and applications to units
  • ETI Service - Ethics committee memberships tied to units
  • PII Service - Invention ownership by units
  • PRC Service - Research production grouped by units
Organizational units are referenced across the system. Deactivating or deleting units may affect existing records.

​
Common Use Cases

​
Get All Active Departments

curl -X GET "http://localhost:4285/unidades?q=activo==true;nombre=like='Departamento*'" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Find Unit by Acronym

curl -X GET "http://localhost:4285/unidades?q=acronimo=='DI'" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Organizational Hierarchy

To retrieve a complete organizational hierarchy, fetch all units and build the tree structure based on unidadPadreId relationships.

​
Error Responses

​
status
number
HTTP status code
​
error
string
Error type
​
message
string
Human-readable error message
Example Error Response: 
{
  "status": 404,
  "error": "Not Found",
  "message": "Unidad with ID 999 not found"
}

Administrator Guide

Managing users and organizational units

Authorization

Role-based access control

Build docs developers (and LLMs) love

Get started for freeTalk to us