Configurar a recorrência de tarefas no Planner (versão prévia)

Este artigo descreve como usar a recorrência com tarefas do Planner para automatizar a criação de tarefas repetitivas. A propriedade de recorrência em uma tarefa do Planner permite que os usuários automatizem a criação de tarefas futuras que representam tarefas da vida real que precisam ser concluídas repetidamente.

Cenários de usuário

Os cenários a seguir são suportados:

  • Adicione o comportamento de recorrência a uma tarefa existente, criando assim uma série recorrente. Como alternativa, crie uma nova tarefa com a recorrência definida. O resultado final para ambos é o mesmo: uma tarefa recorrente, a primeira de uma série recorrente. Os usuários especificam a agenda para recorrência.

  • Edite a agenda de recorrência de uma série recorrente existente.

  • Continuar uma série. Marcar uma tarefa como concluída resulta na geração de uma nova tarefa para continuar a série, de acordo com a agenda de recorrência. Se a tarefa ativa em uma série for excluída, o usuário deverá ser solicitado a determinar se deseja continuar ou encerrar a série. Se o cliente não souber sobre a recorrência e não oferecer um prompt, a série deverá continuar. Não deve ser encerrado acidentalmente.

  • Encerrar uma série ao:

    • Excluir a tarefa ativa na série (e escolher sim para encerrar a série).
    • Encerrando a série sem excluir a tarefa ativa.

  • Reviva uma série. Se a recorrência foi encerrada, deve ser possível restabelecer a série.

Diferenças conceituais entre reuniões recorrentes e tarefas recorrentes

Esta seção descreve um cenário da vida real para tarefas recorrentes, para ilustrar as diferenças interessantes entre reuniões recorrentes e tarefas recorrentes e para explorar o espaço problemático de alterações em um padrão de recorrência.

O exemplo a seguir envolve um relatório que deve ser concluído regularmente e utiliza uma tarefa recorrente para rastrear a conclusão do relatório.

O relatório e sua tarefa associada devem ser entregues a cada 2 semanas na sexta-feira; a série começou em 14 de maio de 2021. O primeiro relatório deve ser divulgado nessa data, sexta-feira, 14 de maio. Avance para 7 de janeiro de 2022, 34 semanas depois. A pessoa que fez os relatórios tirou uma folga em dezembro e ninguém os completou. A tarefa recorrente atual (e o relatório correspondente) deve ser entregue em 10 de dezembro. O relatório e sua tarefa associada estão agora com 4 semanas de atraso.

Observação: Nesse ponto, o contraste entre reuniões e eventos recorrentes se torna aparente. As reuniões não precisam ser marcadas como concluídas para que um sistema automatizado agende a próxima reunião no calendário. A conclusão de uma tarefa atrasada pode gerar outra tarefa que deve ser concluída no passado, mas não há o conceito de concluir uma reunião no passado. A próxima instância de uma reunião está sempre no futuro, com base na data de hoje. A data de hoje não é usada para calcular datas de conclusão de tarefas recorrentes, a fim de evitar perder o controle do trabalho atrasado.

Para essa tarefa, se a agenda de recorrência não for editada e a tarefa de 10 de dezembro for marcada como concluída, a próxima tarefa da série será instanciada com a data de vencimento de 24 de dezembro.

No entanto, suponha que seja tomada uma decisão de que, daqui para frente, esse relatório deve ser feito a cada 3 semanas, em vez de a cada 2 semanas. A decisão pode até ser que a cadência de 3 semanas deve ser retroativa para os relatórios vencidos. Essa mudança convida a diferentes opções possíveis de como a continuação da série pode ser definida:

  • A data de vencimento de 10 de dezembro deve ser alterada?
  • Quando a próxima tarefa deve ser concluída?

Veja a seguir o estado atual da tarefa recorrente e da decisão:

  • A tarefa atual tem data de vencimento em 10 de dezembro de 2021.
  • A tarefa concluída anterior estava prevista para 26 de novembro de 2021.
  • É tomada a decisão de alterar a cadência de 2 semanas para 3 semanas; A alteração se aplica retroativamente aos relatórios vencidos.

Dado o contexto, duas opções são possíveis, e ambas são histórias válidas de clientes sobre como a série pode ser alterada para acomodar a nova cadência de 3 semanas.

Opção 1: Altere a tarefa de 10 de dezembro para vencer 3 semanas após a tarefa anterior de 26 de novembro. A tarefa atual tem sua data de conclusão alterada para 17 de dezembro, e a tarefa seguinte deve ser concluída em 7 de janeiro.

Opção 2: Manter a data de vencimento atual de 10 de dezembro e alterar a cadência da tarefa seguinte que deve ser concluída em 31 de dezembro.

O Planner dá suporte a essas duas opções; A data de hoje não leva em consideração como esses diferentes casos são tratados. Esse exemplo é explorado mais detalhadamente no Exemplo 1: Alterando o padrão com e sem alterações em patternStartDateTime.

Definições

Os termos a seguir são usados para discutir e descrever tarefas do Planner com recorrência:

