Technical Details of Uploading Event Content
The CSV Upload Tool is meant for two different audiences: on the one hand, it’s intended to provide a convenient means for business users to quickly upload a large volume of data into a new event; while on the other, it’s intended to provide a pathway for loading data coming from some external system like an organization’s Association Management System.
This document is intended for the latter audience: developers and database administrators concerned with producing data files from existing data to be loaded into the system.
Controlling the Process
Along with the data fields you’d expect to find (session dates, speaker names, etc.), there are a few columns included in the file format specifically for controlling the way that the data is processed for all items.
The External Key column is expressly for this kind of export-to-import scenario, and is intended to contain the primary key of each record from its source system. This gives us a stable, unique identifier for each row, without requiring you to track Engagefully’s primary key values in your source data.
The ID column contains Engagefully's internal primary key values. As such, you can omit this column, or leave it empty, when generating data files from your systems to be imported into Engagefully.
Taken together, these two values control whether the input creates or updates an item in Engagefully. The value of ID is the automatically generated ID from Engagefully, and the External Key is the primary key of the record from the source system.
- If a row has neither an ID nor an External Key value, a new item will be created.
- If there is an ID, and a corresponding item exists with that ID, it will be updated. If no corresponding item is found, the API will report an error.
- If the row has no ID, but does have an External Key, then any corresponding item that already exists will be updated. If no corresponding item is found, a new item will be created.
As you can see, it’s very important that, if you plan to perform more than one bulk file transfer, you include a stable External Key value in your data. If you do not, there is a significant risk of creating duplicate records in Engagefully.
Other Control Fields
The External Timestamp is not currently used for anything by Engagefully, but will be saved if provided, and included in CSV files downloaded from the backoffice. This can be useful to determine whether the data that’s in Engagefully is up to date with the information in the source system.
Version protects against concurrent modifications when updating data. If it’s provided in the input, the item will be updated with the new data if and only if the record’s current version in the database matches the value in the input. (For example, if you download the current sessions and edit them, and I change one before you upload your modified file, that session’s version number will not match, and you will not accidentally overwrite my changes.)
Uploads for the Attendee Roster and Appointments must contain a complete list. Items not found in the upload file will be removed from the system.
Fields Available by Item Type
|Field||Session||Exhibitor||Speaker||Custom Content||Resource||Roster Entry||Appointment|
|About Content 4||as Description||as Description||as Bio||as Description||as Description|
|Associated Asset URL 2||as URL for Logo||as URL for Photo||
||as Resource URL|
|Start Time 1||Required||Yes||Required|
|End Time 1||Required||Yes||Required|
|URL for Photo 2||Yes||Yes|
|URL for Logo 2||Yes|
|Item ID 5||as Session ID||Yes||Yes|
|Item Key 5||as Session Key||Yes||Yes|
|Item Type 5||Yes||Yes|
|User Email List 8||Required|
- For maximum compatibility, dates should be provided in
yyyy-MM-dd HH:mm:ssformat, using a 24-hour clock (military time). For example, 6:10pm on Monday, November 18th would be written
2013-11-18 18:10:00. These values will be assumed to be in the event’s local time zone, unless they are specified to be in UTC (Coordinated Universal Time) by suffixing the value with a
Z. Internally, Engagefully stores all date/time values as UTC, and that’s what you’ll see when you download existing data.
- Web addresses, like a company’s web site, or the address of a resource file, must always be absolute URLs, beginning with
- Phone numbers are just strings, so any format may be used. For best results, however, they should conform to the formatting requirements of the
telURI scheme so that Engagefully can render them as such for users.
- The descriptive content for an item (Bio for speakers) may be plain text, or they may contain some limited HTML markup.
The Item ID and Item Key fields are used to build relationships between items:
- Speakers may only be associated with sessions, so the column names are more specific, and the Item Type is not used.
- Resources are assumed to link to sessions, but the Item Type can be set to any of
Customto specify the kind of item. A resource must be related to exactly one other item.
- Items of custom content types may be associated with any number of other items.
- If both an Item ID and Item Key value are provided, the ID will supersede the external key.
- If a speaker or custom content item is associated with multiple other items, then one of these fields may contain a pipe-delimited (
|) list of ID or external key values (the other must be empty). For custom content items, the Item Type must also contain a pipe-delimited list of item types.
Tags are collected into groups. Tag groups must be created in the backoffice, but individual tags will be created as necessary by the upload tool.
Each group is represented by a single column in the data, using the group’s name (with a required "Tag: " prefix). Any text within those columns will be used to create and edit tags. In order to apply multiple tags within a group to one item, use pipes (
|) to separate them.
The Custom1 and Custom2 fields provide options to include additional information that is specific to your organization. This can be anything shortform including credentials, interests, special codes, CEU credits, etc. The labels for these fields are configured on the event edit screen in the section labelled “Custom Labels” (or in the definition of a custom content type), and can be different for each type of item.
Your uploaded file must still label the columns
The User Email List field should be a pipe-delimited (
|) list containing the email addresses of people who should have the appointment on their schedule.