Compartir a través de

Configuración de la periodicidad de tareas en Planner (versión preliminar)

En este artículo se describe cómo usar la periodicidad con las tareas de Planner para automatizar la creación de tareas repetitivas. La propiedad recurrence de una tarea de Planner permite a los usuarios automatizar la creación de tareas futuras que representan tareas reales que deben completarse de forma repetitiva.

Escenarios de usuario

Se admiten los siguientes escenarios:

  • Agregue el comportamiento de periodicidad a una tarea existente, creando así una serie periódica. Como alternativa, cree una nueva tarea con la periodicidad definida. El resultado final de ambos es el mismo: una tarea periódica, la primera de una serie periódica. Los usuarios especifican la programación de periodicidad.

  • Edite la programación de periodicidad de una serie periódica existente.

  • Continúe con una serie. Marcar una tarea completa da como resultado la generación de una nueva tarea para continuar con la serie, según la programación de periodicidad. Si se elimina la tarea activa de una serie, se debe pedir al usuario que determine si desea continuar o finalizar la serie. Si el cliente no conoce la periodicidad y no ofrece una solicitud, la serie debe continuar. No debe terminarse accidentalmente.

  • Finalice una serie por:

    • Eliminar la tarea activa de la serie (y elegir sí para finalizar la serie).
    • Terminación de la serie sin eliminar la tarea activa.

  • Revivir una serie. Si se ha terminado la periodicidad, debería ser posible restablecer la serie.

Diferencias conceptuales entre reuniones periódicas y tareas periódicas

En esta sección se describe un escenario real para las tareas periódicas, para ilustrar las diferencias interesantes entre reuniones periódicas y tareas periódicas, y para explorar el espacio problemático de los cambios en un patrón de periodicidad.

El ejemplo siguiente implica un informe que debe completarse con regularidad y utiliza una tarea periódica para realizar un seguimiento de la finalización del informe.

El informe y su tarea asociada vencen cada 2 semanas el viernes; la serie comenzó el 14 de mayo de 2021. El primer informe vence en esa fecha, el viernes 14 de mayo. Avance rápido hasta el 7 de enero de 2022, 34 semanas más tarde. La persona que hizo los informes se tomó un tiempo libre en diciembre y nadie completó los informes. La tarea periódica actual (y el informe correspondiente) vence el 10 de diciembre. El informe y su tarea asociada tienen ahora 4 semanas de retraso.

Nota: En este punto, el contraste entre reuniones periódicas y eventos se hace evidente. No es necesario que las reuniones se marquen como completadas para que un sistema automatizado programe la próxima reunión en el calendario. Completar una tarea vencida puede generar otra tarea que vence en el pasado, pero no hay ningún concepto de completar una reunión en el pasado. La siguiente instancia de una reunión es siempre en el futuro, en función de la fecha de hoy. La fecha de hoy no se usa para calcular las fechas de vencimiento de las tareas periódicas, con el fin de evitar perder el seguimiento del trabajo tardío.

Para esta tarea, si no se edita la programación de periodicidad y la tarea del 10 de diciembre se marca como completa, se crea una instancia de la siguiente tarea de la serie con una fecha de vencimiento del 24 de diciembre.

Sin embargo, supongamos que se toma una decisión de que, en el futuro, este informe debe realizarse cada 3 semanas, en lugar de cada 2 semanas. La decisión podría incluso ser que la cadencia de tres semanas debería ser retroactiva para los informes vencidos. Este cambio invita a diferentes opciones posibles para definir la continuación de la serie:

  • ¿Debe cambiarse la fecha de vencimiento del 10 de diciembre?
  • ¿Cuándo debe vence la siguiente tarea?

A continuación se muestra el estado actual de la tarea periódica y la decisión:

  • La tarea actual tiene una fecha de vencimiento del 10 de diciembre de 2021.
  • La tarea completada anterior debía realizarse el 26 de noviembre de 2021.
  • Se toma una decisión para cambiar la cadencia de 2 semanas a 3 semanas; el cambio se aplica con carácter retroactivo para los informes vencidos.

Dado el contexto, dos opciones son posibles y ambas son historias de clientes válidas para saber cómo se puede cambiar la serie para dar cabida a la nueva cadencia de tres semanas.

Opción 1: cambie la tarea del 10 de diciembre para que se deba realizar 3 semanas después de la tarea del 26 de noviembre anterior. La tarea actual ha cambiado su fecha de vencimiento al 17 de diciembre y la siguiente tarea vence el 7 de enero.

