---

Gestionar Asignaciones de Registros

La API de Blue proporciona tres operaciones para gestionar las asignaciones de registros: establecer asignaciones (reemplazo inteligente), agregar asignaciones y eliminar asignaciones. Estas operaciones manejan automáticamente el seguimiento de actividades, notificaciones, webhooks y actualizaciones en tiempo real.

Establecer Asignaciones de Registros (Asignación Inteligente)

Reemplaza todas las asignaciones actuales con una nueva lista. El sistema calcula inteligentemente qué cambios son necesarios, eliminando usuarios que no están en la nueva lista y agregando nuevos.

mutation SetRecordAssignees {
  setTodoAssignees(input: {
    todoId: "record_abc123"
    assigneeIds: ["user_123", "user_456", "user_789"]
  }) {
    success
    operationId
  }
}

Agregar Asignaciones de Registros

Agrega nuevas asignaciones sin eliminar las existentes. Solo se agregarán usuarios que no estén ya asignados.

mutation AddRecordAssignees {
  addTodoAssignees(input: {
    todoId: "record_abc123"
    assigneeIds: ["user_999", "user_111"]
  }) {
    success
    operationId
  }
}

Eliminar Asignaciones de Registros

Elimina asignaciones específicas de un registro.

mutation RemoveRecordAssignees {
  removeTodoAssignees(input: {
    todoId: "record_abc123"
    assigneeIds: ["user_456"]
  }) {
    success
    operationId
  }
}

Parámetros de Entrada

SetTodoAssigneesInput

Parámetro	Tipo	Requerido	Descripción
todoId	String!	✅ Sí	El ID del registro al que se asignarán los usuarios
assigneeIds	[String!]!	✅ Sí	Array de IDs de usuarios a asignar (reemplaza todas las asignaciones actuales)

AddTodoAssigneesInput

Parámetro	Tipo	Requerido	Descripción
todoId	String!	✅ Sí	El ID del registro al que se asignarán los usuarios
assigneeIds	[String!]!	✅ Sí	Array de IDs de usuarios a agregar como asignaciones

RemoveTodoAssigneesInput

Parámetro	Tipo	Requerido	Descripción
todoId	String!	✅ Sí	El ID del registro del que se eliminarán las asignaciones
assigneeIds	[String!]!	✅ Sí	Array de IDs de usuarios a eliminar de las asignaciones

Campos de Respuesta

Campo	Tipo	Descripción
success	Boolean!	Si la operación se completó con éxito
operationId	String	Identificador único para rastrear esta operación

Permisos Requeridos

Establecer/Eliminar Asignaciones

Rol	Puede Asignar/Eliminar
OWNER	✅ Sí
ADMIN	✅ Sí
MEMBER	✅ Sí
CLIENT	✅ Sí
VIEW_ONLY	❌ No
COMMENT_ONLY	❌ No

Agregar Asignaciones

Rol	Puede Agregar Asignaciones
OWNER	✅ Sí
ADMIN	✅ Sí
MEMBER	✅ Sí
CLIENT	✅ Sí
VIEW_ONLY	✅ Sí
COMMENT_ONLY	✅ Sí

Respuestas de Error

Registro No Encontrado

{
  "errors": [{
    "message": "Todo was not found.",
    "extensions": {
      "code": "TODO_NOT_FOUND"
    }
  }]
}

Permisos Insuficientes

{
  "errors": [{
    "message": "You don't have permission to modify this record",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Entrada Inválida

{
  "errors": [{
    "message": "Variable '$input' got invalid value; Expected non-nullable type 'String!' not to be null.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

Comparación de Operaciones

Característica	Establecer Asignaciones	Agregar Asignaciones	Eliminar Asignaciones
Logic	Smart replacement	Incremental addition	Selective removal
Activity Tracking	✅ Sí	❌ No	❌ No
Notificaciones	✅ Sí	❌ No	❌ No
Webhooks	✅ Sí	❌ No	❌ No
Automations	✅ Sí	❌ No	❌ No
Permission Level	Stricter	More permissive	Stricter

Lógica Empresarial

Asignación Inteligente (setTodoAssignees)

Cuando utilizas setTodoAssignees, el sistema:

1. Compara Listas: Analiza los asignados actuales frente a la nueva lista de asignados
2. Calcula Cambios: Determina quién eliminar, mantener y agregar
3. Elimina Usuarios: Desasigna usuarios que no están en la nueva lista
4. Agrega Usuarios: Asigna usuarios en la nueva lista que no estaban previamente asignados
5. Rastrea Actividad: Crea entradas de registro de actividad para cada cambio
6. Envía Notificaciones: Notifica a los usuarios recién asignados
7. Dispara Webhooks: Activa webhooks de asignación agregada/eliminada
8. Actualiza Gráficos: Marca gráficos analíticos para actualización
9. Actualizaciones en Tiempo Real: Publica actualizaciones a los clientes conectados

Operaciones Simples (agregar/eliminar)

Las operaciones addTodoAssignees y removeTodoAssignees proporcionan funcionalidad básica sin las características de seguimiento y notificación exhaustivas de setTodoAssignees.

Notas Importantes

• Membresía del Proyecto: Los asignados deben ser miembros del proyecto que contiene el registro
• Sin Límites de Asignación: No hay un número máximo de asignados por registro
• Auto-Asiganción: Los usuarios pueden asignarse a sí mismos si tienen los permisos adecuados
• Arrays Vacíos: Proporcionar un array assigneeIds vacío a setTodoAssignees elimina todas las asignaciones
• Prevención de Duplicados: El sistema previene automáticamente asignaciones duplicadas
• Eficiencia de Base de Datos: Utiliza una tabla de unión (TodoUser) para relaciones escalables de muchos a muchos
• Actualizaciones en Tiempo Real: Todos los clientes conectados reciben actualizaciones inmediatas cuando cambian las asignaciones

Obtener Asignados Disponibles

Para obtener una lista de usuarios que pueden ser asignados a registros en un proyecto:

query GetAssignees {
  assignees(projectId: "project_abc123") {
    id
    name
    email
    avatar
  }
}

Esta consulta devuelve todos los miembros del proyecto que pueden ser potencialmente asignados a registros.

Operaciones Relacionadas

• Listar Registros - Obtener registros con sus asignaciones actuales
• Actualizar Registro - Modificar otras propiedades del registro
• Agregar Comentario - Agregar comentarios a registros asignados