Definição de uma tarefa com recorrência ativa

Se as três condições a seguir forem atendidas, uma plannerTask terá recorrência ativa:

  • A propriedade percentComplete tem um valor menor que 100.
  • recurrence.nextInSeriesTaskId é null ou indefinido.
  • recurrence.schedule contém um plannerRecurrenceSchedule válido com um nextOccurrenceDateTime não nulo.

Uma tarefa com recorrência ativa (chame-a de tarefa A) pode disparar o mecanismo de recorrência do serviço que cria uma nova tarefa (tarefa B) para continuar a série recorrente. Quando isso acontece, a tarefa A tem sua recurrence.nextInSeriesTaskId definida como a ID da tarefa B. Como a tarefa A não atende mais à condição 2, ela não tem mais recorrência ativa. A tarefa A nunca mais poderá ter recorrência ativa , pois nextInSeriesTaskId é uma propriedade somente leitura e o serviço nunca exclui seu valor.

Definição de uma série de recorrência

Uma série de recorrência (também conhecida como série recorrente) é uma série sequencial de tarefas. A série começa quando a recorrência é definida pela primeira vez em uma tarefa e a série continua por meio da criação automática de novas tarefas com a mesma recorrência.seriesId.

  • As tarefas que compartilham o mesmo recurrence.seriesId pertencem à mesma série de recorrência.
  • Cada tarefa na série tem uma recorrência.occurenceId distinta.
  • A primeira tarefa da série tem um occurrenceId de 1.
  • Quando a primeira tarefa tem seu mecanismo de recorrência acionado (sendo marcada como concluída ou excluída, enquanto tem recorrência ativa), a segunda tarefa é criada com um occurenceId de 2. Esse processo continua até que a série de recorrências seja encerrada.

Evitando o termo ambíguo tarefa recorrente

Na linguagem comum, o termo tarefa recorrente às vezes se refere à tarefa única com recorrência ativa dentro de uma série; e, às vezes, refere-se à própria série de recorrência ou a todas as tarefas dentro da série de recorrência. Essa ambiguidade é comum no inglês falado: da mesma forma, o relatório semanal pode se referir a uma instância do relatório ou à responsabilidade recorrente de fazer o relatório a cada semana. Devido a essa ambiguidade, evita-se o uso do termo tarefa recorrente ; Em vez disso, um dos seguintes termos é preferido: tarefa com recorrência ativa ou série de recorrência.

Detalhes do tipo de recurso

Trabalhar com a recorrência para tarefas do Planner envolve o uso de muitos tipos de recursos: plannerTaskRecurrence, plannerRecurrenceSchedule e recurrencePattern. As seções a seguir fornecem mais detalhes sobre os dois últimos tipos de recursos.

plannerRecurrenceSchedule

O plannerRecurrenceSchedule encapsula uma definição de padrão de recorrência (padrão), uma data de início para esse padrão (patternStartDateTime) e uma propriedade gerada pelo sistema que indica a próxima data de ocorrência (nextOccurrenceDateTime).

O padrão é um recurrencePattern; para obter detalhes, consulte Notas específicas do Planner sobre o recurrencePattern.

O patternStartDateTime indica a data e a hora de início da série como um DateTimeOffset. Um valor não nulo deve ser atribuído a patternStartDateTime sempre que a propriedade pattern for usada; esta é atualmente a única maneira de definir a recorrência. Os clientes geralmente devem reatribuir esse valor quando fizerem uma alteração no recurrence.schedule.pattern para indicar a data de início do novo padrão; No entanto, se os clientes não incluírem um valor, o serviço continuará a série usando um valor padrão com base na agenda. Para obter mais detalhes, consulte as notas e esclarecimentos a seguir.

O nextOccurrenceDateTime é um campo gerado pelo sistema somente leitura. Ela fornece a data calculada pelo serviço que é usada como a dueDateTime para a próxima plannerTask na série. O nextOccurrenceDateTime é calculado a partir do padrão , juntamente com o patternStartDateTime ou um valor de âncora que rastreia a data originalmente agendada da tarefa determinada.

Observação: No momento, o Planner não usa o tipo de recurso recurrenceRange .

Anotações específicas do Planner sobre o recurrencePattern

A seguir estão as restrições específicas do Planner para recurrencePattern:

  • relativeMonthly e relativeYearly os padrões podem não especificar mais de um dia para daysOfWeek.
  • Para weekly padrões, se daysOfWeek contiver mais de um dia, o intervalo deve ser 1.

