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.), a few columns are included in the file format specifically for controlling how 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 an ID is given in the upload file, and a corresponding item exists with that ID, the record 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.

Uploads for event items (Sessions, Speakers, Exhibitors, Custom Content, and Resources) do not need to contain a complete list. These items cannot be deleted through the CSV upload utility.

Fields Available in Event Content Types

Fields Available in Year-Round Content Types

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.

9. Appears in Directory field must be marked TRUE or FALSE.  TRUE = Registrant will appear in the directory by default.