Conceitos do Plan

Esta página é um glossário com links. A visão geral explica o modelo uma vez (organização, projeto, quadro, tarefa); aqui cada objeto tem um parágrafo e um link para os endpoints que o gerenciam.

Projetos, metas e quadros

• Projeto: o que é um conjunto de trabalho. Tem um líder, saúde, datas, notas de status (atualizações) e marcos. Endpoints: Plan · Projetos.
• Meta: para que serve o trabalho, com um período e um status declarado. As metas apontam para projetos; nada vive dentro de uma meta. O progresso conta só o que você pode ver, e is_partial: true sinaliza trabalho oculto. Endpoints: Plan · Metas.
• Quadro: onde o trabalho é acompanhado, dentro de um projeto. Um quadro tem uma chave (ENG), uma visibility e uma effective_visibility: um quadro dentro de um projeto members aparece como members, enquanto visibility continua sendo a configuração armazenada do próprio quadro. Endpoints: Plan · Quadros.

A privacidade é associação, não papel na organização: um projeto, quadro ou tarefa members é 404 para quem não tem uma concessão. Veja Autenticação para o Plan.

Colunas: estados de fluxo e categorias

As colunas de um quadro são seus estados de fluxo. Cada um tem uma de cinco categorias fixas (backlog, todo, in_progress, done, canceled), e a categoria é o que diz se o trabalho está aberto ou concluído em qualquer quadro. Um quadro deve manter pelo menos uma coluna done ativa. Aposentar uma coluna a arquiva, e ela pode ser restaurada. O estado de uma tarefa só muda movendo-a, em relação às vizinhas.

Tarefas

Uma tarefa é uma unidade de trabalho, endereçada por uuid ou por chave (ENG-142). Tem título, descrição em Markdown, prioridade, estimativa, datas, etiquetas, uma version para edições concorrentes e um estado. Arquivar é apagar, e é reversível. Endpoints: Plan · Tarefas.

Responsável, executor e executores

Campo	Significado
owner	A pessoa responsável
executor	O ator que faz o trabalho agora, quando diferente do responsável: quem está com a bola
executors	Cada agente que executou uma escrita no cartão em nome de alguém, do mais recente ao mais antigo, com first_at e last_at. No detalhe da tarefa e nas respostas de escrita de uma tarefa, não nas linhas de listas
created_by	Quem criou a tarefa

executors é separado do executor singular. Veja Agentes no Plan.

Participantes e observadores

Os participantes são as pessoas notificadas sobre uma tarefa; precisam poder ver o quadro. Um observador acompanha as notificações de uma tarefa sem estar nela (subscription). Uma pessoa também pode silenciar uma tarefa em que está. Gerenciar participantes é uma ação somente para pessoas.

Relações e subtarefas

As tarefas podem ser ligadas por relações (blocks, relates_to, duplicates; podem surgir outras, então ignore os valores que você não conhece). “Bloqueada” é derivado das relações. As subtarefas aninham um nível, ficam no mesmo quadro da tarefa pai e são listadas pelo endpoint de filhas da tarefa.

Anexos

Tarefas, comentários, metas e projetos aceitam anexos. Em uma tarefa você pode presignar, enviar os bytes e confirmar; uma única requisição multipart também funciona. Baixe pelo endpoint content/ do anexo em vez de guardar sua url. Limites e tipos aceitos estão em Erros do Plan.

Comentários

Os comentários são Markdown, mencionam pessoas com <@DB@{uuid}>, encadeiam um nível e carregam reações. Cada um tem uma provenance e, quando um agente o executou, executed_by_agent. Endpoints: Plan · Comentários e arquivos.

Marcos

Um marco é um compromisso com data dentro de um projeto. As tarefas podem apontar para um marco do projeto do seu quadro. Concluir, reabrir e aposentar são operações separadas; aposentar o arquiva e as tarefas continuam apontando para ele. A lista de marcos de toda a organização mostra todos os que você pode ver. Um marco aposentado pode ser restaurado. Os marcos aceitam anexos (até 5 MiB cada): referencie um na description do marco com um marcador attachment:{uuid} e leia attachment_count no marco.

Atualizações de projeto

Uma atualização de projeto é uma nota de status sobre um projeto, a mais recente primeiro, com um valor de health e menções. Há um resumo das atualizações mais recentes de todos os projetos que você pode ver. Uma atualização pode ser lida, editada e excluída uma a uma: somente seu autor ou autora a edita (update_not_author), e a pessoa autora ou um administrador da organização a exclui. Traz edited_at, provenance, executed_by_agent e seus attachments, e um agente pode coescrever uma atualização enviando agent_name (veja Agentes no Plan).

Etiquetas

As etiquetas são de toda a organização. Adicione, remova ou substitua as etiquetas de uma tarefa em uma única chamada em lote. Gerenciar as etiquetas da organização é uma ação somente para pessoas. Os filtros aceitam até 50 uuids de etiqueta.

Visões salvas e favoritos

Uma visão salva guarda como você olha um quadro ou projeto: filtros, ordenação, agrupamento e modo de visualização. As visões pessoais são suas; um gestor do quadro pode compartilhar uma ou torná-la a padrão. Salvar substitui toda a sua lista e exige If-Match com o ETag da sua última leitura. Os favoritos fixam quadros e visões salvas na sua lista e podem ser reordenados.

Caixa de entrada e cursor de atividade

A caixa de entrada lista os eventos que merecem uma notificação para você (o filtro mentioned=true deixa só as menções), com operações de lido, ler tudo e contagem de não lidos. O cursor de atividade é a sua marca de leitura no feed de atividade da organização: avance-o para dizer “estou em dia”. Para quadros ao vivo use o feed delta; veja a receita de quadro ao vivo.

Próximos passos

• Agentes no Plan para que um agente trabalhe um cartão como uma pessoa.
• Convenções do Plan para filtros, paginação e concorrência.