Esclarecimentos sobre recurrencePattern:

  • Sempre que qualquer propriedade dentro de um recurrencePattern é alterada, todas as propriedades de padrão relevantes devem ser especificadas. Por exemplo, um padrão com tipo = daily e intervalo = 1 não pode ser corrigido apenas com intervalo = 2; caso contrário, o serviço retornará um código de 400 Bad Request resposta. A propriedade type = daily também deve ser especificada, mesmo que o tipo não esteja sendo alterado. Esse é um comportamento normal para o tipo de recurso recurrencePattern , embora algumas outras propriedades do Planner funcionem de maneira diferente.

  • As propriedades não utilizadas recebem automaticamente um valor padrão.

    • Por exemplo, a propriedade month é usada apenas para padrões anuais, com valores válidos de 1 até 12. No entanto, daily, weekly, e monthly padrões foram 0 atribuídos à propriedade month , porque 0 é o padrão para um valor inteiro.
    • As propriedades de enumeração, incluindo firstDayOfWeek e index, obtêm valores padrão que correspondem ao primeiro valor de enumeração: sunday e first, respectivamente.

  • Para absoluteMonthly padrões, se o dayOfMonth selecionado não existir em um determinado mês, o último dia do mês será substituído.

    • Exemplo: se dayOfMonth for 31 e você se repetir em abril, a data selecionada será 30 de abril.
    • Exemplo: se dayOfMonth for 29, 30ou 31 e você se repetir em fevereiro, a data selecionada será o último dia de fevereiro.

  • Da mesma forma, para absoluteYearly padrões com mês = 2 e dayOfMonth = 29, a data selecionada em anos não bissextos é 28 de fevereiro.

  • Para weekly padrões, a propriedade firstDayOfWeek é usada para distinguir entre o que é considerado esta semana e o que é considerado na próxima semana. Isso é relevante quando você altera um weekly padrão. A próxima tarefa está agendada para a próxima semana e firstDayOfWeek determina quando a próxima semana começa.

Exemplos de como firstDayOfWeek afeta as alterações em um padrão semanal

Dada uma tarefa com recorrência ativa com as seguintes propriedades:

  • Ocorre semanalmente todas as quartas-feiras: o padrão tem type = weekly, interval, = 1daysOfWeek = [wednesday] e firstDayOfWeek = sunday
  • O dueDateTime é quarta-feira 2/2
  • O nextOccurrenceDateTime é quarta-feira, 9/2

Três alterações no padrão são possíveis, e o nextOccurrenceDateTime resultante é mostrado na tabela a seguir.

Mudança de padrão NextOccurrenceDateTime resultante
Semanalmente todas as terças-feiras Terça-feira 2/8
Semanalmente, todas as quintas-feiras Quinta-feira 2/10
Semanalmente todas as quintas-feiras e firstDayOfWeek alterado para quinta-feira Quinta-feira 2/3

Observe a diferença entre quinta-feira 2/10 vs. quinta-feira 2/3. Quando firstDayOfWeek = Thursday, quinta-feira 2/3 não está na mesma semana que quarta-feira 2/2 porque uma nova semana começa na quinta-feira; enquanto que se o firstDayOfWeek não Thursdayfor , quinta-feira 2/3 estará na mesma semana que quarta-feira 2/2 e quinta-feira 2/10 será na próxima semana.

Observações sobre o agendamento e a data de conclusão

O dueDateTime pode ser editado pelos clientes para ter um valor diferente (incluindo null), sem afetar o agendamento e o nextOccurrenceDateTime. Por exemplo, se uma tarefa estiver atrasada e a data de vencimento for alterada para acomodar esse atraso, a próxima tarefa na série aparecerá como agendada originalmente, a menos que o padrão e/ou o patternStartDateTime sejam explicitamente atualizados. Portanto, adiar a data de vencimento não resulta em pular datas de acordo com o cronograma definido. Isso difere de um modelo de reunião , em que a data de hoje desempenha um papel importante na determinação de quando a próxima reunião ocorrerá. Saber a data de hoje é relevante para calcular a próxima data da reunião ou evento, mas não é relevante para calcular a data de conclusão da próxima tarefa.

Exemplo 1: Alterando o padrão com e sem alterações em patternStartDateTime

Dada uma tarefa com recorrência ativa com as seguintes propriedades:

  • O padrão de recorrência especifica a cada 2 semanas na sexta-feira, por exemplo, type = weekly, interval, = 2daysOfWeek = [friday] e firstDayOfWeek = sunday.
  • A tarefa concluída anterior estava prevista para 26 de novembro de 2021.
  • A tarefa atual deve ser entregue em 10 de dezembro de 2021.
  • O nextOccurrenceDateTime é 24 de dezembro de 2021 (duas semanas após a data de vencimento atual).

É tomada a decisão de alterar a cadência de 2 semanas para 3 semanas. Assim, o padrão é modificado para ter intervalo = 3 junto com os mesmos valores para semanalmente às sextas-feiras.

Três possibilidades distintas são examinadas, cada uma produzindo datas de vencimento diferentes para a próxima tarefa da série:

Alterar descrição NextOccurrenceDateTime resultante
Altere o patternStartDateTime para 10 de dezembro de 2021 sexta-feira, 31 de dezembro de 2021
Altere o patternStartDateTime para 17 de dezembro de 2021 7 de janeiro de 2022
Não altere o patternStartDateTime sexta-feira, 31 de dezembro de 2021

