Import data

The Import Data screen imports events, venues and related data into JEM. It is intended for administrators who need to import external datasets, reuse saved import profiles, load curated catalog sources, migrate records from another JEM installation, load Special Days, or review import security and logs.

Where to Find it

Open the Joomla administrator and go to Components → JEM → Import Data. The screen is also available from the JEM control panel.

Access to Import Data requires JEM management permission. Users without the required Joomla permission cannot upload or import files.

Default Tab

Import Tabs

The Import Data page is organised into tabs so each workflow stays focused:

Before Importing

• Make a full backup of the target Joomla site and database.
• Test the import on a staging copy first.
• Use UTF-8 encoded files where possible.
• Check the CSV separator and delimiter configured in JEM.
• Review date and time formats before importing.
• Copy physical image and attachment files separately when needed.
• Use the preview step to review errors, warnings and duplicate candidates before saving records.
• For large public datasets, begin with unpublished records and verify a representative sample before publishing them.
• Save a reusable import profile only after checking its source, defaults, mapping and static values.

Event Import Tab

The Event Import tab imports events from external CSV, JSON, XML or ICS/iCalendar files. JEM detects the parser from the file extension. Sources can be uploaded from the administrator's computer or loaded from a public URL or Import Catalog entry.

This workflow is useful when importing events from spreadsheets, public calendars, school calendars, institutional event lists, or other applications that can export CSV or ICS files.

Event Import Options

Preview and Import

1. Select the file and configure the import options.
2. Click Preview import.
3. Review the preview table. The preview shows the detected file type/parser, title, date, time, category, type, venue, language, notes and status.
4. If valid rows are available, click Import to save them.
5. If the preview contains errors, correct the source file or options and run the preview again.

CSV Columns for External Events

The Event Import tab includes a help link named Show possible CSV columns for external events. It shows supported CSV headers and examples.

A practical CSV can use separate date and time columns:

title;dates;enddates;times;endtimes;introtext
Community workshop;2026-07-18;2026-07-18;18:30;20:00;Introductory session with registration and venue details.

A shorter CSV can include only the most common fields:

title;dates;times;introtext
Open doors day;2026-07-21;10:00;Short public visit with basic event information.

CSV files can also use date/time fields:

title;start_datetime;end_datetime;introtext
Evening concert;2026-07-22 20:00:00;2026-07-22 22:00:00;Outdoor summer concert.

Accepted aliases include title, name, event, event_title, dates, date, start, start_date, enddates, end, end_date, times, time, start_time, endtimes, end_time, introtext, description and text.

ICS/iCalendar Event Imports

ICS imports read VEVENT entries. JEM imports the event title, start date, end date, start time, end time, description and available metadata. A destination category must be selected before importing an ICS file.

ICS UID values are used for duplicate detection when available. Location data in the ICS file is added to the preview notes and can help the administrator choose the correct default venue.

Venue Import Tab

The Venue Import tab imports venue directories and public location datasets into JEM. It supports .csv, .json, .xml and .xlsx files and can read either a file uploaded in the browser or a public source URL.

Venue Import Options

Supported Venue Fields

The mapping step can assign incoming columns to standard venue fields and active custom fields. Common destinations include:

A venue name is the minimum required value. Choose None for source columns that should not be imported.

CSV, XLSX and Combined Coordinates

CSV imports use the separator configured in JEM and automatically compare semicolon, comma and tab. The first row must contain field names. XLSX imports read the first worksheet.

A single source column named coordinates, coordenadas, coords, gps or latlng can be mapped to coordinates (split into latitude and longitude). Values must contain latitude first and longitude second:

FUENTE;COORDENADAS
Plaza Cervantes;40.482149, -3.364360

JEM separates the coordinate pair automatically and stores it in the latitude and longitude fields.

Field Mapping and Static Values

After the source is read, JEM displays every incoming field beside the JEM field that will receive its value. Review the automatic assignments carefully, especially when source labels are not standard.

Use Static values to supply data that is not included in the file. Each static value has an application rule:

Venue Preview, Reload and Import

1. Select a profile or configure the source and fallback values.
2. Click Preview import.
3. Review the detected format, mapping, resulting JEM columns, row status, errors and notes.
4. Change incorrect mappings or add static values where necessary.
5. Click Reload preview to reprocess the stored source data with the new configuration. The file does not need to be selected again while the preview remains active.
6. When valid rows are available, click Import.

Large previews are displayed in pages or samples of 100 records. The complete validated payload remains available for import, and database writes are processed in batches of 100 records to reduce memory and database load.

Saving and Updating Venue Profiles

Enable Save this mapping as an import profile and enter a profile name to retain the current configuration. A profile is uniquely identified by:

Context + Format + Profile name

For example, Venues + JSON + Educational centres and Venues + CSV + Educational centres are separate profiles. Saving the same context, format and name again updates the existing profile instead of creating a duplicate.

JEM Migration Tab

