Technical Details of Uploading 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 (dates, 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 in Event Content Types

Field Session Exhibitor Speaker Custom Content Resource Roster Entry Appointment
ID Yes Yes Yes Yes Yes Yes
Yes
Name Required Required Required Required Required
About Content 1 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
Created Read-only Read-only Read-only Read-only Read-only
Updated Read-only Read-only Read-only Read-only Read-only
External Key Yes Yes Yes Yes Yes Yes Required
External Timestamp Yes Yes Yes Yes Yes
Version Read-only Read-only Read-only Read-only Read-only
Start Time 3 Required Yes Required
End Time 3 Required Yes Required
Location Yes Yes
Hashtag Yes
Tag 7 Yes Yes Yes
Booth Yes
URL 2 Yes Yes Yes Yes
Email Yes Yes Yes Required
Address Yes
Phone 4 Yes Yes Yes Yes
Fax 4 Yes
Facebook Yes
LinkedIn Yes
Twitter Yes Yes
YouTube Yes
First Name Required Required
Last Name Required Required
Title Yes Yes
Company Yes Yes
URL for Photo 2 Yes Yes
URL for Logo 2 Yes
Sorting Yes
Keywords Yes
Item ID 5 as Session ID Yes Yes
Item Key 5 as Session Key Yes Yes
Item Type 5 Yes Yes
Custom1 6 Yes Yes Yes Yes Yes
Custom2 6 Yes Yes Yes Yes Yes
User Email List 8 Required

Fields Available in Year-Round Content Types

Field Custom Content Resource
ID Yes Yes
Name Required Required
About Content 1 as Description
Associated Asset URL 2 as Resource URL
Created Read-only Read-only
Updated Read-only Read-only
External Key Yes Yes
External Timestamp Yes Yes
Version Read-only Read-only
Start Time 3 Yes
End Time 3 Yes
URL 2 Yes
Email Yes
Phone 4 Yes
URL for Photo 2 Yes
URL for Logo 2 Yes
Sorting Yes
Keywords Yes
Item ID 5 Yes Yes
Item Key 5 Yes Yes
Item Type 5 Yes Yes
Custom1 6 Yes
Custom2 6 Yes
  1. The descriptive content for an item may be plain text, or they may contain some limited HTML markup.
  2. Web addresses, like a company’s web site, or the address of a resource file, must always be absolute URLs, beginning with http:// or https://.
  3. For maximum compatibility, dates should be provided in yyyy-MM-dd HH:mm:ss format, 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.
  4. Phone numbers are just strings, so any format may be used. For best results, however, they should conform to the formatting requirements of the tel URI scheme so that Engagefully can render them as such for users.
  5. The Item ID and Item Key fields are used to build relationships between items:

    • A resource must be related to exactly one other item. At the current time, that item may only be a custom content item, and the value of Item Type must be set to Custom.
    • Items of custom content types may be associated with any number of other custom content items (the type definition determines which relationships are allowed).
    • If both an Item ID and Item Key value are provided, the ID will supersede the external key.
    • If a 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). The Item Type field must also contain a corresponding pipe-delimited list of item types.
  6. The Custom1 and Custom2 fields provide options to include additional information that is specific to your organization. This can be anything short-form 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 Custom1 and Custom2.

  7. 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.

  8. 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.

Still need help? Contact Us Contact Us