Opción 2: mantenga la fecha de vencimiento del 10 de diciembre actual y cambie la cadencia de la siguiente tarea que vence el 31 de diciembre.

Planner admite ambas opciones; la fecha de hoy no tiene en cuenta cómo se tratan estos diferentes casos. Este ejemplo se explora aún más en Ejemplo 1: Cambiar el patrón con y sin cambios en patternStartDateTime.

Definiciones

Los términos siguientes se usan para analizar y describir las tareas de Planner con periodicidad:

Definición de una tarea con periodicidad activa

Si se cumplen las tres condiciones siguientes, plannerTask tiene periodicidad activa:

  • La propiedad percentComplete tiene un valor menor que 100.
  • recurrence.nextInSeriesTaskId es null o no está definido.
  • recurrence.schedule contiene un plannerRecurrenceSchedule válido con un nextOccurrenceDateTime distinto de null.

Una tarea con periodicidad activa (llamada tarea A) puede desencadenar el mecanismo de periodicidad del servicio que crea una nueva tarea (tarea B) para continuar con la serie periódica. Cuando eso sucede, la tarea A tiene su recurrence.nextInSeriesTaskId establecido en el identificador de la tarea B. Dado que la tarea A ya no cumple la condición 2, ya no tiene periodicidad activa. La tarea A nunca puede volver a tener una periodicidad activa , ya que nextInSeriesTaskId es una propiedad de solo lectura y el servicio nunca elimina su valor.

Definición de una serie de periodicidad

Una serie de periodicidad (también conocida como serie periódica) es una serie secuencial de tareas. La serie comienza cuando la periodicidad se define por primera vez en una tarea y la serie continúa a través de la creación automática de nuevas tareas con el mismo recurrence.seriesId.

  • Las tareas que comparten el mismo recurrence.seriesId pertenecen a la misma serie de periodicidad.
  • Cada tarea de la serie tiene un valor de recurrence.occurenceId distinto.
  • La primera tarea de la serie tiene un occurrenceId de 1.
  • Cuando la primera tarea tiene su mecanismo de periodicidad desencadenado (marcado como completo o eliminado, mientras tiene periodicidad activa), la segunda tarea se crea con un occurenceId de 2. Este proceso continúa hasta que finaliza la serie de periodicidad .

Evitar el término ambiguo tarea periódica

En la voz común, el término tarea periódica a veces hace referencia a la tarea única con periodicidad activa dentro de una serie; y a veces hace referencia a la propia serie de periodicidad o a todas las tareas de la serie de periodicidad. Esta ambigüedad es común en inglés hablado: de la misma manera, el informe semanal podría hacer referencia a una instancia del informe o a la responsabilidad periódica de hacer el informe cada semana. Debido a esta ambigüedad, se evita el uso del término tarea periódica ; En su lugar, se prefiere uno de los siguientes términos: tarea con periodicidad activa o serie de periodicidad.

Detalles del tipo de recurso

Trabajar con periodicidad para tareas de Planner implica el uso de muchos tipos de recursos: plannerTaskRecurrence, plannerRecurrenceSchedule y recurrencePattern. En las secciones siguientes se proporcionan más detalles sobre los dos últimos tipos de recursos.

plannerRecurrenceSchedule

PlannerRecurrenceSchedule encapsula una definición de patrón de periodicidad (patrón), una fecha de inicio para ese patrón (patternStartDateTime) y una propiedad generada por el sistema que indica la siguiente fecha de repetición (nextOccurrenceDateTime).

El patrón es recurrencePattern; Para obtener más información, consulte las notas específicas de Planner sobre recurrencePattern.

El patrónStartDateTime indica la fecha y hora de inicio de la serie como DateTimeOffset. Se debe asignar un valor distinto de NULL a patternStartDateTime cada vez que se use la propiedad pattern ; esta es actualmente la única manera de definir la periodicidad. Por lo general, los clientes deben reasignar este valor cuando realizan un cambio en recurrence.schedule.pattern para indicar la fecha de inicio del nuevo patrón; sin embargo, si los clientes no incluyen un valor, el servicio continúa la serie usando un valor predeterminado basado en la programación. Para obtener más información, consulte las siguientes notas y aclaraciones.

NextOccurrenceDateTime es un campo generado por el sistema de solo lectura. Proporciona la fecha calculada por el servicio que se usa como dueDateTime para el siguiente plannerTask de la serie. NextOccurrenceDateTime se calcula a partir del patrón junto con el patrónStartDateTime o un valor delimitador que realiza un seguimiento de la fecha programada originalmente de la tarea especificada.

