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 except the Attendee Roster
- The External Key column is expressly for this kind of export-to-import scenario, and is intended to contain the primary key of the each record from its source system. This gives us a stable, unique identifier for each row, without requiring you to track Eventsential’s primary key values in your source data.
- The ID column contains Eventsential’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 Eventsential.
Taken together, these two values control whether the input creates or updates an item in Eventsential. The value of ID is the automatically generated ID from Eventsential, 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 Eventsential.
Other Control Fields
- The External Timestamp is not currently used for anything by Eventsential, but will be saved if provided, and included in CSV files downloaded from Eventsential. This can be useful to determine whether the data that’s in Eventsential 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.)
Fields Available by Item Type
|About Content 4||as Description||as Description||as Bio|
|Associated Asset URL 2||as Logo URL||as Photo URL||as Handout URL|
|Start Time 1||Required|
|End Time 1||Required|
|Item ID 5||as Session ID||Yes|
|Item Key 5||as Session Key||Yes|
|Item Type 5||Yes|
- 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, Eventsential 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 http:// or https://.
- 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 Eventsential 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.
- Speakers may only be associated with sessions; resources are assumed to link to sessions, but the Item Type can be set to any of Session, Exhibitor, or Speaker to specify the kind of the item.
If both an Item ID and Item Key value are provided, the ID will supercede the external key. If a speaker is associated with multiple sessions, then one of these fields may contain a pipe-delimited (|) list of ID or external key values (the other must be empty).
- 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”, and can be different for each type of item.
Your uploaded file must still label the columns Custom1 and Custom2.