No primeiro exemplo, o patternStartDateTime é definido como o mesmo valor que o dueDateTime, por exemplo, 10 de dezembro. O nextOccurrenceDateTime é definido como 3 semanas após o patternStartDateTime, sendo 31 de dezembro. Conceitualmente, isso representa a alteração de cadência que entra em vigor apenas para a tarefa seguinte, e não para esta tarefa.

No segundo exemplo, o patternStartDateTime é definido para ser 3 semanas após 26 de novembro, sendo 17 de dezembro. Novamente, o nextOccurrenceDateTime é definido como 3 semanas após o patternStartDateTime, desta vez em 7 de janeiro. Conceitualmente, isso representa a alteração de cadência que entra em vigor a partir de 26 de novembro (a tarefa anterior) em vez de 10 de dezembro (data de conclusão original da tarefa atual).

Geralmente, recomendamos que o dueDateTime de uma tarefa seja alterado para coincidir com um novo patternStartDateTime; No entanto, isso não é necessário. Se o dueDateTime não for alterado junto com o patternStartDateTime no segundo exemplo, os usuários continuarão a ver uma data de conclusão de 10 de dezembro para a tarefa atual. Quando estiver concluída, a próxima tarefa da série será agendada para 7 de janeiro. Como isso pode ser confuso para os usuários, recomendamos que você atribua dueDateTime e patternStartDateTime juntos.

O terceiro exemplo é semelhante ao primeiro, exceto que não especifica o patternStartDateTime. Um patternStartDateTime que é muito antigo, como em agosto, não pode ser usado. Nesse caso, nextOccurrenceDateTime é calculado com base na data de vencimento original de 10 de dezembro, resultando em nextOccurrenceDateTime de 31 de dezembro, semelhante ao primeiro exemplo. Observe que a data de vencimento original não é exposta, embora seja usada neste cálculo. Isso significa que o dueDateTime pode ser alterado para outro valor ou até mesmo alterado para ser null, mas o valor dueDateTime é ignorado para esse cálculo, usando a data de vencimento original. Esse é outro motivo pelo qual recomendamos que você altere dueDateTime e patternStartDateTime juntos.

Exemplo 2: a data de conclusão não afeta a próxima ocorrência

Dada uma tarefa com recorrência ativa com as seguintes propriedades:

  • Ocorre semanalmente todas as quartas-feiras: o padrão tem type = weekly, interval, = 1daysOfWeek = [wednesday] e firstDayOfWeek = sunday.
  • O dueDateTime é qua 16/02.
  • O nextOccurrenceDateTime é Wed 2/9.
  • A data de vencimento original é quarta-feira, 2/2. Esse valor não é exposto publicamente, embora possa ser inferido de nextOccurrenceDateTime.

A seguir, um exame de três possíveis mudanças.

Alteração NextOccurrenceDateTime resultante
Sem alteração Terça-feira 2/9
o padrão mudou para ser semanal todas as quintas-feiras; nenhuma alteração no patternStartDateTime Quinta-feira 2/10
patternStartDateTime alterado para 2/9; Nenhuma alteração no padrão Quarta-feira 16/02

Em todos os três exemplos, o dueDateTime não é alterado de seu valor modificado de quarta-feira, 16/02, e a próxima tarefa na série é criada com um dueDateTime igual ao nextOccurrenceDateTime na tabela anterior.

Observação:

  • O comportamento padrão, quando patternStartDateTime não é reatribuído explicitamente, é que a agenda continua com base na data de conclusão original. Nesse caso, a data de vencimento original é 2/2, enquanto a dueDateTime atual é 16/2.
  • Se o patternStartDateTime for alterado, o nextOccurrenceDateTime será recalculado usando essa nova data de início.
  • Se a data de conclusão for alterada em null vez de 16/02, ou para qualquer outra data no futuro ou no passado, os exemplos anteriores não serão afetados.

Cenários do desenvolvedor

Criar uma série recorrente

O recurrence.schedule é a única subpropriedade editável pelo cliente de recorrência. Ao adicionar um recurrence.schedule (independentemente de a recorrência já estar definida ou não), os clientes podem transformar uma tarefa não recorrente em uma tarefa com recorrência ativa.

As outras duas condições mencionadas na definição de recorrência ativa influenciam se um cronograma de recorrência pode ser adicionado:

  • A propriedade percentComplete deve ser menor que 100.
  • A propriedade recurrence.nextInSeriesTaskId deve ser null ou não atribuída.

Outras subpropriedades de recorrência são somente leitura. Se eles ainda não tiverem sido atribuídos, o serviço os gerará automaticamente quando o recurrence.schedule for adicionado.

Recorrência do gatilho

O diagrama a seguir mostra duas maneiras pelas quais um mecanismo de recorrência pode ser disparado em uma tarefa com recorrência ativa:

Na definição anterior de um _task com recorrência ativa, se qualquer uma das três condições não for atendida, o mecanismo de recorrência não será disparado (nenhuma nova tarefa será criada e nextInSeriesTaskId não será atribuída).

A instanciação da nova tarefa geralmente acontece imediatamente, o que ocasionalmente causa um atraso na criação da nova tarefa.