Nota: Planner no usa actualmente el tipo de recurso recurrenceRange .

Notas específicas de Planner sobre recurrencePattern

Las siguientes son restricciones específicas de Planner para recurrencePattern:

  • relativeMonthly es posible que los patrones y relativeYearly no especifiquen más de un día para daysOfWeek.
  • Para weekly los patrones, si daysOfWeek contiene más de un día, el intervalo debe ser 1.

Aclaraciones sobre recurrencePattern:

  • Cada vez que se cambia cualquier propiedad dentro de un recurrencePattern , se deben especificar todas las propiedades de patrón pertinentes. Por ejemplo, un patrón con tipo = daily e intervalo = 1 no se puede aplicar una revisión con solo intervalo = 2; de lo contrario, el servicio devuelve un 400 Bad Request código de respuesta. También se debe especificar la propiedad type = daily , aunque el tipo no cambie. Este es un comportamiento normal para el tipo de recurso recurrencePattern , aunque algunas otras propiedades de Planner funcionan de forma diferente.

  • A las propiedades sin usar se les asigna automáticamente un valor predeterminado.

    • Por ejemplo, la propiedad month solo se usa para patrones anuales, con valores válidos de 1 a 12. Sin embargo, dailylos patrones , weeklyy monthly se han 0 asignado a la propiedad month , porque 0 es el valor predeterminado de un valor entero.
    • Las propiedades de enumeración, incluidos firstDayOfWeek y index, obtienen valores predeterminados que corresponden al primer valor de enumeración: sunday y first, respectivamente.

  • En absoluteMonthly el caso de los patrones, si el dayOfMonth seleccionado no existe en un mes determinado, se sustituye el último día del mes.

    • Ejemplo: si dayOfMonth es 31 y se repite para abril, la fecha seleccionada es el 30 de abril.
    • Ejemplo: si dayOfMonth es 29, 30o 31 y se repite en febrero, la fecha seleccionada es el último día de febrero.

  • Del mismo modo, para absoluteYearly los patrones con month = 2 y dayOfMonth = 29, la fecha seleccionada en años no bisiestos es el 28 de febrero.

  • En weekly el caso de los patrones, la propiedad firstDayOfWeek se usa para distinguir entre lo que se considera esta semana y lo que se considera la semana siguiente. Esto es relevante cuando se cambia un weekly patrón. La siguiente tarea está programada para la próxima semana y firstDayOfWeek determina cuándo comienza la semana siguiente .

Ejemplos de cómo afecta firstDayOfWeek a los cambios en un patrón semanal

Dada una tarea con periodicidad activa con las siguientes propiedades:

  • Se produce semanalmente todos los miércoles: el patrón tiene tipo = weekly, intervalo = 1, daysOfWeek = [wednesday], y firstDayOfWeek = sunday
  • DueDateTime es el miércoles 2/2
  • NextOccurrenceDateTime es el miércoles 2/9

En la tabla siguiente se pueden realizar tres cambios en el patrón y el nextOccurrenceDateTime resultante.

Cambio de patrón NextOccurrenceDateTime resultante
Semanalmente todos los martes Martes 2/8
Semanalmente todos los jueves Jueves 2/10
Semanalmente todos los jueves y firstDayOfWeek cambian a Jueves Jueves 2/3

Tenga en cuenta la diferencia del jueves 2/10 frente al jueves 2/3. Cuando firstDayOfWeek = Thursday, el jueves 2/3 no está en la misma semana que el miércoles 2/2 porque una nueva semana comienza el jueves; mientras que si el primerDayOfWeek no Thursdayes , el jueves 2/3 está en la misma semana que el miércoles 2/2, y el jueves 2/10 es en la semana siguiente.

Notas sobre la programación y la fecha de vencimiento

Los clientes pueden editar dueDateTime para que tengan un valor diferente (incluido null), sin que ello afecte a la programación ni a nextOccurrenceDateTime. Por ejemplo, si una tarea se retrasa y se cambia la fecha de vencimiento para dar cabida a esa latencia, la siguiente tarea de la serie aparece como programada originalmente, a menos que el patrón o el patrónStartDateTime se actualicen explícitamente. Por lo tanto, posponer la fecha de vencimiento no da lugar a omitir las fechas según la programación definida. Esto difiere de un modelo de reunión , donde la fecha de hoy desempeña un papel en la determinación de cuándo se produce la próxima reunión. Conocer la fecha de hoy es relevante para calcular la siguiente fecha de reunión o evento, pero no es relevante para calcular la siguiente fecha de vencimiento de la tarea.

