Specifying Calendar recurrence



To create an event that recurs multiple times, you specify the following fields in the event attribute structure:

  • Set the IsRecurring field to true.

  • Specify a RecurrenceType field value of DAILY, WEELY, MONTHLY, or YEARLY.

  • (Optional) Specify one of the following mutually exclusive fields: RecurrenceCount, RecurrenceEndDate, or RecurrenceNoEndDate.

    Note: If you omit all three of these fields, the event is created with no end date, and if you specify a count or end date, the RecurrenceNoEndDate value is automatically false; therefore, Specify a RecurrenceNoEndDate field only if you are changing an existing event with a recurrence count or end date to one with no end date.

  • Specify the recurrence details in additional fields that depend on the recurrence type.

To change an event recurrence, including to change whether the event recurs, you specify only the fields whose values change. To stop an event from recurring, set the IsRecurring field to false. To convert an event from nonrecurring to recurring, set the IsRecurring field to true and set all the necessary recurrence fields.

The following sections describe how to specify each type of recurrence. For detailed descriptions of the fields that you use, see cfexchangecalendar in the CFML Reference.

Note: If you specify a recurrence rule that conflicts with the start date that you specify, the first occurrence of the event is on first day following the start date that conforms to the rule, not on the start date. For example, if you schedule an event for the second Tuesday of the month, and specify a start date of June 2, 2007, the first occurrence of the event is on June 12, 2007.

Specifying daily recurrence

To set a recurrence that is based on days, you do one of the following:

  • Define a RecurrenceFrequency field to specify the frequency of the event, in days. To schedule a meeting for every third day, for example, specify RecurrenceFrequency="3".

  • Specify RecurEveryWeekDay="true" to specify a meeting that is held five days a week.

You cannot use daily recurrence to schedule a single event that occurs a multiple number of times, but only on week days. To schedule such an event, specify a weekly recurrence with multiple recurrence days.

The following CFScript code sample sets daily recurrence for every three days and sets the event to occur 20 times: 

IsRecurring="true"; 
RecurrenceType="DAILY"; 
RecurrenceCount="20"; 
RecurrenceFrequency="3";

Specifying weekly recurrence

You can create an event that always occurs on the same day or days of the week, and occurs every week or every several weeks by specifying RecurrenceType="WEEKLY". You use the following fields to control the frequency:

  • Define a RecurrenceFrequency field to specify the frequency of the event, in weeks. If you omit this field, the event occurs every week. To schedule a meeting for every fourth week, for example, specify RecurrenceFrequency="4".

  • Specify a RecurrenceDays field with a comma-delimited list of one of more of the following strings: MON, TUE, WED, THUR, FRI, SAT, SUN. If you omit this attribute, the event recurs on the day of the week determined by the startTime field value.

The following CFScript code sample sets an event that occurs on Tuesday and Thursday of every other week until December 3, 2007.

IsRecurring="true"; 
RecurrenceType="WEEKLY"; 
RecurrenceEndDate="12/13/2007"; 
RecurrenceFrequency="2"; 
RecurrenceDays="TUE,THU;

Specifying monthly recurrence

You can create an event that always occurs on a monthly basis, or occurs every several months by specifying RecurrenceType="MONTHLY". You can schedule two types of events:

  • Events that occur on the same date of each scheduled month, for example, on the tenth day of every three months.

  • Events that occur on the same week of the month and the same day of the week, for example, on the second thursday of every month, or on the last Friday of every six months.

To specify a date-based monthly event, you only specify the recurrence type, and, if the recurrence is not every month, the frequency. ColdFusion schedules the event to occur on the day of the week determined by the startTime field value. To schedule a meeting that occurs on the start date every four months, specify the following recurrence fields:

IsRecurring="true"; 
RecurrenceType="MONTHLY"; 
RecurrenceFrequency="4";

To specify an event that occurs on the same day of the week, specify the following fields in addition to RecurrenceType:

Field

Description

RecurrenceFrequency

The frequency of the event, in months. If you omit this field, the event occurs every month.

RecurrenceWeek

The week of the month on which the event occurs. Valid values are first, second, third, fourth, and last.

RecurrenceDay

The day of the week on which the event occurs. Valid values are SUN, MON, TUE, WED, THU, FRI, and SAT.

The following CFScript code sample sets an event that occurs on the third Thursday of every three months:

