Compartilhar via

Configurar a periodicidade de tarefas no Planner (pré-visualização)

  • Artigo

Este artigo descreve como utilizar a periodicidade com as tarefas do Planner para automatizar a criação de tarefas repetitivas. A propriedade periodicidade numa tarefa do Planner permite aos utilizadores automatizar a criação de tarefas futuras que representam tarefas reais que precisam de ser concluídas repetidamente.

Cenários de usuário

Os cenários a seguir são suportados:

  • Adicione o comportamento de periodicidade a uma tarefa existente, criando assim uma série periódica. Em alternativa, crie uma nova tarefa com periodicidade definida. O resultado final para ambos é o mesmo: uma tarefa periódica, a primeira numa série periódica. Os utilizadores especificam a agenda de periodicidade.

  • Edite a agenda de periodicidade de uma série periódica existente.

  • Continue uma série. Marcar uma tarefa concluída resulta na geração de uma nova tarefa para continuar a série, de acordo com a agenda de periodicidade. Se a tarefa ativa numa série for eliminada, deverá ser pedido ao utilizador para determinar se pretende continuar ou terminar a série. Se o cliente não souber da periodicidade e não oferecer um pedido, a série deverá continuar. Não deve ser terminado acidentalmente.

  • Terminar uma série por:

    • Eliminar a tarefa ativa na série (e escolher sim para terminar a série).
    • Terminar a série sem eliminar a tarefa ativa.

  • Revive uma série. Se a periodicidade tiver sido terminada, deverá ser possível restabelecer a série.

Diferenças conceptuais entre reuniões periódicas e tarefas periódicas

Esta secção descreve um cenário da vida real para tarefas periódicas, para ilustrar as diferenças interessantes entre reuniões periódicas e tarefas periódicas e explorar o espaço problemático das alterações a um padrão de periodicidade.

O exemplo seguinte envolve um relatório que tem de ser concluído regularmente e utiliza uma tarefa periódica para controlar a conclusão do relatório.

O relatório e a tarefa associada devem ser apresentados a cada 2 semanas na sexta-feira; a série começou a 14 de maio de 2021. O primeiro relatório está previsto para essa data, sexta-feira, 14 de maio. Avancemos para 7 de janeiro de 2022, 34 semanas depois. A pessoa que fez os relatórios tirou algum tempo de folga em Dezembro, e ninguém completou os relatórios. A tarefa periódica atual (e o relatório correspondente) está prevista para 10 de dezembro. O relatório e a tarefa associada estão agora 4 semanas em atraso.

Nota: Neste momento, o contraste entre reuniões periódicas e eventos torna-se evidente. As reuniões não precisam de ser marcadas como concluídas para que um sistema automatizado agende a próxima reunião no calendário. Concluir uma tarefa em atraso pode gerar outra tarefa que está para ser concluída no passado, mas não existe nenhum conceito de conclusão de uma reunião no passado. A próxima instância de uma reunião é sempre no futuro, com base na data atual. A data de hoje não é utilizada para calcular datas para conclusão de tarefas periódicas, de modo a evitar perder o controlo do trabalho atrasado.

Para esta tarefa, se a agenda de periodicidade não for editada e a tarefa de 10 de dezembro estiver marcada como concluída, a tarefa seguinte da série será instanciada com uma data para conclusão de 24 de dezembro.

No entanto, suponhamos que é tomada uma decisão que, daqui para a frente, este relatório deve ser feito a cada 3 semanas, em vez de a cada duas semanas. A decisão pode até ser a de que a cadência de três semanas deve ser retroactiva para os relatórios em atraso. Esta alteração convida a diferentes opções possíveis para a forma como a continuação da série pode ser definida:

  • A data para conclusão de 10 de dezembro deve ser alterada?
  • Quando deve ser concluída a próxima tarefa?

Segue-se o estado atual da tarefa periódica e a decisão:

  • A tarefa atual tem uma data para conclusão de 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 aplica-se retroativamente aos relatórios em atraso.

Tendo em conta o contexto, são possíveis duas opções e ambas são histórias de clientes válidas 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 3 semanas após a tarefa anterior de 26 de novembro. A tarefa atual tem a data para conclusão alterada para 17 de dezembro e a tarefa seguinte está prevista para 7 de janeiro.