Ejemplo 1: Cambio del patrón con y sin cambios en patternStartDateTime

Dada una tarea con periodicidad activa con las siguientes propiedades:

  • El patrón de periodicidad especifica cada 2 semanas el viernes, por ejemplo, tipo = weekly, intervalo = 2, daysOfWeek = [friday], y firstDayOfWeek = sunday.
  • La tarea completada anterior debía realizarse el 26 de noviembre de 2021.
  • La tarea actual vence el 10 de diciembre de 2021.
  • NextOccurrenceDateTime es el 24 de diciembre de 2021 (dos semanas después de la fecha de vencimiento actual).

Se toma la decisión de cambiar la cadencia de 2 semanas a 3 semanas. Por lo tanto, el patrón se modifica para que tenga intervalo = 3 junto con los mismos valores para semanalmente los viernes.

Se examinan tres posibilidades distintas, cada una con fechas de vencimiento diferentes para la siguiente tarea de la serie:

Descripción del cambio NextOccurrenceDateTime resultante
Cambie el patrónStartDateTime al 10 de diciembre de 2021 viernes, 31 de diciembre de 2021
Cambie el patrónStartDateTime al 17 de diciembre de 2021 7 de enero de 2022
No cambie el patrónStartDateTime viernes, 31 de diciembre de 2021

En el primer ejemplo, el patternStartDateTime se establece en el mismo valor que dueDateTime, por ejemplo, el 10 de diciembre. NextOccurrenceDateTime se establece en 3 semanas después del patrónStartDateTime, siendo el 31 de diciembre. Conceptualmente, esto representa el cambio de cadencia que surte efecto solo para la siguiente tarea en lugar de para esta tarea.

En el segundo ejemplo, el patrónStartDateTime se establece en 3 semanas después del 26 de noviembre, siendo el 17 de diciembre. De nuevo, nextOccurrenceDateTime se establece en 3 semanas después del patrónStartDateTime, esta vez el 7 de enero. Conceptualmente, esto representa el cambio de cadencia que surte efecto a partir del 26 de noviembre (la tarea anterior) en lugar de a partir del 10 de diciembre (fecha de vencimiento original de la tarea actual).

Por lo general, se recomienda cambiar dueDateTime de una tarea para que coincida con un nuevo patrónStartDateTime; sin embargo, esto no es necesario. Si el dueDateTime no cambia junto con el patrónStartDateTime en el segundo ejemplo, los usuarios seguirán viendo una fecha de vencimiento del 10 de diciembre para la tarea actual. Una vez completada, la siguiente tarea de la serie está programada para el 7 de enero. Dado que esto puede resultar confuso para los usuarios, se recomienda asignar los valores dueDateTime y patternStartDateTime juntos.

El tercer ejemplo es similar al primero, salvo que no especifica el patrónStartDateTime. No se puede usar un patternStartDateTime que esté largo atrás, como en agosto. En este caso, nextOccurrenceDateTime se calcula en función de la fecha de vencimiento original del 10 de diciembre, lo que da como resultado un nextOccurrenceDateTime del 31 de diciembre, similar al primer ejemplo. Tenga en cuenta que la fecha de vencimiento original no se expone, aunque se usa en este cálculo. Esto significa que el dueDateTime se puede cambiar a otro valor, o incluso cambiarse para que sea null, pero el valor dueDateTime se omite para este cálculo, usando en su lugar la fecha de vencimiento original. Esta es otra razón por la que se recomienda cambiar los valores dueDateTime y patternStartDateTime juntos.

Ejemplo 2: La fecha de vencimiento no afecta a la siguiente aparición

Dada una tarea con periodicidad activa con las siguientes propiedades:

  • Se produce semanalmente todos los miércoles: el patrón tiene tipo = weekly, intervalo = 1, daysOfWeek = [wednesday], y firstDayOfWeek = sunday.
  • DueDateTime es Wed 2/16.
  • NextOccurrenceDateTime es Wed 2/9.
  • La fecha de vencimiento original es el miércoles 2/2. Este valor no se expone públicamente, aunque se puede deducir de nextOccurrenceDateTime.

A continuación se muestra un examen de tres posibles cambios.