A nova tarefa tem as seguintes propriedades copiadas da tarefa agora concluída: título, descrição, itens da lista de verificação (definidos como incompletos), atribuições, prioridade e categorias. O percentComplete da nova tarefa é definido como 0. O dueDateTime da nova tarefa é definido de acordo com a agenda de recorrência. As seguintes subpropriedades de recorrência são copiadas: seriesId, recurrenceStartDateTime e schedule; schedule.nextOccurrenceDateTime foi calculado recentemente para a nova tarefa. As outras propriedades de recorrência recebem valores apropriados para a nova tarefa.

Descubra a próxima tarefa em uma série

Se a tarefa C tiver a recorrência definida e um usuário marcar a tarefa C como concluída (percentComplete = 100), a tarefa D será criada para continuar a série de recorrência. A tarefa C tem sua propriedade recurrence.nextInSeriesTaskId preenchida com a ID da tarefa D.

Por outro lado, se a tarefa C for excluída e a exclusão disparar a recorrência, um cliente deverá descobrir a ID da tarefa D por outros meios. Por exemplo, consultando tarefas no mesmo bucket ou consumindo o feed de sincronização delta.

Editar uma série recorrente

Uma tarefa com recorrência ativa pode ter seu cronograma de recorrência editado. Observe que recurrence.schedule é a única subpropriedade de recurrence que pode ser editada.

Por exemplo, uma tarefa com recorrência ativa e um cronograma de semanal todas as quartas-feiras pode ter seu cronograma alterado para mensal no 15º dia de cada mês.

Encerrar uma série recorrente

Para encerrar uma série recorrente, defina a propriedade recurrence.schedule como null. Você só pode fazer isso quando nextInSeriesTaskId for null ou não atribuído.

Reviver recorrência após o término

Depois de remover o recurrence.schedule, você pode adicionar um novo recurrence.schedule à tarefa que revive a série.

Siga as etapas anteriores para Criar uma série recorrente. As mesmas restrições se aplicam. O recurrence.seriesId original e outras subpropriedades de recorrência permanecem inalterados, restabelecendo ou continuando efetivamente a série original.

Identificar a tarefa com recorrência ativa, dentro de uma série de recorrência

Dado um recurrence.seriesId, no máximo uma tarefa com esse seriesId pode ter recorrência ativa.

As tarefas concluídas ficam ocultas da maioria dos modos de exibição. É incomum que um usuário esteja visualizando uma tarefa que foi marcada como concluída. As tarefas excluídas não podem ser exibidas. Isso significa que, na maioria dos casos, existe apenas uma tarefa com recorrência ativa em uma série de recorrências. Se a tarefa com recorrência ativa teve sua recorrência desativada por meio da exclusão do agendamento, não existem tarefas com recorrência ativa nessa série.

Cenários raros excepcionais

Os cenários a seguir são raros, embora possíveis. Embora possam parecer exceções para um cliente, na verdade o serviço sempre mantém a integridade da regra: no máximo uma tarefa com recorrência ativa em uma determinada série de recorrências. A orientação é dada para a desambiguação.

Causas

O diagrama a seguir mostra duas causas possíveis para as informações que parecem estar fora de sincronia:

  • As informações ainda não chegaram ao armazenamento rápido voltado para o cliente do Planner. A fonte de informações autoritativa do Planner tem os dados, mas os dados ainda não foram replicados para o armazenamento otimizado para solicitação que retorna dados aos clientes.

  • O mecanismo de recorrência encontrou uma falha temporária. Isso significa que a nova tarefa para continuar uma série ainda não foi criada; Geralmente é criado em alguns segundos ou minutos.

Duas tarefas com recorrência ativa na mesma série de recorrência

Se um cliente observar duas tarefas com recorrência ativa na mesma série de recorrência, pode-se supor que a tarefa com o occurrenceId menor já teve seu mecanismo de recorrência disparado. O armazenamento de back-end do Planner tem o nextInSeriesTaskId definido, mas essas informações ainda não chegaram ao armazenamento rápido voltado para o cliente. A tarefa com o occurrenceId maior é a tarefa exclusiva com recorrência ativa.

Uma tarefa com recorrência ativa tem um occurrenceId menor do que outra na mesma série de recorrência

Semelhante às "duas tarefas com recorrência ativa" anteriores, esta segunda situação pode ser observada se a tarefa com o occurrenceId maior tiver sua recorrência desativada (recurrence.schedule = null). A existência de uma tarefa com um occurrenceId maior implica que todas as tarefas com occurrenceId menor nessa série não têm recorrência ativa, mesmo que a tarefa com o occurrenceId maior também não tenha recorrência ativa .

Zero tarefas com recorrência ativa em uma série

Esta é uma situação verdadeiramente ambígua, pois qualquer um dos seguintes pode ser o caso:

  • O mecanismo de recorrência foi retardado por uma falha transitória; ela será tentada novamente.
  • O mecanismo de recorrência foi bem-sucedido, mas a nova tarefa ainda não foi adicionada ao armazenamento rápido voltado para o cliente.
  • A nova tarefa foi criada, mas depois foi excluída por outro cliente.

