Importing events from an iCal feed

One-off imports

Event Organiser allows you to perform a manual import of events from iCal file (.ics). The steps for doing this are provided here: http://docs.wp-event-organiser.com/quick-start/importing-an-ical-feed-from-google-2/ (using a Google calendar as an example).

‘Subscribing’ to a feed

With the Event Organiser iCal Sync extension you can ‘subscribe’ to a iCal feed and regularly import events from that feed so that your site remains update to date with the source site or service. For instance, your events might be managed via Google Calendar and you simply want the events added there to appear on your site.

Once you’ve installed iCal Sync, simply follow these steps: http://docs.wp-event-organiser.com/quick-start/subscribing-to-an-ical-feed/

Importing from the command line

Event Organiser iCal Sync exposes a number of commands through WP-Cli to manage, sync and validate your feeds from the command line.

Once WP-Cli is installed (see install instructions) and Event Organiser iCal Sync is installed simply run:

wp eo ical-feed --help

to view the available commands. These include:

  • fetch – to trigger an import of a feed (or all feeds using --all)
  • validate – to validate an iCal feed or URL. This will highlight any errors in the feed.
  • create – Create a feed
  • update – Update a feed
  • delete – Delete a feed (use --delete-events to trash any imported events)
  • delete-events – Trash events imported from a feed, while leaving the feed in place.

For details and available parameters run:

wp eo ical-feed <command> --help

Import using Cron

By default Event Organiser iCal Sync uses WP-Cron to automatically import feeds. The advantage is that it requires no server-side configuration, however this comes at the expense of accuracy of when the job is run.

If you wish to set up a genuine cron job to pull in events from your feeds, you shall need to install WP-Cli. Once installed there are a number of commands available (see above) related to your iCal feeds.

To set up a cron job, first ssh onto your sever. Once there run the command:

 crontab -e

to edit your crontab file. This lists all your cron jobs with each line corresponding to one job and of the format:

 minute hour day month day-of-week command-to-execute

The first 5 values indicate the frequency with which the job is run and the last value indicates the cron job to run.

The command to run is:

 wp --path=/path/to/your/site eo ical-feed fetch --all

Values indicating the frequency of the job must all be specified and must take the values:

Field Range of values
minute 0-59, or *
hour 0-23, or *
day 1-31, or *
month 1-12, or *
day-of-week 0-7 (where both 0 and 7 mean Sun, 1 = Mon, 2 = Tue, etc), or *

The values specify which minute/hour/day etc you want the job to run on. The ‘wildcard’ * means every (minute/hour/day etc).

For example 0 20 * * * <command> means run the command at 8pm every day of every month. This allows you to fine tune exactly when and how frequently your feeds import.

As a complete example, to fetch all feeds at 2am every morning:

 0 2 * * * wp --path=/path/to/your/site eo ical-feed fetch --all

You can import feeds at different times/frequencies. For example to import feed with ID 123 (you can view your feed IDs by running wp eo ical-feed list) at 2am every day and the feed 456 at 3am every Sunday:

 0 2 * * * wp --path=/path/to/your/site eo ical-feed fetch 123
 0 3 * * 0 wp --path=/path/to/your/site eo ical-feed fetch 456

Importing venue information

Unfortunately the iCal specification does not provide for venue information aside from venue name and latitude and longtitdue co-ordinates.

However, your source feed may providing that information (in a non-standard) way via the LOCATION property in your feed. In this case you can use the eventorganiser_ical_import_venue filter to tell the plug-in how to interpret any new venues it attempts to import.

Lets suppose your feed uses the LOCATION attribute to specify the feed as follows:

LOCATION:<name>,<address>,<city>,<postcode>

e.g.

LOCATION:Sherlock Holmes,221B Baker Street,London,NW1 6XE

By default the plug-in will interpret the LOCATION value as the venue’s name, so you can do the following to correct that:

add_filter( 'eventorganiser_ical_import_venue', 'my_ical_set_venue_details', 10, 4 );
function my_ical_set_venue_details( $venue, $event, $event_id, $ical ) {

    //Assuming venue is giving in iCal in the following form:
    // <name>,<address>,<city>,<state>
    $parts = explode( ',', $venue['name'] );

    $keys  = array( 'name', '_address', '_city', '_state' );
    $count = min( count( $keys ), count( $parts ) );

    $venue_details = array_combine( 
         array_slice( $keys, 0, $count ), 
         array_slice( $parts, 0, $count )
    );

    $venue = array_merge( $venue, $venue_details );

    return $venue;
}

The values passed to the hooked callback include:

  • $venue (array) – An array which will contain the venue name (with the name as given in iCal), and possibly latitude and longitude if these are given by the feed. It’s this array which is used to create the venue.
  • $event (array) – The event parsed from iCal feed to which this venue is assigned.
  • $event_id (ID) – The ID of above event. Lastly $ical is the parser object for context reference.
  • $ical (EO_ICAL_Parser) – Instance of the class responsible for parsing iCal feeds. Contains the feed and parsed information (including source, events, venues and categories).

Note: This will not update an existing venue.