Cambiar NextOccurrenceDateTime resultante
Sin cambios Martes 2/9
patrón cambiado para ser semanal cada jueves; no hay ningún cambio en patternStartDateTime Jueves 2/10
patternStartDateTime ha cambiado a 2/9; no hay ningún cambio en el patrón Miércoles 2/16

En los tres ejemplos, dueDateTime no cambia de su valor modificado del miércoles 2/16 y la siguiente tarea de la serie se crea con un dueDateTime igual a nextOccurrenceDateTime en la tabla anterior.

Nota:

  • El comportamiento predeterminado, cuando patternStartDateTime no se reasigna explícitamente, es que la programación continúa en función de la fecha de vencimiento original. En este caso, la fecha de vencimiento original es 2/2, mientras que la fecha de vencimiento actual es 2/16.
  • Si se cambia el patrónStartDateTime , nextOccurrenceDateTime se vuelve a calcular con esa nueva fecha de inicio.
  • Si la fecha de vencimiento se cambia a null en lugar del 16/2 o a cualquier otra fecha en el futuro o pasado, los ejemplos anteriores no se verían afectados.

Escenarios para desarrolladores

Crear una serie periódica

Recurrence.schedule es la única subpropiedad editable por el cliente de periodicidad. Al agregar un recurrence.schedule (independientemente de si la periodicidad ya está definida), los clientes pueden cambiar una tarea no periódica a una tarea con periodicidad activa.

Las otras dos condiciones mencionadas en la definición de periodicidad activa influyen en si se puede agregar una recurrence.schedule :

  • La propiedad percentComplete debe ser menor que 100.
  • La propiedad recurrence.nextInSeriesTaskId debe estar null o sin asignar.

Otras subpropiedades de periodicidad son de solo lectura. Si aún no están asignados, el servicio los genera automáticamente cuando se agrega recurrence.schedule .

Periodicidad del desencadenador

A continuación se muestran dos maneras de desencadenar un mecanismo de periodicidad en una tarea con periodicidad activa:

En la definición anterior de un _task con periodicidad activa, si no se cumple alguna de las tres condiciones, no se desencadena el mecanismo de periodicidad (no se crea ninguna tarea nueva y no se asigna nextInSeriesTaskId ).

La creación de instancias de la nueva tarea suele producirse inmediatamente, lo que en ocasiones provoca un retraso en la creación de la nueva tarea.

La nueva tarea tiene las siguientes propiedades copiadas de la tarea ahora completa: título, descripción, elementos de lista de comprobación ( establecidos en incompletos), asignaciones, prioridad y categorías. PercentComplete de la nueva tarea se establece en .0 El dueDateTime de la nueva tarea se establece según la programación de periodicidad. Se copian las siguientes subpropiedades de periodicidad: seriesId, recurrenceStartDateTime y schedule; schedule.nextOccurrenceDateTime se acaba de calcular para la nueva tarea. A las otras propiedades de periodicidad se les proporcionan los valores adecuados para la nueva tarea.

Detección de la siguiente tarea de una serie

Si la tarea C tiene definida la periodicidad y un usuario marca la tarea C complete (percentComplete = 100), se crea la tarea D para continuar con la serie de periodicidad. La tarea C tiene su propiedad recurrence.nextInSeriesTaskId rellenada con el identificador de la tarea D.

Por otro lado, si se elimina la tarea C y la eliminación desencadena la periodicidad, un cliente debe detectar el identificador de la tarea D por algún otro medio. Por ejemplo, consultando tareas en el mismo cubo o consumiendo la fuente de sincronización delta.

Edición de una serie periódica

Una tarea con periodicidad activa puede tener su programación de periodicidad editada. Tenga en cuenta que recurrence.schedule es la única subpropiedad de periodicidad que se puede editar.

Por ejemplo, una tarea con periodicidad activa y una programación semanal cada miércoles, puede cambiar su programación a mensual el día 15 de cada mes.

Finalización de una serie periódica

Para finalizar una serie periódica, establezca la propiedad recurrence.schedule en null. Solo puede hacerlo cuando nextInSeriesTaskId está null o no asignado.

Reactivación de la periodicidad después de la finalización

Después de quitar recurrence.schedule, puede agregar una nueva recurrence.schedule a la tarea que reviva la serie.

Siga los pasos anteriores para Crear una serie periódica. Se aplican las mismas restricciones. El valor de recurrence.seriesId original y otras subpropiedades de periodicidad no se modifican, reinsertando o continuando de forma eficaz la serie original.