Os dois primeiros são estados temporários, que têm a garantia de serem corrigidos pelo serviço, normalmente dentro de alguns segundos ou minutos. O terceiro é geralmente permanente. Provavelmente é impreciso descrever esse cenário como raro ou excepcional; No entanto, foi descrito anteriormente para chamar a atenção para o fato de que há ambigüidade no estado observado devido à possibilidade dos dois primeiros casos.

Localizar todas as tarefas em uma série recorrente

Os desenvolvedores que trabalham com o Planner estão familiarizados com a API existente para obter todas as tarefas em um plano. O Planner ainda não tem uma API para obter todas as tarefas em uma série de recorrência; No entanto, obtendo todas as tarefas em um plano, você geralmente pode obter todas as tarefas em uma série de recorrência.

A propriedade recurrence.seriesId em cada plannerTask é um identificador distinto de uma série recorrente específica à qual uma ou mais tarefas pertencem. Quando atribuído, esse valor nunca poderá ser alterado. O recurrence.occurrenceId é um valor inteiro que indica a ordem das tarefas em uma série. A primeira tarefa em uma série (a tarefa em que a recorrência foi adicionada pela primeira vez) recebe uma occurrenceId de 1.

Observação:

  • Se algumas tarefas da série foram excluídas, os índices podem conter lacunas.
  • Se os usuários moveram a série recorrente para um plano diferente, você precisará procurar em outros planos para ver outras tarefas na série; No entanto, os usuários geralmente estão interessados principalmente nas séries recorrentes em um plano. As tarefas não podem ser movidas entre os limites do grupo; Se todos os planos de um grupo forem consultados, você poderá encontrar todas as tarefas que poderiam ter sido movidas para fora do plano original.

Exemplos de operação REST

As solicitações e respostas a seguir representam uma sequência ordenada de operações. Eles podem ser usados como casos de teste para clientes que implementam a recorrência de tarefas do Planner, substituindo identificadores apropriados (para tarefa, plano, série de recorrência e assim por diante). Muitos casos de erro são intercalados para ilustrar alterações incorretas em estados específicos.

Adicionar uma data de conclusão e recorrência a um plannerTask existente

O exemplo de solicitação e resposta a seguir mostra como se recorrência a uma tarefa. A tarefa com ID Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV já existe e tem recorrência = null. Para adicionar a recorrência, você precisa atribuir as propriedades necessárias de recurrence.schedule. As propriedades recurrencePattern não utilizadas (month, dayOfMonth, firstDayOFWeek e index) não devem ser incluídas.

Solicitação

PATCH https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "daily",
                "interval": 2
            },
            "patternStartDateTime": "2021-11-13T10:30:00Z"
        }
    },
    "dueDateTime": "2021-11-13T10:30:00Z"
}

Resposta

HTTP/1.1 204 NO CONTENT

Obter a tarefa anterior

O exemplo de solicitação e resposta a seguir mostra como recuperar a tarefa com a recorrência recém-adicionada.

Solicitação

GET https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

Resposta

A seguir estão observações sobre a resposta:

  • As propriedades recurrencePattern não utilizadas (mês, dayOfMonth, firstDayOFWeek e índice) recebem valores padrão pelo serviço.
  • O nextOccurrenceDateTime é calculado a partir do agendamento. Nesse caso, o patternStartDateTime é 13 de novembro e o padrão define dia sim, dia não; isso dá um nextOccurrenceDateTime de dois dias após o patternStartDateTime, sendo 15 de novembro.
  • O seriesId e o occurrenceId são gerados automaticamente. O seriesId é um novo GUID, codificado no formato de identificador do Planner. Como essa é a primeira tarefa de uma série, ela recebe um occurrenceId de 1.
  • O recurrenceStartDateTime recebe o mesmo valor que o patternStartDateTime. Isso é verdadeiro para a primeira tarefa em uma série (occurrenceId = 1). No entanto, para tarefas futuras na série, o valor de recurrenceStartDateTime não é alterado, mesmo que o patternStartDateTime seja alterado; Ele rastreia o início da recorrência, em contraste com as mudanças de padrão.
  • O previousInSeriesTaskId é sempre null, porque esta é a primeira tarefa na série (occurrenceId = 1).
  • O nextInSeriesTaskId é atribuído se e quando a próxima tarefa é criada para continuar a série.
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#planner/tasks/$entity",
    "@odata.etag": "W/\"JzEtVGFzayAgQEBAQEBAQEBAQEBAQEBASCc=\"",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "orderHint": "8586352620867692777",
    "assigneePriority": "",
    "percentComplete": 0,
    "priority": 5,
    "startDate": null,
    "createdDateTime": "2019-08-20T23:46:38.708303Z",
    "hasDescription": false,
    "previewType": "automatic",
    "completedDateTime": null,
    "completedBy": null,
    "referenceCount": 0,
    "checklistItemCount": 0,
    "activeChecklistItemCount": 0,
    "conversationThreadId": null,
    "id": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
    "createdBy": {
        "user": {
            "displayName": null,
            "id": "edcfc4b0-be77-4866-948a-b93267e151f8"
        }
    },
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 1,
        "previousInSeriesTaskId": null,
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-15T10:30:00Z",
            "pattern": {
                "type": "daily",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2021-11-13T10:30:00Z",
    "creationSource": null
}