The JEM Migration tab is for moving data from one JEM installation to another. These imports expect CSV files that follow JEM table fields and are best prepared from JEM exports.

Each migration card contains:

• A link to show possible columns for that JEM table.
• A Replace if ID exists option.
• A CSV file selector.
• An Import button.

Recommended Migration Order

1. Import Types first if events, venues, or categories reference type IDs.
2. Import Venues.
3. Import Categories.
4. Import Events.
5. Import Cat_Events relations if event-category links are supplied separately.
6. Import Attachments after the related records exist.

Replace Existing Records

Use Replace if ID exists carefully:

• No: safer for most imports because existing records are preserved where possible.
• Yes: allows matching records to be updated when the CSV contains existing IDs.

Do not enable replacement on a production site unless you have checked the IDs in the CSV file. A CSV exported from another site may contain IDs that already belong to different records in the target site.

Special Days Tab

The Special Days tab imports Special Days from CSV or ICS/iCalendar files. Special Days are used by calendars to mark days such as weekends, holidays, school periods, exams, public holidays or other day types.

Special Days Options

CSV Special Days

CSV imports can include the following fields:

id;title;alias;day_type;start_date;end_date;weekdays;country;region;city;description;published;ordering

Dates use YYYY-MM-DD. Start date and end date are required for every row. Weekdays can use numbers from 0 to 6 or names such as Saturday and Sunday.

title;day_type;start_date;end_date;weekdays;country;region;city;description;published;ordering
Saturday and Sunday;Weekend;2026-01-01;2026-12-31;Saturday,Sunday;;;;Regular weekend days;1;1
Christmas holidays;Public holiday;2026-12-24;2026-12-26;;;;;Christmas closure;1;2

ICS Special Days

ICS imports read VEVENT entries and convert them into Special Days. Select a Type of Day before previewing the import. This is useful for importing public holiday calendars, school calendars, labour calendars, or institutional closure days.

Special Days Preview

The preview table shows the title, date, Type of Day, description, notes and status. Review the preview before clicking Import.

Advanced / Tools Tab

The Advanced / Tools tab contains import diagnostics and log file access.

Import Logs

JEM stores import log files for the available import workflows. The tools area shows the log path and provides actions to view or download log files when they exist.

• View: opens the selected log content for quick inspection.
• Download: downloads the selected log file for support or auditing.
• Not created yet: no import has generated that log file yet.

Logs are useful when an import reports errors, skipped rows, duplicate candidates or parser details.

Import Catalog Tab

The Import Catalog tab lists curated public sources for events, venues and Special Days. A catalog entry can provide a direct source URL, format, location metadata, item count, defaults, static values and a reusable mapping profile.

Catalog Filters

Use the filters above the Available lists table to narrow the catalog. All filters can be combined:

Available Lists

Each catalog row can show the country, county, city, list name, description, import type, format, item count, category rule, source URL and mapping profile. A dash in the Items column means the source does not publish a known count. When a count verification date is available, it is shown as additional information.

Loading a Catalog Entry

1. Filter the catalog and review the source metadata.
2. Click Load in the required row.
3. JEM opens Event Import, Venue Import or Special Days according to the catalog entry type.
4. Review the selected source notice and the Profile configuration summary.
5. Check all defaults and click Preview import.
6. Correct the mapping, reload the preview and import only after the result has been reviewed.

If the catalog entry includes both a profile name and mapping, JEM creates or updates the related import profile. Existing site-specific options are preserved when the same catalog profile is loaded again.

Refreshing the Catalog

Click Refresh catalog to reload the active catalog source. Use this action after the official catalog has been updated or when source metadata, formats or item counts may have changed. Refreshing the catalog remains in the Import Catalog tab and does not start an import.

Official and Custom Catalogs

By default, JEM reads import_catalog_jem.xml from the official JEM update server. The Catalog structure panel identifies the active source and displays its availability, version and publication date.

A Super User can replace the official source with a custom catalog for testing, private lists or site-specific integrations:

1. Open the Catalog structure panel.
2. Click Load XML.
3. Select a valid JEM Import Catalog XML file no larger than 1 MB.
4. JEM validates and stores the XML for this website.
5. Confirm that Custom catalog loaded and its server path are displayed.

The custom catalog remains active until it is removed. Click the red X button and confirm the operation to delete the custom catalog and return to the official server source. Removing a custom catalog does not remove imported records or previously saved profiles.

Recommended Catalog-to-Venue Workflow

1. Open Import Catalog and set Type to Venues.
2. Apply Country, County, City or Format filters as needed.
3. Review the source, item count and description, then click Load.
4. In Venue Import, verify the source URL, profile, default Venue Type, publication state and language.
5. Generate the preview and check the automatic field mapping.
6. Add static location values where the public dataset omits them.
7. Reload the preview and review all errors and warnings.
8. Save the profile when the source will be reused, then import the valid records.

Security Tab

The Security tab controls the HTML security policy used by every JEM import. All imported fields are inspected before data is accepted.