Identificar la tarea con periodicidad activa, dentro de una serie de periodicidad

Dado un recurrence.seriesId, un máximo de una tarea con ese valor de seriesId puede tener periodicidad activa.

Las tareas completadas están ocultas en la mayoría de las vistas. No es habitual que un usuario vea una tarea marcada como completa. Las tareas eliminadas no se pueden ver. Esto significa que, en la mayoría de los casos, solo existe una tarea con periodicidad activa en una serie de periodicidad. Si la tarea con periodicidad activa ha tenido su periodicidad desactivada a través de la programación que se está eliminando, no existe ninguna tarea con periodicidad activa en esa serie.

Escenarios excepcionales poco frecuentes

Los siguientes escenarios son poco frecuentes, aunque es posible. Aunque pueden parecer excepciones a un cliente, de hecho, el servicio siempre mantiene la integridad de la regla: un máximo de una tarea con periodicidad activa en una serie de periodicidad determinada. Se proporcionan instrucciones para la desambiguación.

Causas

A continuación se muestran dos posibles causas de que la información parezca no estar sincronizada:

  • La información aún no ha alcanzado el almacenamiento rápido orientado al cliente de Planner. El origen de información autoritativo de Planner tiene los datos, pero los datos aún no se han replicado en el almacenamiento optimizado para solicitudes que devuelve datos a los clientes.

  • El mecanismo de periodicidad encontró un error temporal. Esto significa que la nueva tarea para continuar una serie aún no se ha creado; normalmente se crea en unos segundos o minutos.

Dos tareas con periodicidad activa en la misma serie de periodicidad

Si un cliente observa dos tareas con periodicidad activa en la misma serie de periodicidad, se puede suponer que la tarea con el valor occurrenceId más pequeño ya ha desencadenado su mecanismo de periodicidad. El almacenamiento back-end de Planner tiene el nextInSeriesTaskId establecido, pero esa información aún no ha alcanzado el almacenamiento rápido orientado al cliente. La tarea con el valor occurrenceId más grande es la tarea única con periodicidad activa.

Una tarea con periodicidad activa tiene un valor occurrenceId más pequeño que otro en la misma serie de periodicidad.

De forma similar a las "dos tareas anteriores con periodicidad activa", esta segunda situación podría observarse si la tarea con el valor occurrenceId más grande tiene su periodicidad desactivada (recurrence.schedule = null). La existencia de una tarea con un valor de occurrenceId mayor implica que las tareas con occurrenceId más pequeño en esa serie no tienen periodicidad activa, incluso si la tarea con el valor occurrenceId más grande tampoco tiene periodicidad activa .

Cero tareas con periodicidad activa en una serie

Se trata de una situación realmente ambigua, ya que cualquiera de las siguientes puede ser el caso:

  • El mecanismo de periodicidad se retrasó por un error transitorio; será reintentado.
  • El mecanismo de periodicidad se realizó correctamente, pero la nueva tarea aún no se ha agregado al almacén rápido orientado al cliente.
  • Se creó la nueva tarea, pero otro cliente la eliminó.

Los dos primeros son estados temporales, que el servicio garantiza que se corregirán, normalmente en unos segundos o minutos. El tercero suele ser permanente. Probablemente sea inexacto describir este escenario como poco frecuente o excepcional; sin embargo, se describió anteriormente para llamar la atención sobre el hecho de que existe ambigüedad en el estado observado debido a la posibilidad de los dos primeros casos.

Búsqueda de todas las tareas de una serie periódica

Los desarrolladores que trabajan con Planner están familiarizados con la API existente para obtener todas las tareas de un plan. Planner aún no tiene una API para obtener todas las tareas de una serie de periodicidad; sin embargo, al obtener todas las tareas de un plan, normalmente puede obtener todas las tareas de una serie de periodicidad.

La propiedad recurrence.seriesId de cada plannerTask es un identificador distinto a una serie periódica determinada a la que pertenecen una o varias tareas. Cuando se asigna, este valor nunca puede cambiar. Recurrence.occurrenceId es un valor entero que indica el orden de las tareas dentro de una serie. A la primera tarea de una serie (la tarea en la que se agregó la periodicidad por primera vez) se le asigna un occurrenceId de 1.

Nota:

  • Si se han eliminado algunas tareas de la serie, los índices podrían contener brechas.
  • Si los usuarios han movido la serie periódica a otro plan, tendrá que buscar en otros planes para ver otras tareas de la serie; sin embargo, los usuarios suelen estar interesados principalmente en la serie periódica dentro de un plan. Es posible que las tareas no se muevan a través de los límites del grupo; Si se consultan todos los planes de un grupo, puede encontrar todas las tareas que se podrían haber movido fuera del plan original.