Opção 2: mantenha a data para conclusão atual de 10 de dezembro e altere a cadência da tarefa seguinte que está para ser concluída a 31 de dezembro.

O Planner suporta ambas as opções; a data de hoje não tem em conta a forma como estes diferentes casos são processados. Este exemplo é explorado ainda mais no Exemplo 1: alterar o padrão com e sem alterações a patternStartDateTime.

Definições

Os seguintes termos são utilizados para discutir e descrever tarefas do Planner com periodicidade:

Definição de uma tarefa com periodicidade ativa

Se as três condições seguintes forem cumpridas, uma plannerTask tem periodicidade ativa:

  • A propriedade percentComplete tem um valor inferior a 100.
  • recurrence.nextInSeriesTaskId is null or undefined.
  • recurrence.schedule contém um plannerRecurrenceSchedule válido com um nextOccurrenceDateTime não nulo.

Uma tarefa com periodicidade ativa (chamar-lhe tarefa A) pode acionar o mecanismo de periodicidade do serviço que cria uma nova tarefa (tarefa B) para continuar a série periódica. Quando isso acontece, a tarefa A tem recurrence.nextInSeriesTaskId definido como o ID da tarefa B. Uma vez que a tarefa A já não cumpre a condição 2, já não tem periodicidade ativa. A Tarefa A nunca mais poderá ter periodicidade ativa , uma vez que nextInSeriesTaskId é uma propriedade só de leitura e o serviço nunca elimina o respetivo valor.

Definição de uma série de periodicidade

Uma série de periodicidade (também conhecida como série periódica) é uma série sequencial de tarefas. A série começa quando a periodicidade é definida pela primeira vez numa tarefa e a série continua através da criação automática de novas tarefas com o mesmo recurrence.seriesId.

  • As tarefas que partilham o mesmo recurrence.seriesId pertencem à mesma série de periodicidade.
  • Cada tarefa na série tem um recurrence.occurenceId distinto.
  • A primeira tarefa da série tem um occurrenceId de 1.
  • Quando a primeira tarefa tem o mecanismo de periodicidade acionado (ao ser marcada como concluída ou eliminada, enquanto tem periodicidade ativa), a segunda tarefa é criada com um occurenceId de 2. Este processo continua até que a série de periodicidade seja terminada.

Evitar o termo ambíguo de tarefa periódica

Na voz comum, o termo tarefa periódica refere-se, por vezes, à tarefa exclusiva com periodicidade ativa numa série; e, por vezes, refere-se à própria série de periodicidade ou a todas as tarefas na série de periodicidade. Esta ambiguidade é comum em inglês falado: da mesma forma, o relatório semanal pode referir-se a uma instância do relatório ou à responsabilidade recorrente de fazer o relatório todas as semanas. Devido a esta ambiguidade, evita-se a utilização do termo tarefa periódica; em vez disso, é preferível um dos seguintes termos: tarefa com periodicidade ativa ou série de periodicidade.

Detalhes do tipo de recurso

Trabalhar com periodicidade para tarefas do Planner implica a utilização de muitos tipos de recursos: plannerTaskRecurrence, plannerRecurrenceSchedule e recurrencePattern. as secções seguintes fornecem mais detalhes sobre os dois últimos tipos de recursos.

plannerRecurrenceSchedule

