Obtener y establecer la periodicidad de las citas

A veces, es necesario crear y actualizar una cita periódica, como, por ejemplo, una reunión semanal de estado para un proyecto de equipo o un recordatorio anual de cumpleaños. Use la API de JavaScript de Office para administrar los patrones de periodicidad de una serie de citas en el complemento.

Nota:

La compatibilidad con esta característica se introdujo en el conjunto de requisitos 1.7. Vea clientes y plataformas compatibles con este conjunto de requisitos.

Patrones de periodicidad

El patrón de periodicidad de una cita se compone de un tipo de periodicidad (por ejemplo, periodicidad diaria o semanal) y sus propiedades de periodicidad aplicables (por ejemplo, el día del mes en que se produce la cita).

En la tabla siguiente se enumeran los tipos de periodicidad disponibles, sus propiedades configurables y las descripciones de su uso.

Tipo de periodicidad	Propiedades de periodicidad válidas	Uso
daily	interval	Una cita tiene lugar cada interval días. Por ejemplo, una cita se produce cada dos días.
weekday	Ninguno	Una cita tiene lugar todos los días laborables.
monthly	interval dayOfMonth dayOfWeek weekNumber	Una cita tiene lugar el día del díaOfMonth cada intervalo de meses. Por ejemplo, una cita se produce el quinto día cada cuatro meses. Una cita se produce en el weekNumberdayOfWeek cada intervalo de meses. Por ejemplo, una cita tiene lugar el tercer jueves cada dos meses.
weekly	interval days	Una cita tiene lugar los days cada interval semanas. Por ejemplo, una cita tiene lugar los martes y jueves cada dos semanas.
yearly	interval dayOfMonth dayOfWeek weekNumber month	Una cita tiene lugar el día del díaOfMonth del mes cada intervalo de años. Por ejemplo, una cita tiene lugar el séptimo día de septiembre cada cuatro años. Una cita tiene lugar en el weekNumberdayOfWeek del mes cada intervalo de años. Por ejemplo, una cita tiene lugar el primerjueves de septiembre cada dos años.

Sugerencia

También puede usar la propiedad firstDayOfWeek con el tipo de periodicidad weekly. El día especificado iniciará la lista de los días mostrados en el cuadro de diálogo de periodicidad.

Acceso al patrón de periodicidad

Como se muestra en la tabla siguiente, la forma de acceder al patrón de periodicidad y lo que puede hacer con él depende de:

• Ya sea el organizador de la cita o un asistente.
• Tanto si usa el complemento en modo de redacción como de lectura.
• Si la cita actual es una sola repetición o una serie.

Estado de cita	¿Puede editarse la periodicidad?	¿Puede verse la periodicidad?
Organizador de la cita: redacción de serie	Sí (setAsync)	Sí (getAsync)
Organizador de la cita: redacción de instancia	No (setAsync devuelve un error)	Sí (getAsync)
Asistente de la cita: lectura de serie	No (setAsync no disponible)	Sí (item.recurrence)
Asistente de la cita: lectura de instancia	No (setAsync no disponible)	Sí (item.recurrence)
Convocatoria de reunión: lectura de serie	No (setAsync no disponible)	Sí (item.recurrence)
Convocatoria de reunión: lectura de instancia	No (setAsync no disponible)	Sí (item.recurrence)

Establecer la periodicidad como organizador

Con el patrón de periodicidad, también necesita determinar las fechas de inicio y finalización y las horas de la serie de citas. El objeto SeriesTime se usa para administrar esa información.

El organizador de la cita puede especificar el patrón de periodicidad de una serie de citas solamente en el modo Redacción. En el ejemplo siguiente, se establece que la serie de citas tenga lugar de 10:30 a 11:00 (zona horaria PST) todos los martes y jueves durante el período que va del 2 de noviembre de 2019 al 2 de diciembre de 2019.

const seriesTimeObject = new Office.SeriesTime();
seriesTimeObject.setStartDate(2019,10,2);
seriesTimeObject.setEndDate(2019,11,2);
seriesTimeObject.setStartTime(10,30);
seriesTimeObject.setDuration(30);

const pattern = {
    seriesTime: seriesTimeObject,
    recurrenceType: Office.MailboxEnums.RecurrenceType.Weekly,
    recurrenceProperties:
    {
        interval: 1,
        days: [Office.MailboxEnums.Days.Tue, Office.MailboxEnums.Days.Thu]
    },
    recurrenceTimeZone: { name: Office.MailboxEnums.RecurrenceTimeZone.PacificStandardTime }
};

Office.context.mailbox.item.recurrence.setAsync(pattern, (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
});

Cambiar la periodicidad como organizador

En el ejemplo siguiente, el organizador de citas obtiene el objeto Recurrence de una serie de citas y, a continuación, establece una nueva duración de periodicidad. Esto se hace en modo de redacción.

Office.context.mailbox.item.recurrence.getAsync((asyncResult) => {
  const recurrencePattern = asyncResult.value;
  recurrencePattern.seriesTime.setDuration(60);
  Office.context.mailbox.item.recurrence.setAsync(recurrencePattern, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log("Failed to set recurrence.");
      return;
    }

    console.log("Successfully set recurrence.");
  });
});