Ejemplos de operaciones REST

Las siguientes solicitudes y respuestas representan una secuencia ordenada de operaciones. Se pueden usar como casos de prueba para los clientes que implementan la periodicidad de tareas de Planner, sustituyendo los identificadores adecuados (para tareas, planes, series de periodicidad, etc.). Muchos casos de error se intercalan para ilustrar cambios incorrectos en estados concretos.

Agregar una fecha de vencimiento y una periodicidad a un plannerTask existente

En la siguiente solicitud y respuesta de ejemplo se muestra cómo periodicidad en una tarea. La tarea con identificador Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV ya existe y tiene periodicidad = null. Para agregar periodicidad, debe asignar las propiedades necesarias de recurrence.schedule. No se deben incluir las propiedades recurrencePattern sin usar (month, dayOfMonth, firstDayOFWeek e index).

Solicitud

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

Respuesta

HTTP/1.1 204 NO CONTENT

Obtener la tarea anterior

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la tarea con la periodicidad recién agregada.

Solicitud

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

Respuesta

A continuación se muestran notas sobre la respuesta:

  • El servicio asigna valores predeterminados a las propiedades recurrencePattern sin usar (month, dayOfMonth, firstDayOFWeek e index).
  • NextOccurrenceDateTime se calcula a partir de la programación. En este caso, el patrónStartDateTime es el 13 de noviembre y el patrón define cada dos días; esto proporciona un nextOccurrenceDateTime de dos días después del patrónStartDateTime, siendo el 15 de noviembre.
  • Los valores seriesId y occurrenceId se generan automáticamente. El valor de seriesId es un nuevo GUID, codificado en el formato de identificador de Planner. Dado que esta es la primera tarea de una serie, obtiene un occurrenceId de 1.
  • A recurrenceStartDateTime se le asigna el mismo valor que patternStartDateTime. Esto es así para la primera tarea de una serie (occurrenceId = 1). Sin embargo, para las tareas futuras de la serie, el valor de recurrenceStartDateTime no cambia incluso si cambia el patrónStartDateTime ; realiza un seguimiento del comienzo de la periodicidad, en contraste con los cambios de patrón.
  • PreviousInSeriesTaskId siempre nulles , porque es la primera tarea de la serie (occurrenceId = 1).
  • NextInSeriesTaskId se asigna si y cuando se crea la siguiente tarea para continuar con la serie.
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 la tarea completa, desencadenando la periodicidad (primera tarea de la serie)

En la siguiente solicitud y respuesta de ejemplo se muestra cómo establecer percentComplete100 en (también conocido como completar la tarea o marcar la tarea completada).

Solicitud

En el ejemplo siguiente se muestra una solicitud idéntica para una tarea con o sin periodicidad.

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

{
    "percentComplete": 100
}

Respuesta

HTTP/1.1 204 NO CONTENT

Obtener la tarea ahora completa y detectar el identificador de la siguiente tarea (2ª) de la serie

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la tarea después de que se haya marcado como completada.

Solicitud

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

Respuesta

En el ejemplo siguiente se muestra la solicitud. Dado que se asigna nextInSeriesTaskId , esta tarea ya no puede tener configurada la periodicidad activa .

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

Obtener la nueva tarea de la serie (segunda aparición)

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la nueva tarea de la serie, identificador para el que se detectó desde nextInSeriesTaskId en la respuesta anterior.

Solicitud

La solicitud de ejemplo (GxOo0ms1iEu3eBI1-6lk85UAI5FI) contiene las siguientes diferencias en comparación con el ejemplo anterior (Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV):

  • dueDateTime tiene asignado el valor del nextOccurrenceDateTime anterior de la tarea.
  • nextOccurrenceDateTime se ha calculado según la programación: la siguiente aparición después del dueDateTime anterior.
  • occurrenceId es 2 en lugar de 1
  • percentComplete es 0.
GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Respuesta

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 la periodicidad de la tarea para que sea de un día a la semana y establezca la fecha de vencimiento en null.

En la siguiente solicitud y respuesta de ejemplo se muestra cómo asignar un nulldueDateTime y un patrón diferente a una tarea con periodicidad activa.

Solicitud

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

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

Respuesta

HTTP/1.1 204 NO CONTENT