Marcar a tarefa como concluída, disparando a recorrência (1ª tarefa da série)

O exemplo de solicitação e resposta a seguir mostra como definir percentComplete como 100 (também conhecido como conclusão da tarefa ou marcação da tarefa como concluída).

Solicitação

O exemplo a seguir mostra uma solicitação idêntica para uma tarefa com ou sem recorrência.

PATCH https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

{
    "percentComplete": 100
}

Resposta

HTTP/1.1 204 NO CONTENT

Obtenha a tarefa agora concluída e descubra a ID da próxima (2ª) tarefa da série

O exemplo de solicitação e resposta a seguir mostra como recuperar a tarefa depois que ela tiver sido marcada como concluída.

Solicitação

GET https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

Resposta

O exemplo a seguir mostra uma solicitação. Como nextInSeriesTaskId está atribuído, essa tarefa não pode mais ter a recorrência ativa configurada.

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "percentComplete": 100,
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 1,
        "previousInSeriesTaskId": null,
        "nextInSeriesTaskId": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-15T10:30:00Z",
            "pattern": {
                "type": "daily",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2021-11-13T10:30:00Z",
}

Obter a nova tarefa na série (2ª ocorrência)

O exemplo de solicitação e resposta a seguir mostra como recuperar a nova tarefa na série, cuja ID foi descoberta da nextInSeriesTaskId na resposta anterior.

Solicitação

O exemplo de solicitação (GxOo0ms1iEu3eBI1-6lk85UAI5FI) contém as seguintes diferenças quando comparado com o exemplo anterior (Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV):

  • dueDateTime recebeu o valor do nextOccurrenceDateTime anterior da tarefa.
  • nextOccurrenceDateTime foi calculado de acordo com o agendamento: a próxima ocorrência após a dueDateTime anterior.
  • occurrenceId é 2 em vez de 1
  • percentComplete é 0.
GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Resposta

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-17T10:30:00Z",
            "pattern": {
                "type": "daily",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2021-11-15T10:30:00Z"
}

Edite a recorrência da tarefa para ser um dia por semana e defina a data de conclusão como nula

O exemplo de solicitação e resposta a seguir mostra como atribuir um nulldueDateTime e um padrão diferente a uma tarefa com recorrência ativa.

Solicitação

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "weekly",
                "interval": 1,
                "daysOfWeek": [ "tuesday" ],
                "firstDayOfWeek": "sunday"
            }
        }
    },
    "dueDateTime": null
}

Resposta

HTTP/1.1 204 NO CONTENT

Obtenha a tarefa novamente para ver o resultado da edição

O exemplo de solicitação e resposta a seguir mostram como recuperar a tarefa após as edições anteriores. Você pode esperar ver o recurrence.schedule.pattern especificado anteriormente: semanalmente às terças-feiras, junto com dueDateTime = null.

Solicitação

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Resposta

No exemplo a seguir, uma tarefa pode ter recorrência ativa junto com uma null data de conclusão. O nextOccurrenceDateTime é recalculado e agora é em 23 de novembro, uma terça-feira, a partir de daysOfWeek. Essa próxima ocorrência é calculada com base no dueDateTime original da tarefa de 15 de novembro, uma segunda-feira.

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-23T10:30:00Z",
            "pattern": {
                "type": "weekly",
                "interval": 1,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [ "tuesday" ],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": null
}

Remover o agendamento de recorrência

O exemplo de solicitação e resposta a seguir mostra como atribuir um nullrecurrence.schedule, encerrando assim a recorrência nessa tarefa.

Solicitação

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": null
    }
}

Resposta

HTTP/1.1 204 NO CONTENT

Excluir a tarefa com o agendamento de recorrência

O exemplo de solicitação e resposta a seguir mostram como recuperar a tarefa após as edições anteriores.

Solicitação

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Resposta

Veja a seguir um exemplo de resposta que tem as informações da série de recorrência retidas (recurrence.schedule = null). Se uma nova agenda for especificada, essa tarefa ainda pertencerá à mesma série.

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "schedule": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z"
    },
    "dueDateTime": null
}

Caso de erro: tentativa de adicionar um novo agendamento de recorrência sem especificar o patternStartDateTime

O exemplo de solicitação e resposta a seguir mostram uma solicitação incorreta, uma tentativa de adicionar um novo recurrence.schedule sem especificar o patternStartDateTime.

Solicitação

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "daily",
                "interval": 5
            }
        }
    }
}

Resposta

Veja a seguir um exemplo de resposta que mostra um erro que descreve o problema. O objeto de resposta contém um bug porque a mensagem de erro deve fazer uma menção Recurrence.Schedule.PatternStartDateTime em vez de Recurrence.Schedule.Range. Este é um problema conhecido no momento.

