Events (CalendarEvent)
Events are scheduled activities that are automatically added to your calendar when created. For more information, see Working with Events.
The event record is defined in the actSched (scheduling) XSD.
Supported Operations
add | addList | attach / detach | delete | deleteList | get | getDeleted | getList | getSavedSearch | getSelectValue | search | update | updateList | upsert | upsertList
You can also use the asynchronous equivalents of SOAP web services list operations. For information about asynchronous operations, see SOAP Web Services Asynchronous Operations. For more information about request processing, see Synchronous Versus Asynchronous Request Processing.
Field Definitions
The SOAP Schema Browser includes definitions for all body fields, sublist fields, search filters, and search joins available to this record. For details, refer to the SOAP Schema Browser’s calendar event reference page.
For information on using the SOAP Schema Browser, see SOAP Schema Browser.
Usage Notes
Events can be scheduled as one-time events that are set to occur on a specific day at a specific time. Events can also be designated as recurring events, which recur over a period of several days, weeks, months, or years. See the following sections for more information:
Non-Recurring (One-Time) Events
A non-recurring event takes place one time during a single day. Note that a non-recurring event cannot extend beyond midnight in a user's specified time zone. Both the startDate and endDate fields must contain the same date.
Recurring Events
Recurring events recur on a daily, weekly, monthly, or yearly basis. You can schedule events to automatically recur in your calendar in both basic and advanced patterns.
Basic Recurrence Patterns
A basic event recurrence pattern includes events such daily departmental status meetings. These events begin and end on the same day, and they recur in a Monday through Friday pattern. An event with a basic recurrence pattern does not require that you set the recurrenceDow, recurrenceDowim, or recurrenceDowMaskList fields.
To set a basic recurrence pattern:
-
Set the frequency field.
-
Set the period field.
-
Set the startDate field.
-
Set the endDate field only if there is a known date by which you want to end the recurring event. Events that recur indefinitely do not require that you set the endDate field.
Advanced Recurrence Patterns
Events that are scheduled with advanced recurrence patterns may include some of the following types of patterns:
-
A certain number of days apart, such as every 3 days
-
The same day of the week with weeks off in between, such as Tuesday every 2 weeks
-
The same date of every month
-
The same date in a month with months off in between, such as every 3 months on the 20th
-
The same day of the week every month, such as the first Friday of every month
-
The same day of the week every few months, such as the first Tuesday every other month
To set an advanced recurrence pattern for an event, you must set the following fields, in addition to setting the frequency, period, and startDate fields:
-
recurrenceDow
-
recurrenceDowim
-
recurrenceDowMaskList
The recurrenceDow, recurrenceDowim, and recurrenceDowMaskList fields do not have corresponding field labels in the UI. These fields represent a collection of functions which are shown in the figure below.
The recurrenceDow, recurrenceDowim, and recurrenceDowMaskList fields are hidden fields in SuiteScript. These fields are currently supported in server-side SuiteScript development; they are not supported in client development.
The following screenshot represents the scheduling of a monthly event that contains an advanced recurrence pattern.
The preceding screenshot shows the equivalent of the following settings.
|
Callout |
Description |
|---|---|
|
1 |
The frequency field is set to _month. |
|
2 |
The recurrenceDowim field is set to _first. |
|
3 |
The recurrenceDow field set to _wednesday. |
|
4 |
The period field is set to 1. |
The next screenshot represents the scheduling of a weekly event that contains an advanced recurrence pattern.
The preceding screenshot shows the equivalent of the following settings.
|
Callout |
Description |
|---|---|
|
1 |
The frequency field is set to _week. |
|
2 |
The recurrenceDowMaskList field is set to _tuesday and _thursday. |
To set an advanced recurrence pattern that recurs monthly or yearly:
-
Set the frequency field to indicate how often the event will recur. The value specified for frequency dictates the values that will be set for the recurrenceDow and recurrenceDowim fields.
-
Next, set the period field.
-
Set the value for recurrenceDow.
-
Set the value for recurrenceDowim.
To set an advanced recurrence patterns that recurs weekly:
-
Set the frequency field to indicate how often the event will occur. The value specified for frequency dictates the value that will be set for the recurrenceDow MaskList.
-
Next, set the period field.
-
Finally, set recurrenceDowMaskList.
Updating a Series of Events that Include Advanced Recurrence Patterns
When updating a record in SOAP web services, generally you submit only the values you intend to change. However, when updating an event record that includes advanced recurrence patterns, you must use nullFieldList to explicitly remove the values that were previously set.
For example, to update a monthly or a yearly event from a specific day of the week in a month to a specific day of the month, use nullFieldList to explicitly remove the values in recurrenceDowim and recurrenceDow.
Updating a Single Instance of a Recurring Event
A recurring event can be modified to change or delete an individual event in the series. In SOAP web services, this is handled using the ExclusionDateList type.
Deleting individual events in a series
To delete individual events in a series, update the recurring event with a list of exclusions (in the form of dates) in the ExclusionDateList type. The ExclusionDateList type sets a list of timestamps of individual events that have been excluded from the series.
After an event has been excluded, it is separated from the rest of the events in the series, and it can NOT be associated with the event series.
To update an individual instance of a recurring event
-
Update the recurring event with a list of exclusions (in the form of dates) in the exclusionDateList field.
-
For each exclusion, add a new event that contains the updated data.
The original event and the new modified event have different internal ID values and the new updated event is no longer associated with the event series.
Retrieving excluded events from a series
To retrieve excluded events from a series, submit a get operation for the desired event series and return the values listed in the ExclusionDateList type.
Working with Event Lists
The SOAP Schema Browser includes all lists (sublists) associated with the Event record. See the following information for usage notes regarding specific Event lists. Note that usage notes are not provided for every list type.
AttendeeList
This list is used to identify each attendee for the event.
ExclusionDateList
This list is used to denote individual events in a series that have been modified or deleted. For detailed information, see Updating a Single Instance of a Recurring Event.
ResourceList
This list is used to schedule available resources for the event.
TimeItemList
This list, available when the Time Tracking feature is enabled, is used to track employee time associated with the event, including payroll, billing, and project fields.