---

Gerenciar Atribuições de Registros

A API Blue fornece três operações para gerenciar atribuições de registros: definir atribuições (substituição inteligente), adicionar atribuições e remover atribuições. Essas operações lidam automaticamente com rastreamento de atividades, notificações, webhooks e atualizações em tempo real.

Definir Atribuições de Registros (Atribuição Inteligente)

Substitui todos os atribuintes atuais por uma nova lista. O sistema calcula inteligentemente quais mudanças são necessárias, removendo usuários que não estão na nova lista e adicionando novos.

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

Adicionar Atribuições de Registros

Adiciona novos atribuintes sem remover os existentes. Apenas usuários que ainda não estão atribuídos serão adicionados.

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

Remover Atribuições de Registros

Remove atribuintes específicos de um registro.

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

Parâmetros de Entrada

SetTodoAssigneesInput

Parâmetro	Tipo	Obrigatório	Descrição
todoId	String!	✅ Sim	O ID do registro para atribuir usuários
assigneeIds	[String!]!	✅ Sim	Array de IDs de usuários a serem atribuídos (substitui todos os atribuintes atuais)

AddTodoAssigneesInput

Parâmetro	Tipo	Obrigatório	Descrição
todoId	String!	✅ Sim	O ID do registro para atribuir usuários
assigneeIds	[String!]!	✅ Sim	Array de IDs de usuários a serem adicionados como atribuintes

RemoveTodoAssigneesInput

Parâmetro	Tipo	Obrigatório	Descrição
todoId	String!	✅ Sim	O ID do registro para remover atribuintes
assigneeIds	[String!]!	✅ Sim	Array de IDs de usuários a serem removidos dos atribuintes

Campos de Resposta

Campo	Tipo	Descrição
success	Boolean!	Se a operação foi concluída com sucesso
operationId	String	Identificador único para rastrear esta operação

Permissões Necessárias

Definir/Remover Atribuintes

Função	Pode Atribuir/Remover
OWNER	✅ Sim
ADMIN	✅ Sim
MEMBER	✅ Sim
CLIENT	✅ Sim
VIEW_ONLY	❌ Não
COMMENT_ONLY	❌ Não

Adicionar Atribuintes

Função	Pode Adicionar Atribuintes
OWNER	✅ Sim
ADMIN	✅ Sim
MEMBER	✅ Sim
CLIENT	✅ Sim
VIEW_ONLY	✅ Sim
COMMENT_ONLY	✅ Sim

Respostas de Erro

Registro Não Encontrado

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

Permissões 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"
    }
  }]
}

Comparação de Operações

Recurso	Definir Atribuintes	Adicionar Atribuintes	Remover Atribuintes
Logic	Smart replacement	Incremental addition	Selective removal
Activity Tracking	✅ Sim	❌ Não	❌ Não
Notificações	✅ Sim	❌ Não	❌ Não
Webhooks	✅ Sim	❌ Não	❌ Não
Automations	✅ Sim	❌ Não	❌ Não
Permission Level	Stricter	More permissive	Stricter

Lógica de Negócio

Atribuição Inteligente (setTodoAssignees)

Quando você usa setTodoAssignees, o sistema:

1. Compara Listas: Analisa os atribuintes atuais versus a nova lista de atribuintes
2. Calcula Mudanças: Determina quem remover, manter e adicionar
3. Remove Usuários: Desatribui usuários que não estão na nova lista
4. Adiciona Usuários: Atribui usuários na nova lista que não estavam previamente atribuídos
5. Rastreia Atividades: Cria entradas de log de atividades para cada mudança
6. Envia Notificações: Notifica os usuários recém-atribuídos
7. Dispara Webhooks: Aciona webhooks de atribuição adicionada/removida
8. Atualiza Gráficos: Marca gráficos de análise para atualização
9. Atualizações em Tempo Real: Publica atualizações para clientes conectados

Operações Simples (adicionar/remover)

As operações addTodoAssignees e removeTodoAssignees fornecem funcionalidade básica sem os recursos abrangentes de rastreamento e notificação de setTodoAssignees.

Notas Importantes

• Membresia do Projeto: Os atribuintes devem ser membros do projeto que contém o registro
• Sem Limites de Atribuição: Não há um número máximo de atribuintes por registro
• Auto-Atribuição: Usuários podem se atribuir se tiverem as permissões adequadas
• Arrays Vazios: Fornecer um array vazio assigneeIds para setTodoAssignees remove todos os atribuintes
• Prevenção de Duplicatas: O sistema previne automaticamente atribuições duplicadas
• Eficiência do Banco de Dados: Usa tabela de junção (TodoUser) para relacionamentos escaláveis muitos-para-muitos
• Atualizações em Tempo Real: Todos os clientes conectados recebem atualizações imediatas quando as atribuições mudam

Obter Atribuintes Disponíveis

Para obter uma lista de usuários que podem ser atribuídos a registros em um projeto:

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

Essa consulta retorna todos os membros do projeto que podem ser potencialmente atribuídos a registros.

Operações Relacionadas

• Listar Registros - Obter registros com seus atribuintes atuais
• Atualizar Registro - Modificar outras propriedades do registro
• Adicionar Comentário - Adicionar comentários a registros atribuídos