Obtener la periodicidad como organizador

En el ejemplo siguiente, el organizador de citas obtiene el Recurrence objeto de una cita para determinar si es una serie periódica. Esto se hace en modo de redacción.

Office.context.mailbox.item.recurrence.getAsync((asyncResult) => {
    const recurrence = asyncResult.value;

    if (recurrence == null) {
        console.log("Non-recurring meeting.");
    } else {
        console.log(JSON.stringify(recurrence));
    }
});

En el ejemplo siguiente se muestran los resultados de la getAsync llamada que recupera la periodicidad de una serie.

Nota:

En este ejemplo, seriesTimeObject es un marcador de posición del JSON que representa la propiedad recurrence.seriesTime. Debe usar los métodos SeriesTime para obtener las propiedades de fecha y hora de periodicidad.

{
    "recurrenceType": "weekly",
    "recurrenceProperties": {
        "interval": 1,
        "days": ["tue","thu"],
        "firstDayOfWeek": "sun"},
    "seriesTime": {seriesTimeObject},
    "recurrenceTimeZone": {
        "name": "Pacific Standard Time",
        "offset": -480}}

Obtener periodicidad como un asistente

En el ejemplo siguiente, un asistente de cita obtiene el Recurrence objeto de una cita o una convocatoria de reunión.

outputRecurrence(Office.context.mailbox.item);

function outputRecurrence(item) {
    const recurrence = item.recurrence;

    if (recurrence == null) {
        console.log("Non-recurring meeting.");
    } else {
        console.log(JSON.stringify(recurrence));
    }
}

En el ejemplo siguiente se muestra el valor de la item.recurrence propiedad de una serie de citas.

Nota:

En este ejemplo, seriesTimeObject es un marcador de posición del JSON que representa la propiedad recurrence.seriesTime. Debe usar los métodos SeriesTime para obtener las propiedades de fecha y hora de periodicidad.

{
    "recurrenceType": "weekly",
    "recurrenceProperties": {
        "interval": 1,
        "days": ["tue","thu"],
        "firstDayOfWeek": "sun"},
    "seriesTime": {seriesTimeObject},
    "recurrenceTimeZone": {
        "name": "Pacific Standard Time",
        "offset": -480}}

Obtener los detalles de la periodicidad

Después de que haya recuperado el objeto de periodicidad (de la devolución de llamada getAsync o de item.recurrence), podrá ver las propiedades específicas de la periodicidad. Por ejemplo, obtenga las fechas y horas de inicio y finalización de la serie mediante los métodos SeriesTime de la recurrence.seriesTime propiedad .

// Get the date and time information of the series.
const seriesTime = recurrence.seriesTime;
const startTime = recurrence.seriesTime.getStartTime();
const endTime = recurrence.seriesTime.getEndTime();
const startDate = recurrence.seriesTime.getStartDate();
const endDate = recurrence.seriesTime.getEndDate();
const duration = recurrence.seriesTime.getDuration();

// Get the series time zone.
const timeZone = recurrence.recurrenceTimeZone;

// Get the recurrence properties.
const recurrenceProperties = recurrence.recurrenceProperties;

// Get the recurrence type.
const recurrenceType = recurrence.recurrenceType;

Identificar cuándo cambia el patrón de periodicidad

Puede haber escenarios en los que quiera que el complemento detecte y controle los cambios en el patrón de periodicidad de una serie. Por ejemplo, le gustaría actualizar la ubicación de la cita si la serie se extiende. Para implementar esto, debe crear un controlador para el evento RecurrenceChanged . Para agregar un controlador de eventos para el RecurrenceChanged evento, llame a Office.context.mailbox.item.addHandlerAsync. Cuando se detecta un cambio, el controlador de eventos recibe un argumento de tipo Office.RecurrenceChangedEventArgs, que proporciona el objeto periodicidad actualizado.

En el ejemplo siguiente se muestra cómo registrar un controlador de eventos para el RecurrenceChanged evento.

// This sample shows how to register an event handler in Outlook.
Office.onReady(() => {
    // Register an event handler to identify when the recurrence pattern of a series is updated.
    Office.context.mailbox.item.addHandlerAsync(Office.EventType.RecurrenceChanged, handleEvent, (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            return;
        }

        console.log("Event handler added for the RecurrenceChanged event.");
    });
});

function handleEvent(event) {
    // Get the updated recurrence object.
    const updatedRecurrence = event.recurrence;

    // Perform operations in response to the updated recurrence pattern.
}

Ejecución de fragmentos de código de ejemplo en Script Lab

Para probar cómo obtener y establecer la periodicidad de una cita con un complemento, instale el Script Lab para el complemento de Outlook y ejecute los siguientes fragmentos de código de ejemplo.

• "Obtener periodicidad (lectura)"
• "Obtener y establecer periodicidad (Organizador de citas)"

Para más información sobre Script Lab, consulte Explorar las API de JavaScript de Office con Script Lab.

Vea también

• Obtener o establecer la hora al redactar una cita en Outlook
• Obtener o establecer la ubicación al redactar una cita en Outlook