IsRecurring="true"; 
RecurrenceType="Monthly"; 
RecurrenceFrequency="3"; 
RecurrenceWeek="third"; 
RecurrenceDay="THU";

Specifying yearly recurrence

You can create an event that always occurs on a yearly basis by specifying RecurrenceType="YEARLY". You can schedule two types of events:

  • Events that occur on the same date of each year, for example, on every August 10.

  • Events that occur on a specific day week and month, for example, on the second Thursday of August.

To specify a date-based yearly event, you only specify the recurrence type. ColdFusion schedules the event to occur each year on the date determined by the startTime field value. To schedule a meeting that occurs on the start date every year, specify the following recurrence fields:

IsRecurring="true"; 
RecurrenceType="YEARLY";

To specify an event that occurs on the same day of the week and month each year, specify the following fields in addition to RecurrenceType:

Field

Description

RecurrenceMonth

The month of the year which the event occurs. Valid values are JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, and DEC.

RecurrenceWeek

The week of the month during which the event occurs. Valid values are first, second, third, fourth, and last.

RecurrenceDay

The day of the week on which the event occurs. Valid values are SUN, MON, TUE, WED, THU, FRI, and SAT.

The following CFScript code sample sets an event that occurs on the third Thursday of August three months:

IsRecurring="true"; 
RecurrenceType="YEARLY"; 
RecurrenceMonth="AUG"; 
RecurrenceWeek="third"; 
RecurrenceDay="THU";

Example: Setting calendar recurrence

The following example lets you create events with all types of recurrence. To limit the code length, it does not prevent you from attempting to create events with invalid field combinations. When you submit the form, if an event is created, the form redisplays, preceded by a dump that shows the field values that were used to create the event, and the event UID. You cannot resubmit the form to modify the event, but you can change some values in the form and create an event.

<!--- Create a structure to hold the event information. ---> 
<cfparam name="form.eventID" default="0"> 
 
<!--- If the form was submitted, populate the event structure from it. ---> 
<cfif isDefined("Form.Submit")> 
    <cfscript> 
        sEvent.AllDayEvent="false"; 
        sEvent=StructNew(); 
        sEvent.Subject=Form.subject; 
        if (IsDefined("Form.allDay")) { 
            sEvent.AllDayEvent="true"; 
            sEvent.StartTime=createDateTime(Year(Form.date), Month(Form.date), 
                Day(Form.date), 8, 0, 0); 
        } 
        else { 
            sEvent.StartTime=createDateTime(Year(Form.date), Month(Form.date), 
                Day(Form.date), Hour(Form.startTime), Minute(Form.startTime), 0); 
            sEvent.EndTime=createDateTime(Year(Form.date), Month(Form.date), 
                Day(Form.date), Hour(Form.endTime), Minute(Form.endTime), 0); 
        } 
        sEvent.Location=Form.location; 
        sEvent.RequiredAttendees=Form.requiredAttendees; 
        sEvent.OptionalAttendees=Form.optionalAttendees; 
        //sEvent.Resources=Form.resources; 
        if (Form.reminder NEQ "") { 
            sEvent.Reminder=Form.reminder; 
        } 
        else { 
            sEvent.Reminder=0; 
        } 
        sEvent.Importance=Form.importance; 
        sEvent.Sensitivity=Form.sensitivity; 
        //Recurrence Fields 
        if (IsDefined("Form.isRecurring")) { 
            sEvent.IsRecurring="true";} 
        if (IsDefined("Form.recurrenceNoEndDate")) { 
            sEvent.RecurrenceNoEndDate="true";} 
        if (Form.recurrenceCount NEQ "") { 
        sEvent.RecurrenceCount=Form.recurrenceCount;} 
        if (Form.recurrenceEndDate NEQ "") { 
        sEvent.RecurrenceEndDate=createDateTime(Year(Form.recurrenceEndDate), 
            Month(Form.recurrenceEndDate), Day(Form.recurrenceEndDate), 0, 0, 
            0);} 
        sEvent.RecurrenceType=Form.recurrenceType; 
        if (Form.recurrenceFrequency NEQ "") { 
        sEvent.recurrenceFrequency=Form.recurrenceFrequency;} 
        if (IsDefined("Form.recurEveryWeekDay")) { 
            sEvent.RecurEveryWeekDay="true";} 
        if (Form.recurrenceDays NEQ "") { 
        sEvent.RecurrenceDays=Form.recurrenceDays;} 
        if (Form.recurrenceDay NEQ "") { 
        sEvent.RecurrenceDay=Form.recurrenceDay;} 
        if (Form.recurrenceWeek NEQ "") { 
        sEvent.RecurrenceWeek=Form.recurrenceWeek;} 
        if (Form.recurrenceMonth NEQ "") { 
        sEvent.RecurrenceMonth=Form.recurrenceMonth;} 
             
        sEvent.message=Form.Message; 
    </cfscript> 
     
