Importing events to the Calendar module

Whether migrating existing event data from another system or adding next year's events from a planning document, the Calendar module event importer makes the task of adding events and recurring event sequences easy. Before you click the Import button, we encourage you to take time to familiarise yourself with our top tips for preparing the data, which will ensure the data passes validation and events are created as expected.

Preparing your data

Here's a simple checklist of things to do before importing event data:

1. Make sure your data is in the right format and file type

To import data to ChurchSuite it needs to be in the form of a CSV file, using a comma as the delimiter and in UTF-8 format. Spreadsheet applications such as MS Excel, Apple Numbers and Google Docs allow you to easily save data as a CSV file in the correct format. Similarly, many calendar applications allow you to export data as a CSV file. Some great online file converters will easily convert ICS format files to CSV.

2. The first row must contain column header labels

The ChurchSuite importer will use the column header labels to map the data in each column of the CSV file to the correct field in ChurchSuite. You will be able to override the default mapping before completing the import - perhaps to correct a wrongly-mapped field - but by using ChurchSuite's field-naming convention (see later in this article), the event data will be auto-mapped to the correct ChurchSuite fields, making the process even simpler. Event data must start from row 2 in the CSV file.

Do not use the same column header label more than once in the CSV file, otherwise, columns will be ignored during import - column header labels in row 1 only must be uniquely named.

3. Review the Calendar module settings

Unless explicitly specified in the CSV file, the Status of each imported event will be the default event status specified in the module settings. If you typically add events with a pending status, you may wish to temporarily change the default status so that the imported events have a confirmed status, otherwise, you will need to update the status to confirmed after import.

In the following example, rows without a specified status will derive the default status set in the module settings.

4. Set up event Categories before import

Ensure that any event Categories being specified in the CSV file are set up in ChurchSuite and ready to receive data - see the related support articles for further information about event categories. The category naming convention used in the CSV file must precisely match the naming convention used in the Calendar module.

5. Date and time format consistency

Different calendar applications and spreadsheet applications will store and display dates in a wide variety of formats. Date and time formats will also vary regionally and may be influenced by device or browser settings. To avoid unexpected results and ensure all imported events and event sequences are correctly created, the following formatting conventions are supported: -

• All dates specified in your CSV file - start dates, end dates, sequence dates, repeat until dates - must be formatted in either the ISO format (YYYY-mm-dd) or your local format (e.g. UK: dd/mm/YYYY or North America: mm/dd/YYYY) - forward slash or hyphen separators are supported
• Times must be specified in 24-hour clock hh:mm (e.g. 19:30). 12-hour clock with AM and PM (e.g. 7:30 PM) is not supported
• Event start and end fields - ideally specified as datetime_start and datetime_end in your CSV headers - will accept values comprising dates only (e.g. an all-day event) or dates with times (see examples below)
• The event end date is optional. If not specified, and if the event start date is specified without a start time, the importer will derive the event to be an "all-day" event. However, if the event end date is specified with a time, the event is deemed to start at midnight on the start date, running until the specified end date and time
• An event end date and time must be later than the event start date and time

In the above example CSV,

• row 11 only has a start date specified - the event will be created as an "all-day" event
• row 6 has a start date and end date specified - the event will be created as an "all-day" event
• row 9 has a different start and end date specified - the event will be created as a multi-date "all-day" event
• row 13 has a specified start date and time, but no end date - this is likely to be a mistake and unless corrected, the event will be created as running from 19:00 until 23:59 on the start date
• row 12 has specified times spanning a range of dates - the event will be created running from the start date and time until the end date and time
• for events that have start and end times, rows 2 and 3 are examples of how valid event data should be presented

6. Multi-site considerations

Events can be site-specific, multiple sites or "All sites". When importing events, set up the Sites in ChurchSuite first and be sure to specify "sites" as a column in the data file so that each event is assigned to the correct site during the import process (the site-naming convention in the CSV file must match the site-naming convention used in ChurchSuite). Any events without a site specified will be imported as "All sites" events - do not specify "All sites" in the CSV file - leave the site blank/empty. Separate multiple sites with a semicolon.

In the example above, rows 1 and 2 are site-specific events, row 3 is a multiple-site event; all other rows have no site specified and will be imported as "All sites" events.

7. Recurring events - event sequences