Only a Super User can change the security policy. Security messages report the relevant entity, source field, line or record identifier when available. Detailed warnings are also written to the JEM import log for troubleshooting and support.

CSV Format Notes

• The first row must contain field names.
• JEM starts with the CSV separator configured in Settings and also compares semicolon, comma and tab.
• Keep IDs only when you understand how they map to the target site.
• Use plain CSV export from spreadsheet applications.
• Avoid spreadsheet changes that alter dates, leading zeroes, separators or encoding.
• When coordinates are stored in one CSV field, ensure the surrounding CSV delimiter does not split the coordinate pair incorrectly.
• JSON or XML is often preferable when the source contains nested fields or text with many separators, but the mapping must still be reviewed.

Attachments and Physical Files

The attachments import imports attachment records. It does not upload the physical files themselves. If imported records refer to files, those files must also exist in the configured JEM attachment path.

• Import events, venues, or categories before their attachments.
• Copy attachment files from the source site to the target site separately.
• Check the attachment path and file permissions after copying files.
• Use the backend Attachments view to audit imported attachment records.

Recommended Workflow

1. Make a full backup of the target site.
2. Prepare a source file, public URL, catalog entry or saved profile.
3. Check separators, delimiters, dates, categories, venues, types and language settings.
4. Run the import on a staging copy first.
5. Use the preview step for external events, venues and Special Days.
6. Review field mapping and static values, then reload the preview after every change.
7. Save a profile after its source, defaults and mapping have been verified.
8. For JEM migration, import records in the recommended order.
9. Review JEM Statistics, backend lists, frontend menu items, calendars and attachments.
10. Only repeat the import on production after the staging import has been checked.

After Importing

After importing, check both the backend records and the frontend output. An imported record may exist in the database but still be hidden on the frontend because of publication state, access, language, category, date, or menu item filters.

• Open the JEM Statistics panel and compare totals with the imported files.
• Check event, venue, category, type, Special Days and attachment backend lists.
• For imported venues, verify address fields, coordinates, Venue Type markers, contact information, level and capacity.
• Open frontend event lists, category views, venue views and calendars.
• Check image paths and attachment downloads.
• Review import logs if the import reported errors or skipped records.
• Use Housekeeping to remove orphaned references only after reviewing the imported data.

Troubleshooting

The file does not import

• Confirm that the file extension is supported for the selected tab.
• For URL imports, use a direct URL to the data resource rather than an HTML download page.
• For CSV files, confirm that the first row contains field names.
• Check the CSV separator and delimiter in JEM settings.
• Run the preview and read the status and notes columns.
• Open the import log from the Advanced / Tools tab.

The venue preview contains mapping errors

• Map the incoming venue name to venue (JEM); a venue name is required.
• Choose None for columns that should not be imported.
• Use the combined coordinates destination when latitude and longitude are stored in one field.
• Add missing country, region or city information with Static values.
• Click Reload preview after changing the mapping. The old row status is not authoritative until the preview has been recalculated.

A saved profile does not reopen its uploaded file

This is expected for browser uploads. The profile retains the configuration and original file name, but not the uploaded file contents. Select the local file again. Profiles based on public URLs can restore their URL automatically.

The Import Catalog is unavailable

• Check the active catalog source and availability indicator.
• Click Refresh catalog.
• If a custom catalog is active, validate its source URLs and XML structure.
• A Super User can remove the custom catalog with the red X button to restore the official source.

Import is blocked for security reasons

Read the reported source field, line and record identifier, then remove or replace the unsafe markup in the source. Core blocked tags cannot be enabled. A Super User can review additional tag rules and trusted iframe hosts in the Security tab. The JEM import log contains additional diagnostic details.

External events are not assigned to a category

Select a destination category before previewing the import. ICS imports require a selected destination category. CSV imports should also be reviewed to ensure the category assignment is correct.

Events are imported with wrong dates or times

• Check whether the CSV uses separate date/time fields or combined datetime fields.
• Use YYYY-MM-DD for dates where possible.
• Use 24-hour time such as 18:30.
• Check whether the source ICS file uses UTC times.

JEM migration records are duplicated or overwritten

Review the Replace if ID exists option and the IDs in the CSV file. On a second import, use a staging copy to confirm whether records will be inserted, skipped, or updated.

Attachments are listed but downloads fail

Confirm that physical files were copied to the expected attachment folders and that file permissions allow downloads.

Related Documentation

• Export Data
• Statistics
• Attachments
• Housekeeping
• Global Parameters
• Special Days settings

Related Project Notes

• #2140 documents category assignment problems found during import testing.
• #2085 discusses JEM import behaviour and migration use cases.
• #2030 covers export/import support for attachments and types.
• #1520 relates to export-to-import round-trip problems for events.
• #654 records earlier work around importing attachment data.
• #2218 proposes importable calendar entries and calendar markers, including CSV-based lightweight date layers for holidays, exams, deadlines, closures and similar calendar information.