<cfdump var="#sEvent#"> 
 
<!--- Create the event in Exchange. ---> 
    <cfexchangecalendar action="create"  
        username ="#user1#" 
        password="#password1#" 
        server="#exchangeServerIP#" 
        event="#sEvent#" 
        result="theUID"> 
    <!--- Output the UID of the new event --->     
    <cfif isDefined("theUID")>         
        <cfoutput>Event Added. UID is#theUID#</cfoutput> 
        <cfset Form.eventID = theUID > 
    </cfif> 
</cfif> 
 
<cfform format="xml" preservedata="true" style="width:500" height="700"> 
    <cfinput type="text" label="Subject" name="subject" style="width:435"> 
            <br /> 
    <cfinput type="checkbox" label="All Day Event" name="allDay"> 
    <cfinput type="datefield" label="Date" name="date" validate="date" 
        style="width:100"> 
    <cfinput type="text" label="Start Time" name="startTime" validate="time" 
        style="width:100"> 
    <cfinput type="text" label="End Time" name="endTime" validate="time" 
        style="width:100"><br /> 
    <cfinput type="text" label="Location" name="location" 
        style="width:435"><br /> 
    <cfinput type="text" label="Required Attendees" name="requiredAttendees" 
        style="width:435"><br /> 
    <cfinput type="text" label="Optional Attendees" name="optionalAttendees" 
        style="width:435"><br /> 
    <cfinput type="text" label="Resources" name="resources" 
        style="width:435"><br /> 
    <cfinput type="text" label="Reminder (minutes)" validate="integer" 
        name="reminder" style="width:200"> 
    <cfselect name="importance" label="Importance" style="width:100"> 
        <option value="normal">Normal</option> 
        <option value="high">High</option> 
        <option value="low">Low</option> 
    </cfselect> 
    <cfselect name="sensitivity" label="Sensitivity" style="width:100"> 
        <option value="normal">Normal</option> 
        <option value="company-confidential">Confidential</option> 
        <option value="personal">Personal</option> 
        <option value="private">Private</option> 
    </cfselect> 
    <hr /> 
    <!--- Recurrence Information ---> 
    <cfinput type="checkbox" label="IsRecurring" name="isRecurring"> 
    <cfinput type="checkbox" label="RecurrenceNoEndDate" name="noEndDate"> 
    <cfinput type="text" label="RecurrenceCount" validate="integer"  
        required="false" name="recurrenceCount">     
    <cfinput type="text" label="RecurrenceEndDate" validate="date"  
        required="false" name="recurrenceEndDate">      
    <cfselect name="RecurrenceType" label="Recurrence Type" 
            style="width:100"> 
        <option value="DAILY">Daily</option> 
        <option value="WEEKLY">Weekly</option> 
        <option value="MONTHLY">Monthly</option> 
        <option value="YEARLY">Yearly</option> 
    </cfselect> 
    <cfinput type="text" label="RecurrenceFrequency" validate="integer" 
        name="recurrenceFrequency">      
    <cfinput type="checkbox" label="RecurEveryWeekDay" 
        name="recurEveryWeekDay"> 
    <cfinput type="text" label="RecurrenceDays" name="recurrenceDays">      
    <cfinput type="text" label="RecurrenceDay" name="recurrenceDay">      
    <cfselect name="RecurrenceWeek" label="RecurrenceWeek" style="width:100"> 
        <option value=""></option> 
        <option value="first">First</option> 
        <option value="second">Second</option> 
        <option value="third">Third</option> 
        <option value="fourth">Fourth</option> 
        <option value="last">Last</option> 
    <cfinput type="text" label="RecurrenceMonth" name="recurrenceMonth">      
    </cfselect> 
    <hr />  
    <cfinput type="textarea" label="Message" name="message" style="width:300;  
            height:100"> 
    <cfinput type="Submit" name="submit" value="Submit" > 
</cfform>