O plannerRecurrenceSchedule encapsula uma definição de padrão de periodicidade (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, veja Notas específicas do Planner sobre a periodicidadePatterno.

O patternStartDateTime indica a data e hora de início da série como um DateTimeOffset. Tem de ser atribuído um valor não nulo a patternStartDateTime sempre que a propriedade do padrão for utilizada; esta é a única forma de definir a periodicidade. Geralmente, os clientes devem reatribuir este valor quando efetuam uma alteração ao 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 utilizando um valor predefinido com base na agenda. Para obter mais detalhes, veja as seguintes notas e esclarecimentos.

NextOccurrenceDateTime é um campo só de leitura gerado pelo sistema. Fornece a data calculada pelo serviço que é utilizada como dueDateTime para o plannerTask seguinte na série. NextOccurrenceDateTime é calculado a partir do padrão juntamente com o padrãoStartDateTime ou um valor de âncora que controla a data agendada originalmente da tarefa especificada.

Nota: O Planner não utiliza atualmente o tipo de recurso recurrenceRange .

Notas específicas do Planner sobre o recurrencePattern

Seguem-se restrições específicas do Planner para recurrencePattern:

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

Esclarecimentos sobre recurrencePattern:

  • Sempre que qualquer propriedade dentro de um recurrencePattern for alterada, todas as propriedades de padrão relevantes têm de 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 devolve um 400 Bad Request código de resposta. A propriedade type = daily também tem de ser especificada, mesmo que o tipo não esteja a ser alterado. Este é um comportamento normal para o tipo de recurso recurrencePattern , embora algumas outras propriedades do Planner funcionem de forma diferente.

  • As propriedades não utilizadas são atribuídas automaticamente a um valor predefinido.

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

  • Para absoluteMonthly padrões, se dayOfMonth selecionado não existir num mês específico, o último dia do mês é substituído.

    • Exemplo: se dayOfMonth for 31 e se repetir para abril, a data selecionada é 30 de abril.
    • Exemplo: se dayOfMonth for 29, 30ou 31 e se repetir para fevereiro, a data selecionada é 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 primeira propriedadeDayOfWeek é utilizada para distinguir entre o que é considerado esta semana e o que é considerado na próxima semana. Isto é relevante quando altera um weekly padrão. A tarefa seguinte está agendada para a próxima semana e firstDayOfWeek determina quando começa a próxima semana .

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

Foi atribuída uma tarefa com periodicidade ativa com as seguintes propriedades:

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

São possíveis três alterações ao padrão e as nextOccurrenceDateTime resultantes são apresentadas na tabela seguinte.

Alteração do 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 primeiroDayOfWeek alterados para quinta-feira Quinta-feira 2/3

Note a diferença de quinta-feira 2/10 vs. quinta-feira 2/3. Quando firstDayOfWeek = Thursday, quinta-feira 2/3 não é na mesma semana que quarta-feira 2/2 porque uma nova semana começa na quinta-feira; enquanto que se o primeiroDayOfWeek não Thursdayfor , então quinta-feira 2/3 é na mesma semana que quarta-feira 2/2, e quinta-feira 2/10 é na próxima semana.

Notas sobre o agendamento e a data para conclusão

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

Exemplo 1: alterar o padrão com e sem alterações a patternStartDateTime

Foi atribuída uma tarefa com periodicidade ativa com as seguintes propriedades:

  • O padrão de periodicidade especifica a cada 2 semanas na sexta-feira, por exemplo, tipo = weekly, intervalo = 2, daysOfWeek = [friday], e firstDayOfWeek = sunday.
  • A tarefa concluída anterior estava prevista para 26 de novembro de 2021.
  • A tarefa atual está prevista para 10 de dezembro de 2021.
  • NextOccurrenceDateTime é 24 de dezembro de 2021 (duas semanas após a data para conclusão atual).

É tomada a decisão de mudar a cadência de 2 semanas para 3 semanas. Assim, o padrão é modificado para ter intervalo = 3 juntamente com os mesmos valores para as sextas-feiras semanais.

São examinadas três possibilidades distintas, cada uma com datas para conclusão diferentes para a próxima tarefa da série:

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

No primeiro exemplo, o patternStartDateTime está definido para ser o mesmo valor que dueDateTime, por exemplo, 10 de dezembro. NextOccurrenceDateTime está definido para 3 semanas após o padrãoStartDateTime, sendo 31 de dezembro. Conceptualmente, isto representa a alteração da cadência que produz efeitos apenas para a tarefa seguinte e não para esta tarefa.

No segundo exemplo, patternStartDateTime está definido como 3 semanas após 26 de novembro, sendo 17 de dezembro. Novamente, nextOccurrenceDateTime está definido para 3 semanas após o padrãoStartDateTime, desta vez 7 de janeiro. Conceptualmente, isto representa a alteração da cadência que tem efeito a partir de 26 de novembro (a tarefa anterior) em vez de a partir de 10 de dezembro (data para conclusão original da tarefa atual).

Geralmente, recomendamos que o dueDateTime de uma tarefa seja alterado para coincidir com um novo padrãoStartDateTime; no entanto, isto não é necessário. Se dueDateTime não for alterado juntamente com o padrãoStartDateTime no segundo exemplo, os utilizadores continuarão a ver uma data para conclusão de 10 de dezembro para a tarefa atual. Quando estiver concluída, a próxima tarefa da série está agendada para 7 de janeiro. Uma vez que isto pode ser confuso para os utilizadores, recomendamos que atribua o dueDateTime e patternStartDateTime em conjunto.

O terceiro exemplo é semelhante ao primeiro, exceto que não especifica o patternStartDateTime. Não é possível utilizar um patternStartDateTime que esteja há muito tempo, como em agosto. Neste caso, nextOccurrenceDateTime é calculado com base na data para conclusão original de 10 de dezembro, resultando num nextOccurrenceDateTime de 31 de dezembro, semelhante ao primeiro exemplo. Tenha em atenção que a data para conclusão original não está exposta, embora seja utilizada neste cálculo. Isto significa que dueDateTime pode ser alterado para outro valor ou até mesmo alterado para , nullmas o valor dueDateTime é ignorado para este cálculo, utilizando antes a data para conclusão original. Esta é outra razão pela qual recomendamos que altere o dueDateTime e patternStartDateTime em conjunto.

Exemplo 2: a data para conclusão não afeta a ocorrência seguinte

Foi atribuída uma tarefa com periodicidade ativa com as seguintes propriedades:

  • Ocorre semanalmente todas as quartas-feiras: o padrão tem tipo = weekly, intervalo = 1, daysOfWeek = [wednesday], e firstDayOfWeek = sunday.
  • DueDateTime é 2/16.
  • NextOccurrenceDateTime é Wed 2/9.
  • A data para conclusão original é quarta-feira, 2/2. Este valor não é exposto publicamente, embora possa ser inferido a partir de nextOccurrenceDateTime.

Segue-se um exame de três possíveis alterações.

Alteração NextOccurrenceDateTime resultante
Sem alteração Terça-feira, 2/9
padrão alterado para ser semanal todas as quintas-feiras; sem alteração a patternStartDateTime Quinta-feira, 2/10
patternStartDateTime alterado para 2/9; sem alteração ao padrão Quarta-feira, 2/16

Nos três exemplos, dueDateTime não é alterado do valor modificado de quarta-feira 2/16 e a tarefa seguinte na série é criada com um dueDateTime igual ao nextOccurrenceDateTime na tabela anterior.

Observação:

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

Cenários de programador

Criar uma série recorrente

O recurrence.schedule é a única sub-propriedade editável pelo cliente de periodicidade. Ao adicionar um recurrence.schedule (se a periodicidade já está ou não definida), os clientes podem alterar uma tarefa não periódica para uma tarefa com periodicidade ativa.

As outras duas condições mencionadas na definição de periodicidade ativa influenciam a adição de uma periodicidade.schedule :

  • A propriedade percentComplete tem de ser inferior a 100.
  • A propriedade recurrence.nextInSeriesTaskId tem de ser null ou não atribuída.

Outras subpropriedades de periodicidade são só de leitura. Se ainda não estiverem atribuídos, o serviço gera-os automaticamente quando o recurrence.schedule é adicionado.

Periodicidade do acionador

O seguinte mostra duas formas de acionar um mecanismo de periodicidade numa tarefa com periodicidade ativa:

Na definição anterior de um _task com periodicidade ativa, se alguma das três condições não for cumprida, o mecanismo de periodicidade não é acionado (não é criada nenhuma nova tarefa e nextInSeriesTaskId não é atribuído.)

A instanciação da nova tarefa geralmente ocorre 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 está definido como 0. O dueDateTime da nova tarefa é definido de acordo com a agenda de periodicidade. As seguintes subpropriedades da periodicidade são copiadas: seriesId, recurrenceStartDateTime e schedule; schedule.nextOccurrenceDateTime é calculado recentemente para a nova tarefa. As outras propriedades de periodicidade recebem valores adequados para a nova tarefa.

Descobrir a tarefa seguinte numa série

Se a tarefa C tiver a periodicidade definida e um utilizador marcar a tarefa C como concluída (percentagemComplete = 100), a tarefa D é criada para continuar a série de periodicidade. A tarefa C tem a respetiva propriedade recurrence.nextInSeriesTaskId preenchida com o ID da tarefa D.

Por outro lado, se a tarefa C for eliminada e a eliminação acionar periodicidade, um cliente tem de detetar o ID da tarefa D por outros meios. Por exemplo, ao consultar tarefas no mesmo registo ou ao consumir o feed de sincronização delta.

Editar uma série periódica

Uma tarefa com periodicidade ativa pode ter a respetiva agenda de periodicidade editada. Tenha em atenção que recurrence.schedule é a única sub propriedade de periodicidade que pode ser editada.

Por exemplo, uma tarefa com periodicidade ativa e uma agenda semanal todas as quartas-feiras, pode alterar a sua agenda para mensalmente no 15.º dia de cada mês.

Terminar uma série periódica

Para terminar uma série periódica, defina a propriedade recurrence.schedule como null. Só pode fazê-lo quando nextInSeriesTaskId estiver null ou não atribuído.

Reviver periodicidade após a cessação

Depois de remover recurrence.schedule, pode adicionar uma nova periodicidade.schedule à tarefa que revive a série.

Siga os passos anteriores para Criar uma série periódica. Aplicam-se as mesmas restrições. O recurrence.seriesId original e outras subpropriedades de periodicidade são inalterados, reintejando ou continuando a série original.

Identificar a tarefa com periodicidade ativa, numa série de periodicidade

Tendo em conta um recurrence.seriesId, um máximo de uma tarefa com esse seriesId pode ter periodicidade ativa.

As tarefas concluídas estão ocultas da maioria das vistas. É incomum um utilizador ver uma tarefa que foi marcada como concluída. As tarefas eliminadas não podem ser visualizadas. Isto significa que, na maioria dos casos, existe apenas uma tarefa com periodicidade ativa numa série de periodicidade. Se a tarefa com periodicidade ativa tiver sido desativada através da eliminação da agenda, não existem tarefas com periodicidade ativa nessa série.

Cenários excecionais raros

Os cenários seguintes são raros, embora possíveis. Embora possam parecer que um cliente é exceções, na verdade, o serviço mantém sempre a integridade da regra: um máximo de uma tarefa com periodicidade ativa numa determinada série de periodicidade. É dada orientação para a desambiguação.

Causas

O seguinte mostra duas causas possíveis para as informações que parecem estar dessincronizadas:

  • As informações ainda não chegaram ao armazenamento rápido com acesso ao cliente do Planner. A origem de informações autoritativa do Planner tem os dados, mas os dados ainda não foram replicados para o armazenamento otimizado para pedidos que devolve dados aos clientes.

  • O mecanismo de periodicidade encontrou uma falha temporária. Isto significa que a nova tarefa para continuar uma série ainda não foi criada; Normalmente, é criado dentro de alguns segundos ou minutos.

Duas tarefas com periodicidade ativa na mesma série de periodicidade

Se um cliente observar duas tarefas com periodicidade ativa na mesma série de periodicidade, pode presumir-se que a tarefa com o occurrenceId mais pequeno já teve o mecanismo de periodicidade acionado. O armazenamento de back-end do Planner tem o nextInSeriesTaskId definido, mas essas informações ainda não chegaram ao armazenamento rápido com acesso ao cliente. A tarefa com o occurrenceId maior é a tarefa exclusiva com periodicidade ativa.

Uma tarefa com periodicidade ativa tem um occurrenceId menor do que outro na mesma série de periodicidade

Semelhante às "duas tarefas com periodicidade ativa" anteriores, esta segunda situação poderá ser observada se a tarefa com o occurrenceId maior tiver a respetiva periodicidade desativada (recurrence.schedule = null). A existência de uma tarefa com um occurrenceId maior implica que quaisquer tarefas com o occurrenceId mais pequeno nessa série não têm periodicidade ativa, mesmo que a tarefa com o occurrenceId maior também não tenha periodicidade ativa .

Zero tarefas com periodicidade ativa numa série

Esta é uma situação verdadeiramente ambígua, uma vez que qualquer uma das seguintes situações pode ser o seguinte:

  • O mecanismo de periodicidade foi adiado por uma falha transitória; será repetida.
  • O mecanismo de periodicidade foi bem-sucedido, mas a nova tarefa ainda não foi adicionada ao arquivo rápido com acesso ao cliente.
  • A nova tarefa foi criada, mas depois foi eliminada por outro cliente.

Os dois primeiros são estados temporários, que têm a garantia de ser corrigidos pelo serviço, normalmente dentro de alguns segundos ou minutos. O terceiro é geralmente permanente. É provavelmente impreciso descrever este cenário como raro ou excepcional; no entanto, foi descrito anteriormente para chamar a atenção para o facto de existir ambiguidade no estado observado devido à possibilidade dos dois primeiros casos.

Localizar todas as tarefas numa série periódica

Os programadores que trabalham com o Planner estão familiarizados com a API existente para obter todas as tarefas num plano. O Planner ainda não tem uma API para obter todas as tarefas numa série de periodicidade; No entanto, ao obter todas as tarefas num plano, normalmente pode obter todas as tarefas numa série de periodicidade.

A propriedade recurrence.seriesId em cada plannerTask é um identificador que é distinto de uma série periódica específica à qual uma ou mais tarefas pertencem. Quando atribuído, este valor nunca poderá ser alterado. O recurrence.occurrenceId é um valor inteiro que indica a ordenação das tarefas numa série. A primeira tarefa de uma série (a tarefa em que a periodicidade foi adicionada pela primeira vez) recebe um occurrenceId de 1.

Observação:

  • Se algumas tarefas da série tiverem sido eliminadas, os índices poderão conter lacunas.
  • Se os utilizadores tiverem movido a série periódica para um plano diferente, terá de procurar noutros planos para ver outras tarefas na série; No entanto, os utilizadores estão normalmente interessados principalmente nas séries periódicas dentro de um plano. As tarefas não podem ser movidas entre limites de grupo; Se todos os planos num grupo forem consultados, pode encontrar todas as tarefas que poderiam ter sido movidas para fora do plano original.

Exemplos de operação REST

Os seguintes pedidos e respostas representam uma sequência ordenada de operações. Podem ser utilizados como casos de teste para clientes que implementam a periodicidade de tarefas do Planner, substituindo os identificadores adequados (para tarefas, planos, séries de periodicidade, etc.) Muitos casos de erro são intercalados para ilustrar alterações incorretas a estados específicos.

Adicionar uma data para conclusão e periodicidade a um plannerTask existente

O seguinte pedido de exemplo e resposta mostram como periodicidade para uma tarefa. A tarefa com o ID Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV já existe e tem periodicidade = null. Para adicionar periodicidade, tem de atribuir as propriedades necessárias de recurrence.schedule. As propriedades recurrencePattern não utilizadas (mês, dayOfMonth, firstDayOFWeek e índice) 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 seguinte pedido de exemplo e resposta mostram como obter a tarefa com a periodicidade adicionada recentemente.

Solicitação

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

Resposta

Seguem-se notas sobre a resposta:

  • As propriedades recurrencePattern não utilizadas (mês, dayOfMonth, firstDayOFWeek e índice) são atribuídos valores predefinidos pelo serviço.
  • NextOccurrenceDateTime é calculado a partir da agenda. Neste caso, o patternStartDateTime é 13 de novembro e o padrão define todos os dias; isto dá um nextOccurrenceDateTime de dois dias após o padrãoStartDateTime, 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. Uma vez que esta é a primeira tarefa de uma série, obtém um occurrenceId de 1.
  • É atribuído ao recurrenceStartDateTime o mesmo valor que patternStartDateTime. Isto aplica-se à primeira tarefa de uma série (occurrenceId = 1). No entanto, para tarefas futuras na série, o valor de recurrenceStartDateTime não é alterado mesmo que o patternStartDateTime mude; monitoriza o início da periodicidade, em contraste com as alterações de padrões.
  • O previousInSeriesTaskId é sempre null, porque esta é a primeira tarefa da série (occurrenceId = 1).
  • O nextInSeriesTaskId é atribuído se e quando a tarefa seguinte for 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, acionando a periodicidade (1.ª tarefa da série)

O pedido e a resposta de exemplo seguintes mostram como definir percentComplete como 100 (também conhecido como concluir a tarefa ou marcar a tarefa como concluída).

Solicitação

O exemplo seguinte mostra um pedido idêntico para uma tarefa com ou sem periodicidade.

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 o ID da tarefa seguinte (2.ª) na série

O seguinte pedido de exemplo e resposta mostram como obter a tarefa depois de ter 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. Uma vez que nextInSeriesTaskId está atribuído, esta tarefa já não pode ter a periodicidade 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 seguinte pedido de exemplo e resposta mostram como obter a nova tarefa na série, ID para a qual foi detetado a partir de nextInSeriesTaskId na resposta anterior.

Solicitação

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

  • dueDateTime foi atribuído o valor do nextOccurrenceDateTime anterior da tarefa.
  • nextOccurrenceDateTime foi calculado de acordo com a agenda: a ocorrência seguinte após o 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"
}

