Skip to main content

Import an .ics file into a show’s Content Calendar over REST

Premium Advanced Content Calendar

Two routes, POST /benecaster-content-calendar/v1/shows/{show_id}/ical/import/preview and POST …/shows/{show_id}/ical/import, with the same permission and per-show check as Read and write a show’s Content Calendar content items over REST.

Both send the whole file as content: text, at most 1 MB and 1,000 events. A refused file answers:

  • 400 benecaster_content_calendar_import_too_large or 400 benecaster_content_calendar_import_too_many past those limits.
  • 400 benecaster_content_calendar_import_not_ical when it is not a calendar.
  • 400 benecaster_content_calendar_import_empty when it has no events.

…/import/preview writes nothing. It answers { rows }, one per event in file order (an item from a Content Calendar export and its due entry are one row). A row is { index, state, message, tickable, ticked, title, publish_date, publish_time_label, due_date, due_time_label, type, type_name, status }. state is one of:

  • new (ticked).
  • cancelled: the file marked it cancelled. Unticked, may be ticked, and comes in Canceled.
  • already: imported to this show before, or an entry of this show’s own export.
  • duplicate: its UID appears earlier in the file.
  • repeats: it has an RRULE, RDATE or RECURRENCE-ID.
  • no_date.
  • orphan_due: a due entry without its item.

Only new and cancelled are tickable. type is '' except for a row read back from a Content Calendar export (Type: Title (Status)), which has the show’s type of that name, or other with type_name.

…/import sends { content, type, type_name, rows: [ { index, type, type_name } ] }. type is the import’s type, and a row’s type '' means the import’s. An Other row with no type_name takes the row’s own, then the import’s, then Imported. The route reads the file again and takes only positions and types from rows, so a row the preview did not offer is never imported. It answers { created: [ { index, id, title, publish_date } ], failed: [ { index, title, message } ] }, message being the item editor’s own refusal or the preview’s reason.

Every new item is a Draft (an item from a Content Calendar export keeps its status), made through the same checks as one made on the screen. It is saved with $context import and its event’s UID in source_uid (see Run your own code when a Content Calendar content item is saved or deleted). Times in UTC or a named TZID are converted to the site’s time zone; floating times and unknown zones are read as site time; all-day events stay all day.

Code

const root = benecasterAdmin.apiUrl.replace( /benecaster\/v1\/?$/, '' );
const post = ( path, body ) => fetch( `${ root }benecaster-content-calendar/v1/shows/${ showId }/${ path }`, {
    method: 'POST',
    credentials: 'same-origin',
    headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': benecasterAdmin.nonce },
    body: JSON.stringify( body ),
} ).then( ( r ) => r.json() );

const { rows } = await post( 'ical/import/preview', { content } );
const chosen = rows.filter( ( r ) => r.ticked ).map( ( r ) => ( { index: r.index, type: r.type, type_name: r.type_name } ) );
const { created, failed } = await post( 'ical/import', { content, type: 'other', type_name: 'From my booking tool', rows: chosen } );

View on GitHub →

Need this built rather than just documented? See our services →