HTTP/1.1 400 BAD REQUEST
Content-type: application/json

{
    "error": {
        "code": "",
        "message": "Schema validation has failed. Validation for field 'Recurrence.Schedule.Range', on entity 'Task' has failed: A non-null value must be specified for this field.",
        "innerError": {
            "request-id": "922f7646-513a-4f63-a231-9cf2d7b647cb",
            "date": "2021-06-22T21:37:35"
        }
    }
}

Restabeleça a recorrência na tarefa adicionando um novo agendamento

O exemplo de solicitação e resposta a seguir mostra como atribuir um novo recurrence.schedule a uma tarefa que atualmente tem recurrence.schedule = null.

Observação: O dueDateTime não está atribuído.

Solicitação

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "dayOfMonth": 25
            },
            "patternStartDateTime": "2021-11-25T10:30:00Z"
        }
    }
}

Resposta

HTTP/1.1 204 NO CONTENT

Obter a tarefa com o novo agendamento de recorrência

O exemplo de solicitação e resposta a seguir mostra como recuperar a tarefa com a nova agenda de recorrência. As propriedades de recorrência (exceto agendamento) permanecem inalteradas e a tarefa tem recorrência ativa, mesmo enquanto a propriedade dueDateTime permanece null.

Solicitação

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Resposta

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-25T10:30:00Z",
            "nextOccurrenceDateTime": "2022-01-25T10:30:00Z",
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 25,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": null
}

Caso de erro: Tentativa de editar uma propriedade somente leitura

O exemplo de solicitação e resposta a seguir mostram uma solicitação incorreta, uma tentativa de atribuir um valor à propriedade recurrence.seriesId que é somente leitura.

Solicitação

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "seriesId": "abc"
    }
}

Resposta

O objeto de resposta a seguir mostra um erro que descreve o problema.

HTTP/1.1 400 BAD REQUEST
Content-type: application/json

{
    "error": {
        "code": "",
        "message": "Invalid recurrence sub-property assignment(s): \"seriesId\".",
        "innerError": {
            "request-id": "922f7646-513a-4f63-a231-9cf2d7b647cb",
            "date": "2021-06-22T21:37:35"
        }
    }
}

Marcar a tarefa como concluída, disparando a recorrência (2ª tarefa da série, com nulo dueDateTime)

O exemplo de solicitação e resposta a seguir mostra como definir percentComplete como 100 (também conhecido como conclusão da tarefa ou marcação da tarefa como concluída).

Solicitação

A solicitação a seguir é idêntica para uma tarefa com ou sem recorrência.

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "percentComplete": 100
}

Resposta

HTTP/1.1 204 NO CONTENT

Obtenha a tarefa agora concluída e descubra a ID da próxima (terceira) tarefa da série

O exemplo de solicitação e resposta a seguir mostra como recuperar a tarefa depois que ela tiver sido marcada como concluída.

Solicitação

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Resposta

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 100,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": "-6zr7XfE6E2JvxCSmE7Wdf8AClON",
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-25T10:30:00Z",
            "nextOccurrenceDateTime": "2022-01-25T10:30:00Z",
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 25,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": null
}

Caso de erro: Tentativa de excluir o agendamento de recorrência quando o nextInSeriesTaskId já estiver atribuído

O exemplo de solicitação e resposta a seguir mostram uma solicitação incorreta, uma tentativa de atribuir um valor à propriedade recurrence.schedule após a atribuição da propriedade nextInSeriesTaskId .

Solicitação

PATCH https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

{
    "recurrence": {
        "schedule": null
    }
}

Resposta

O objeto de resposta a seguir mostra um erro que descreve o problema.

HTTP/1.1 400 BAD REQUEST
Content-type: application/json

{
    "error": {
        "code": "",
        "message": "Schema validation has failed. Validation for field 'Recurrence', on entity 'Task' has failed: Cannot add/edit/delete recurrence when the next instance should already be created.",
        "innerError": {
            "request-id": "922f7646-513a-4f63-a231-9cf2d7b647cb",
            "date": "2021-06-22T21:37:35"
        }
    }
}

Obter a nova tarefa na série (3ª ocorrência)

O exemplo de solicitação e resposta a seguir mostra como recuperar a nova tarefa na série, ID para a qual você descobriu a partir do nextInSeriesTaskId na resposta anterior. O dueDateTime foi atribuído ao valor apresentado no nextOccurrenceDateTime anterior da tarefa, mesmo que o dueDateTime anterior da tarefa fosse null.

Solicitação

GET https://graph.microsoft.com/beta/planner/tasks/-6zr7XfE6E2JvxCSmE7Wdf8AClON

Resposta

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "-6zr7XfE6E2JvxCSmE7Wdf8AClON",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 3,
        "previousInSeriesTaskId": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-25T10:30:00Z",
            "nextOccurrenceDateTime": "2022-03-25T10:30:00Z",
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 25,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2022-01-25T10:30:00Z"
}
  • Última atualização em