Editar periodicidade na tarefa para ser um dia por semana e definir a data para conclusão como nula

O seguinte pedido de exemplo e resposta mostram como atribuir um nulldueDateTime e um padrão diferente a uma tarefa com periodicidade 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

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

O seguinte pedido de exemplo e resposta mostram como obter a tarefa após as edições anteriores. Pode esperar ver o recurrence.schedule.pattern especificado anteriormente: semanalmente às terças-feiras, juntamente com dueDateTime = null.

Solicitação

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

Resposta

No exemplo seguinte, uma tarefa pode ter periodicidade ativa juntamente com uma null data para conclusão. NextOccurrenceDateTime é re-calculado e agora é no dia 23 de novembro, uma terça-feira, a partir dos diasOfWeek. Esta ocorrência seguinte é 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 a agenda de periodicidade

O seguinte pedido de exemplo e resposta mostram como atribuir um nullrecurrence.schedule, terminando assim a periodicidade nesta tarefa.

Solicitação

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

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

Resposta

HTTP/1.1 204 NO CONTENT

Obter a tarefa com a agenda de periodicidade eliminada

O seguinte pedido de exemplo e resposta mostram como obter a tarefa após as edições anteriores.

Solicitação

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

Resposta

Segue-se um exemplo da resposta que mantém as informações da série de periodicidade (recurrence.schedule = null). Se for especificada uma nova agenda, esta tarefa ainda pertence à 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 uma nova agenda de periodicidade sem especificar o padrãoStartDateTime