Vuelva a obtener la tarea para ver el resultado de la edición.

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la tarea después de las ediciones anteriores. Puede esperar ver el elemento recurrence.schedule.pattern especificado anteriormente: semanalmente los martes, junto con dueDateTime = null.

Solicitud

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

Respuesta

En el ejemplo siguiente, una tarea puede tener periodicidad activa junto con una null fecha de vencimiento. NextOccurrenceDateTime se vuelve a calcular y ahora es el 23 de noviembre, un martes, a partir de daysOfWeek. Esta siguiente repetición se calcula en función del dueDateTime original de la tarea del 15 de noviembre, un lunes.

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
}

Eliminación de la programación de periodicidad

En la siguiente solicitud y respuesta de ejemplo se muestra cómo asignar una nullrecurrence.schedule, terminando así la periodicidad en esta tarea.

Solicitud

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

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

Respuesta

HTTP/1.1 204 NO CONTENT

Eliminación de la tarea con la programación de periodicidad

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la tarea después de las ediciones anteriores.

Solicitud

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

Respuesta

A continuación se muestra un ejemplo de la respuesta que conserva la información de la serie de periodicidad (recurrence.schedule = null). Si se especifica una nueva programación, esta tarea sigue pertenecendo a la misma serie.

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 error: intente agregar una nueva programación de periodicidad sin especificar el patrónStartDateTime

En la siguiente solicitud y respuesta de ejemplo se muestra una solicitud incorrecta, un intento de agregar una nueva recurrence.schedule sin especificar el patrónStartDateTime.

Solicitud

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

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

Respuesta

A continuación se muestra un ejemplo de la respuesta que muestra un error que describe el problema. El objeto de respuesta contiene un error porque el mensaje de error debe mencionarse Recurrence.Schedule.PatternStartDateTime en lugar de Recurrence.Schedule.Range. Actualmente se trata de un problema conocido.

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

Reinstalar la periodicidad en la tarea agregando una nueva programación

En la siguiente solicitud y respuesta de ejemplo se muestra cómo asignar una nueva recurrence.schedule a una tarea que actualmente tiene recurrence.schedule = null.

Nota: No se asigna dueDateTime .

Solicitud

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

Respuesta

HTTP/1.1 204 NO CONTENT

Obtención de la tarea con la nueva programación de periodicidad

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la tarea con la nueva programación de periodicidad. Las propiedades de periodicidad (excepto programación) permanecen sin cambios y la tarea tiene periodicidad activa, incluso mientras la propiedad dueDateTime sigue siendo null.

Solicitud

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

Respuesta

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 error: intento de editar una propiedad de solo lectura

En la siguiente solicitud y respuesta de ejemplo se muestra una solicitud incorrecta, un intento de asignar un valor a la propiedad recurrence.seriesId que es de solo lectura.

Solicitud

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

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

Respuesta

El siguiente objeto de respuesta muestra un error que describe el 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"
        }
    }
}

Marque la tarea completa, desencadenando la periodicidad (segunda tarea de la serie, con null dueDateTime)

En la siguiente solicitud y respuesta de ejemplo se muestra cómo establecer percentComplete100 en (también conocido como completar la tarea o marcar la tarea completada).

Solicitud

La siguiente solicitud es idéntica para una tarea con o sin periodicidad.

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

{
    "percentComplete": 100
}

Respuesta

HTTP/1.1 204 NO CONTENT

Obtener la tarea ahora completa y detectar el identificador de la siguiente (tercera) tarea de la serie

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la tarea después de que se haya marcado como completada.

Solicitud

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

Respuesta

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 error: intente eliminar la programación de periodicidad cuando nextInSeriesTaskId ya esté asignado.

En la siguiente solicitud y respuesta de ejemplo se muestra una solicitud incorrecta, un intento de asignar un valor a la propiedad recurrence.schedule después de que se haya asignado la propiedad nextInSeriesTaskId .

Solicitud

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

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

Respuesta

El siguiente objeto de respuesta muestra un error que describe el 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"
        }
    }
}

Obtener la nueva tarea de la serie (3ª repetición)

En la siguiente solicitud y respuesta de ejemplo se muestra cómo recuperar la nueva tarea de la serie, identificador para el que ha detectado desde nextInSeriesTaskId en la respuesta anterior. El dueDateTime se ha asignado al valor presentado en el nextOccurrenceDateTime anterior de la tarea, aunque el dueDateTime anterior de la tarea era null.

Solicitud

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

Respuesta

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