The importer supports the creation of recurring event sequences that follow common repeat patterns (using the repeat and repeat frequency and repeat until fields). If a repeat until date is not specified the importer will restrict the sequence length to 2 years - it's not possible to create an endless event sequences.

It's also possible to explicitly specify a comma-separated list of sequence dates (using the sequence_dates field) - ideal if the event comprises a variety of ad hoc dates and doesn't follow a common repeat pattern.

For each row in the CSV file, the repeat_frequency and repeat_until fields, if specified, will ignore any use of the sequence_dates field - you must use one or the other, but not both methods.

Supported repeat_frequency values are: -

• daily - will create a sequence of every date from the start date up to and including the sequence end date
• weekdays - will create a sequence of dates that excludes Saturdays and Sundays
• weekends - will create a sequence of dates that are only Saturdays and Sundays
• weekly - will create a sequence of dates that repeats on the same day each week e.g. 1st Oct, 8th Oct, 15th Oct...
• fortnightly - will create a sequence of dates that repeats on the same day every two weeks e.g. 1st Oct, 15th Oct, 29th Oct
• three_weekly - will create a sequence of dates that repeats on the same day every three weeks e.g. 1st Oct, 22nd Oct, 12th Nov, 3rd Dec
• four_weekly - will create a sequence of dates that repeats on the same day every four weeks e.g. 1st Oct, 29th Oct, 26th Nov, 24th Dec
• monthly_date - will create a sequence of dates that repeats on the same date every month e.g. 1st Oct, 1st Nov, 1st Dec
• monthly_day - will create a sequence of dates that repeats on the same day of that same week every month e.g. 1st Oct, 5th Nov, 3rd Dec
• monthly_last - will create a sequence of dates that repeats on the same day of the last week every month e.g. 26th Oct, 30th Nov, 28th Dec
• yearly_date - will create a sequence of dates that repeats on the same date of the last week every month e.g. 1st Oct 2021, 1st Oct 2022, 1st Oct 2023

8. Need some inspiration?

You may find our Example event import CSV file useful - click to download and open it in a preferred spreadsheet application. A full list of supported import fields is also provided.

Importing your calendar file into ChurchSuite

Working within the Calendar module Events section, click Import events.

The Import events page contains lots of useful information to help prepare your file ready for import. There's even an Example file that you can download to help get you started - which will help you visualise how your event data needs to be presented, or it can be used as a template for your event import. There's a comprehensive list of all the supported fields that can be imported. You don't have to supply data for every field in your CSV file but ChurchSuite will import every column in the CSV file that has a field header that it recognises.

When ready to proceed, click Choose file to navigate to and select the CSV to be uploaded. Then click Upload CSV File.

ChurchSuite now displays a preview of the first 5 records in the CSV file so that you can check that the CSV Header fields are correctly mapped to the right field in ChurchSuite - the Import As column shows which field in ChurchSuite the data from the CSV file will be assigned to. Any CSV Header fields not matched to a ChurchSuite field are distinguished by a yellow warning triangle and will not be imported...

However, you can use the drop-down Import As selector to choose the correct ChurchSuite field that the CSV Header item should be mapped to. In the example below, "event" is not a recognised CSV Header, but needs to be imported into the event "Name" field in ChurchSuite.

Once satisfied that all CSV Header fields will be Imported As the correct field in ChurchSuite, scroll to the end of the page and click Import All Records to complete the import. Alternatively, click Cancel if you discover an issue that needs to be addressed in your CSV file.

The import progresses to the Preview/Edit stage. Valid events are distinguished with a green tick. Invalid events requiring attention are distinguished with a yellow warning triangle and details of the Errors are provided. You can View, Edit (to fix the invalid data) or Remove an event from the import.

Continue working through and resolving each error in the list. Note that you can Pause or Delete an event import at any time. You can also Process events at any time - only valid events will be processed and imported; invalid events with errors will remain in the "Preview/Edit" until resolved or removed.

To resume a Pending import, click Import events from the Events section of the Calendar module. Partial/incomplete imports are shown on the Imports tab. From here you can Resume or Delete a partial import. Resuming an import takes you back to where you last left off.

Having resolved all remaining errors you can now Process to complete the import. A success message confirms the completion of a successful import.

For churches following the Common Worship Lectionary, we've produced a separate support article that explains how to easily obtain and import the lectionary into your Calendar module.