O pedido e a resposta de exemplo seguintes mostram um pedido incorreto, uma tentativa de adicionar uma nova periodicidade.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

Segue-se um exemplo da resposta que mostra um erro que descreve o problema. O objeto de resposta contém um erro porque a mensagem de erro deve mencionar Recurrence.Schedule.PatternStartDateTime em vez de Recurrence.Schedule.Range. Este é atualmente um problema conhecido.

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"
        }
    }
}

Reintegre a periodicidade da tarefa ao adicionar uma nova agenda

O seguinte pedido de exemplo e resposta mostram como atribuir uma nova periodicidade.schedule a uma tarefa que tem atualmente periodicidade.schedule = null.

Nota: 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 a nova agenda de periodicidade

O seguinte pedido de exemplo e resposta mostram como obter a tarefa com a nova agenda de periodicidade. As propriedades de periodicidade (exceto a agenda) permanecem inalteradas e a tarefa tem periodicidade ativa, mesmo que a propriedade dueDateTime permaneça 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 só de leitura

O seguinte pedido de exemplo e resposta mostram um pedido incorreto, uma tentativa de atribuir um valor à propriedade recurrence.seriesId que é só de leitura.

Solicitação

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

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

Resposta

O objeto de resposta seguinte 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, acionando a periodicidade (2.ª tarefa na série, com dueDateTime nulo)

O pedido e a resposta de exemplo seguintes mostram como definir percentComplete como 100 (também conhecido como concluir a tarefa ou marcar a tarefa como concluída).

Solicitação

O pedido seguinte é idêntico para uma tarefa com ou sem periodicidade.

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

{
    "percentComplete": 100
}

Resposta

HTTP/1.1 204 NO CONTENT

Obter a tarefa agora concluída e descobrir o ID da tarefa seguinte (terceira) da série

O seguinte pedido de exemplo e resposta mostram como obter a tarefa depois de ter 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: tente eliminar a agenda de periodicidade quando nextInSeriesTaskId já estiver atribuído

O pedido e a resposta de exemplo seguintes mostram um pedido incorreto, uma tentativa de atribuir um valor à propriedade recurrence.schedule após a propriedade nextInSeriesTaskId ter sido atribuída.

Solicitação

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

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

Resposta

O objeto de resposta seguinte 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 seguinte pedido de exemplo e resposta mostram como obter a nova tarefa na série, ID para o qual detetou a partir de nextInSeriesTaskId na resposta anterior. O dueDateTime foi atribuído ao valor apresentado no nextOccurrenceDateTime anterior da tarefa, apesar de o dueDateTime anterior da tarefa ter sido 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"
}